1 package org.opentrafficsim.road.gtu.lane.perception.categories;
2
3 import java.util.SortedSet;
4
5 import org.djunits.value.vdouble.scalar.Length;
6 import org.opentrafficsim.base.parameters.ParameterException;
7 import org.opentrafficsim.core.gtu.GTUException;
8 import org.opentrafficsim.core.network.LateralDirectionality;
9 import org.opentrafficsim.road.gtu.lane.perception.InfrastructureLaneChangeInfo;
10 import org.opentrafficsim.road.gtu.lane.perception.RelativeLane;
11 import org.opentrafficsim.road.network.speed.SpeedLimitProspect;
12
13 /**
14 * <p>
15 * Copyright (c) 2013-2019 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
16 * BSD-style license. See <a href="http://opentrafficsim.org/node/13">OpenTrafficSim License</a>.
17 * <p>
18 * @version $Revision$, $LastChangedDate$, by $Author$, initial version 14 feb. 2017 <br>
19 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
20 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
21 * @author <a href="http://www.transport.citg.tudelft.nl">Wouter Schakel</a>
22 */
23 public interface InfrastructurePerception extends LaneBasedPerceptionCategory
24 {
25
26 /**
27 * Updates the infrastructural lane change info. It starts at the given lane and moves downstream over the network. Whenever
28 * a point is encountered where lane changes are required, this information is saved.
29 * @param lane RelativeLane; relative lateral lane
30 * @throws GTUException if the GTU was not initialized or if the lane is not in the cross section
31 * @throws ParameterException if a parameter is not defined
32 */
33 void updateInfrastructureLaneChangeInfo(RelativeLane lane) throws GTUException, ParameterException;
34
35 /**
36 * Updates the speed limit prospect.
37 * @param lane RelativeLane; relative lateral lane
38 * @throws GTUException if the GTU was not initialized or if the lane is not in the cross section
39 * @throws ParameterException if a parameter is not defined
40 */
41 void updateSpeedLimitProspect(RelativeLane lane) throws GTUException, ParameterException;
42
43 /**
44 * Updates the distance over which lane changes remains legally possible.
45 * @param lane RelativeLane; lane from which the lane change possibility is requested
46 * @param lat LateralDirectionality; LEFT or RIGHT, null not allowed
47 * @throws GTUException if the GTU was not initialized or if the lane is not in the cross section
48 * @throws ParameterException if a parameter is not defined
49 */
50 void updateLegalLaneChangePossibility(RelativeLane lane, LateralDirectionality lat) throws GTUException, ParameterException;
51
52 /**
53 * Updates the distance over which lane changes remains physically possible.
54 * @param lane RelativeLane; lane from which the lane change possibility is requested
55 * @param lat LateralDirectionality; LEFT or RIGHT, null not allowed
56 * @throws GTUException if the GTU was not initialized or if the lane is not in the cross section
57 * @throws ParameterException if a parameter is not defined
58 */
59 void updatePhysicalLaneChangePossibility(RelativeLane lane, LateralDirectionality lat)
60 throws GTUException, ParameterException;
61
62 /**
63 * Updates a set of relative lanes representing the cross section. This set consists of all lanes on the current link, and
64 * an additional lane on the left and/or right side in case of a merge that is sufficiently nearby.
65 * @throws GTUException if the GTU was not initialized
66 * @throws ParameterException if a parameter is not defined
67 */
68 void updateCrossSection() throws GTUException, ParameterException;
69
70 /**
71 * Returns infrastructure lane change info of a lane. A set is returned as multiple points may force lane changes. Which
72 * point is considered most critical is a matter of driver interpretation and may change over time. This is shown below.
73 * Suppose vehicle A needs to take the off-ramp, and that behavior is that the minimum distance per required lane change
74 * determines how critical it is. First, 400m before the lane-drop, the off-ramp is critical. 300m downstream, the lane-drop
75 * is critical. Info is sorted by distance, closest first.
76 *
77 * <pre>
78 * _______
79 * _ _A_ _\_________
80 * _ _ _ _ _ _ _ _ _
81 * _________ _ _ ___
82 * \_______
83 * (-) Lane-drop: 1 lane change in 400m (400m per lane change)
84 * (--------) Off-ramp: 3 lane changes in 900m (300m per lane change, critical)
85 *
86 * (-) Lane-drop: 1 lane change in 100m (100m per lane change, critical)
87 * (--------) Off-ramp: 3 lane changes in 600m (200m per lane change)
88 * </pre>
89 *
90 * @param lane RelativeLane; relative lateral lane
91 * @return infrastructure lane change info of a lane
92 */
93 SortedSet<InfrastructureLaneChangeInfo> getInfrastructureLaneChangeInfo(RelativeLane lane);
94
95 /**
96 * Returns the prospect for speed limits on a lane (dynamic speed limits may vary between lanes).
97 * @param lane RelativeLane; relative lateral lane
98 * @return prospect for speed limits on a lane
99 */
100 SpeedLimitProspect getSpeedLimitProspect(RelativeLane lane);
101
102 /**
103 * Returns the distance over which a lane change remains legally possible. Negative values indicate the distance over which
104 * a lane change is legally not possible.
105 * @param fromLane RelativeLane; lane from which the lane change possibility is requested
106 * @param lat LateralDirectionality; LEFT or RIGHT, null not allowed
107 * @return distance over which a lane change remains possible
108 * @throws NullPointerException if {@code lat == null}
109 */
110 Length getLegalLaneChangePossibility(RelativeLane fromLane, LateralDirectionality lat);
111
112 /**
113 * Returns the distance over which a lane change remains physically possible. Negative values indicate the distance over
114 * which a lane change is physically not possible.
115 * @param fromLane RelativeLane; lane from which the lane change possibility is requested
116 * @param lat LateralDirectionality; LEFT or RIGHT, null not allowed
117 * @return distance over which a lane change remains possible
118 * @throws NullPointerException if {@code lat == null}
119 */
120 Length getPhysicalLaneChangePossibility(RelativeLane fromLane, LateralDirectionality lat);
121
122 /**
123 * Returns a set of relative lanes representing the cross section. Lanes are sorted left to right.
124 * @return set of relative lanes representing the cross section
125 */
126 SortedSet<RelativeLane> getCrossSection();
127
128 /** {@inheritDoc} */
129 @Override
130 default void updateAll() throws GTUException, ParameterException
131 {
132 updateCrossSection();
133 for (RelativeLane lane : getCrossSection())
134 {
135 updateInfrastructureLaneChangeInfo(lane);
136 updateSpeedLimitProspect(lane);
137 updateLegalLaneChangePossibility(lane, LateralDirectionality.LEFT);
138 updateLegalLaneChangePossibility(lane, LateralDirectionality.RIGHT);
139 updatePhysicalLaneChangePossibility(lane, LateralDirectionality.LEFT);
140 updatePhysicalLaneChangePossibility(lane, LateralDirectionality.RIGHT);
141 }
142 }
143
144 }