1 package org.opentrafficsim.road.gtu.lane.perception.categories;
2
3 import java.util.Collection;
4 import java.util.Map;
5 import java.util.Set;
6
7 import org.djunits.value.vdouble.scalar.Length;
8 import org.djunits.value.vdouble.scalar.Speed;
9 import org.opentrafficsim.base.parameters.ParameterException;
10 import org.opentrafficsim.core.gtu.GTUException;
11 import org.opentrafficsim.core.network.LateralDirectionality;
12 import org.opentrafficsim.core.network.NetworkException;
13 import org.opentrafficsim.road.gtu.lane.perception.headway.Headway;
14 import org.opentrafficsim.road.gtu.lane.tactical.LanePathInfo;
15 import org.opentrafficsim.road.network.lane.Lane;
16
17 /**
18 * Default perception category.
19 * <p>
20 * Copyright (c) 2013-2019 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
21 * BSD-style license. See <a href="http://opentrafficsim.org/node/13">OpenTrafficSim License</a>.
22 * <p>
23 * @version $Revision$, $LastChangedDate$, by $Author$, initial version 14 feb. 2017 <br>
24 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
25 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
26 * @author <a href="http://www.transport.citg.tudelft.nl">Wouter Schakel</a>
27 */
28 public interface DefaultSimplePerception extends LaneBasedPerceptionCategory
29 {
30
31 /**
32 * @throws GTUException when the GTU was not initialized yet.
33 * @throws NetworkException when the speed limit for a GTU type cannot be retrieved from the network.
34 * @throws ParameterException in case of not being able to retrieve parameter ParameterTypes.LOOKAHEAD
35 */
36 void updateLanePathInfo() throws GTUException, NetworkException, ParameterException;
37
38 /**
39 * Update the forward headway and first object (a GTU) in front.
40 * @throws GTUException when the GTU was not yet initialized
41 * @throws ParameterException if parameter is not defined or out of bounds
42 * @throws NetworkException in case of network exception
43 */
44 void updateForwardHeadwayGTU() throws GTUException, NetworkException, ParameterException;
45
46 /**
47 * Update the forward headway and first object (but not a GTU) in front.
48 * @throws GTUException when the GTU was not yet initialized
49 * @throws ParameterException if parameter is not defined or out of bounds
50 * @throws NetworkException in case of network exception
51 */
52 void updateForwardHeadwayObject() throws GTUException, NetworkException, ParameterException;
53
54 /**
55 * Update the backward headway and first object (e.g., a GTU) behind.
56 * @throws GTUException when the GTU was not yet initialized
57 * @throws ParameterException if parameter is not defined or out of bounds
58 * @throws NetworkException in case of network exception
59 */
60 void updateBackwardHeadway() throws GTUException, ParameterException, NetworkException;
61
62 /**
63 * Update the accessible adjacent lanes.
64 * @throws GTUException when the GTU was not yet initialized
65 */
66 default void updateAccessibleAdjacentLanes() throws GTUException
67 {
68 updateAccessibleAdjacentLanesLeft();
69 updateAccessibleAdjacentLanesRight();
70 }
71
72 /**
73 * Update the accessible adjacent lanes on the left.
74 * @throws GTUException when the GTU was not yet initialized
75 */
76 void updateAccessibleAdjacentLanesLeft() throws GTUException;
77
78 /**
79 * Update the accessible adjacent lanes on the right.
80 * @throws GTUException when the GTU was not yet initialized
81 */
82 void updateAccessibleAdjacentLanesRight() throws GTUException;
83
84 /**
85 * Update the objects (e.g., GTUs) in parallel, in front and behind on the left neighboring lane, with their headway
86 * relative to our GTU, and information about the status of the adjacent objects.
87 * @throws GTUException when the GTU was not yet initialized
88 * @throws ParameterException if parameter is not defined or out of bounds
89 * @throws NetworkException in case of network exception
90 */
91 void updateNeighboringHeadwaysLeft() throws GTUException, ParameterException, NetworkException;
92
93 /**
94 * Update the objects (e.g., GTUs) in parallel, in front and behind on the right neighboring lane, with their headway
95 * relative to our GTU, and information about the status of the adjacent objects.
96 * @throws GTUException when the GTU was not yet initialized
97 * @throws ParameterException if parameter is not defined or out of bounds
98 * @throws NetworkException in case of network exception
99 */
100 void updateNeighboringHeadwaysRight() throws GTUException, ParameterException, NetworkException;
101
102 /**
103 * Update the objects (e.g., GTUs) in parallel, in front and behind for the lane in the given direction, with their headway
104 * relative to our GTU, and information about the status of the adjacent objects.
105 * @param lateralDirection LateralDirectionality; the direction to update the parallel headway collection for
106 * @throws GTUException when the GTU was not yet initialized
107 * @throws ParameterException if parameter is not defined or out of bounds
108 * @throws NetworkException in case of network exception
109 */
110 void updateNeighboringHeadways(LateralDirectionality lateralDirection)
111 throws GTUException, ParameterException, NetworkException;
112
113 /**
114 * Update the parallel objects (e.g., GTUs) on the left, with information about their status and parallel overlap with our
115 * GTU.
116 * @throws GTUException when the GTU was not yet initialized
117 */
118 void updateParallelHeadwaysLeft() throws GTUException;
119
120 /**
121 * Update the parallel objects (e.g., GTUs) on the right, with information about their status and parallel overlap with our
122 * GTU.
123 * @throws GTUException when the GTU was not yet initialized
124 */
125 void updateParallelHeadwaysRight() throws GTUException;
126
127 /**
128 * Update the parallel objects (e.g., GTUs) for the given direction, with information about their status and parallel
129 * overlap with our GTU.
130 * @param lateralDirection LateralDirectionality; the direction to return the neighboring headway collection for
131 * @throws GTUException when the GTU was not yet initialized
132 */
133 void updateParallelHeadways(LateralDirectionality lateralDirection) throws GTUException;
134
135 /**
136 * Update speedLimit.
137 * @throws GTUException when the GTU was not yet initialized
138 * @throws NetworkException in case of network exception
139 */
140 void updateSpeedLimit() throws GTUException, NetworkException;
141
142 /**
143 * Retrieve the last perceived lane path info.
144 * @return LanePathInfo
145 */
146 LanePathInfo getLanePathInfo();
147
148 /**
149 * @return forwardHeadway, the forward headway and first object (GTU) in front
150 */
151 Headway getForwardHeadwayGTU();
152
153 /**
154 * @return forwardHeadway, the forward headway and first object (not a GTU) in front
155 */
156 Headway getForwardHeadwayObject();
157
158 /**
159 * @return backwardHeadwayGTU, the backward headway and first object (e.g., a GTU) behind
160 */
161 Headway getBackwardHeadway();
162
163 /**
164 * @return accessibleAdjacentLanesLeft, the accessible adjacent lanes on the left
165 */
166 Map<Lane, Set<Lane>> getAccessibleAdjacentLanesLeft();
167
168 /**
169 * @return accessibleAdjacentLanesRight, the accessible adjacent lanes on the right
170 */
171 Map<Lane, Set<Lane>> getAccessibleAdjacentLanesRight();
172
173 /**
174 * @param lateralDirection LateralDirectionality; the direction to return the accessible adjacent lane map for
175 * @return the accessible adjacent lane map for the given direction
176 */
177 Map<Lane, Set<Lane>> getAccessibleAdjacentLanes(LateralDirectionality lateralDirection);
178
179 /**
180 * @return neighboringHeadwaysLeft, the objects (e.g., GTUs) in parallel, in front and behind on the left neighboring lane,
181 * with their headway relative to our GTU, and information about the status of the adjacent objects
182 */
183 Collection<Headway> getNeighboringHeadwaysLeft();
184
185 /**
186 * @return neighboringHeadwaysRight, the objects (e.g., GTUs) in parallel, in front and behind on the right neighboring
187 * lane, with their headway relative to our GTU, and information about the status of the adjacent objects
188 */
189 Collection<Headway> getNeighboringHeadwaysRight();
190
191 /**
192 * @param lateralDirection LateralDirectionality; the direction to return the parallel headway collection for
193 * @return the the objects (e.g., GTUs) in parallel, in front and behind for the lane in the given direction, with their
194 * headway relative to our GTU, and information about the status of the adjacent objects
195 */
196 Collection<Headway> getNeighboringHeadways(LateralDirectionality lateralDirection);
197
198 /**
199 * @return parallelHeadwaysLeft, the parallel objects (e.g., GTUs) on the left, with information about their status and
200 * parallel overlap with our GTU.
201 */
202 Collection<Headway> getParallelHeadwaysLeft();
203
204 /**
205 * @return parallelHeadwaysRight, the parallel objects (e.g., GTUs) on the right, with information about their status and
206 * parallel overlap with our GTU.
207 */
208 Collection<Headway> getParallelHeadwaysRight();
209
210 /**
211 * @param lateralDirection LateralDirectionality; the direction to return the neighboring headway collection for
212 * @return the the parallel objects (e.g., GTUs) for the given direction, with information about their status and parallel
213 * overlap with our GTU.
214 */
215 Collection<Headway> getParallelHeadways(LateralDirectionality lateralDirection);
216
217 /**
218 * @return speedLimit
219 */
220 Speed getSpeedLimit();
221
222 /** {@inheritDoc} */
223 @Override
224 default void updateAll() throws GTUException, ParameterException, NetworkException
225 {
226 updateLanePathInfo();
227 updateForwardHeadwayGTU();
228 updateForwardHeadwayObject();
229 updateBackwardHeadway();
230 updateAccessibleAdjacentLanesLeft();
231 updateAccessibleAdjacentLanesRight();
232 updateNeighboringHeadwaysLeft();
233 updateNeighboringHeadwaysRight();
234 updateParallelHeadwaysLeft();
235 updateParallelHeadwaysRight();
236 updateSpeedLimit();
237 }
238
239 /**
240 * Determine whether there is a lane to the left or to the right of this lane, which is accessible from this lane, or null
241 * if no lane could be found. The method takes the LongitidinalDirectionality of the lane into account. In other words, if
242 * we drive FORWARD and look for a lane on the LEFT, and there is a lane but the Directionality of that lane is not FORWARD
243 * or BOTH, null will be returned.<br>
244 * A lane is called adjacent to another lane if the lateral edges are not more than a delta distance apart. This means that
245 * a lane that <i>overlaps</i> with another lane is <b>not</b> returned as an adjacent lane. <br>
246 * The algorithm also looks for RoadMarkerAcross elements between the lanes to determine the lateral permeability for a GTU.
247 * A RoadMarkerAcross is seen as being between two lanes if its center line is not more than delta distance from the
248 * relevant lateral edges of the two adjacent lanes. <br>
249 * When there are multiple lanes that are adjacent, which could e.g. be the case if an overlapping tram lane and a car lane
250 * are adjacent to the current lane, the widest lane that best matches the GTU accessibility of the provided GTUType is
251 * returned. <br>
252 * <b>Note:</b> LEFT is seen as a negative lateral direction, RIGHT as a positive lateral direction. <br>
253 * FIXME In other places in OTS LEFT is positive (and RIGHT is negative). This should be made more consistent.
254 * @param currentLane Lane; the lane to look for the best accessible adjacent lane
255 * @param lateralDirection LateralDirectionality; the direction (LEFT, RIGHT) to look at
256 * @param longitudinalPosition Length; the position of the GTU along <cite>currentLane</cite>
257 * @return the lane if it is accessible, or null if there is no lane, it is not accessible, or the driving direction does
258 * not match.
259 */
260 Lane bestAccessibleAdjacentLane(Lane currentLane, LateralDirectionality lateralDirection, Length longitudinalPosition);
261
262 }