1 package org.opentrafficsim.road.gtu.lane.perceptionold;
2
3 import java.util.Collection;
4 import java.util.Map;
5 import java.util.Set;
6 import java.util.SortedSet;
7
8 import org.djunits.value.vdouble.scalar.Length;
9 import org.djunits.value.vdouble.scalar.Speed;
10 import org.opentrafficsim.core.gtu.GTUException;
11 import org.opentrafficsim.core.gtu.behavioralcharacteristics.ParameterException;
12 import org.opentrafficsim.core.gtu.perception.Perception;
13 import org.opentrafficsim.core.gtu.perception.TimeStampedObject;
14 import org.opentrafficsim.core.network.LateralDirectionality;
15 import org.opentrafficsim.core.network.NetworkException;
16 import org.opentrafficsim.road.gtu.lane.LaneBasedGTU;
17 import org.opentrafficsim.road.gtu.lane.perception.InfrastructureLaneChangeInfo;
18 import org.opentrafficsim.road.gtu.lane.perception.RelativeLane;
19 import org.opentrafficsim.road.gtu.lane.perception.headway.AbstractHeadwayGTU;
20 import org.opentrafficsim.road.gtu.lane.perception.headway.Headway;
21 import org.opentrafficsim.road.gtu.lane.perception.headway.HeadwayConflict;
22 import org.opentrafficsim.road.gtu.lane.perception.headway.HeadwayTrafficLight;
23 import org.opentrafficsim.road.network.lane.Lane;
24 import org.opentrafficsim.road.network.speed.SpeedLimitProspect;
25
26 /**
27 * Interface for perception in a lane-based model. The following information can be perceived:
28 * <ul>
29 * <li>maximum speed we can use at the current location; either time stamped or just the information</li>
30 * <li>forward headway and first object (e.g., GTU) in front; either time stamped or just the information</li>
31 * <li>backward headway and first object (e.g., GTU) behind; either time stamped or just the information</li>
32 * <li>accessible adjacent lanes on the left or right; either time stamped or just the information</li>
33 * <li>parallel objects (e.g., GTUa) on the left or right; either time stamped or just the information</li>
34 * <li>Objects (e.g., GTUs) in parallel, in front and behind on the left or right neighboring lane, with their headway relative
35 * to our GTU; either time stamped or just the information</li>
36 * </ul>
37 * <p>
38 * Copyright (c) 2013-2016 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
39 * BSD-style license. See <a href="http://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
40 * </p>
41 * $LastChangedDate: 2015-07-24 02:58:59 +0200 (Fri, 24 Jul 2015) $, @version $Revision: 1147 $, by $Author: averbraeck $,
42 * initial version Jan 30, 2016 <br>
43 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
44 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
45 */
46 public interface LanePerception extends Perception
47 {
48
49 /**
50 * @return the gtu for which this is the perception
51 */
52 LaneBasedGTU getGtu();
53
54 /************************************************************************************************************/
55 /********************************** RETRIEVING OF THE INFORMATION *****************************************/
56 /************************************************************************************************************/
57
58 /**
59 * @return forwardHeadway, the forward headway and first object (e.g., a GTU) in front
60 */
61 Headway getForwardHeadway();
62
63 /**
64 * @return backwardHeadwayGTU, the backward headway and first object (e.g., a GTU) behind
65 */
66 Headway getBackwardHeadway();
67
68 /**
69 * @return accessibleAdjacentLanesLeft, the accessible adjacent lanes on the left
70 */
71 Map<Lane, Set<Lane>> getAccessibleAdjacentLanesLeft();
72
73 /**
74 * @return accessibleAdjacentLanesRight, the accessible adjacent lanes on the right
75 */
76 Map<Lane, Set<Lane>> getAccessibleAdjacentLanesRight();
77
78 /**
79 * @param lateralDirection the direction to return the accessible adjacent lane map for
80 * @return the accessible adjacent lane map for the given direction
81 */
82 Map<Lane, Set<Lane>> accessibleAdjacentLaneMap(LateralDirectionality lateralDirection);
83
84 /**
85 * @return neighboringHeadwaysLeft, the objects (e.g., GTUs) in parallel, in front and behind on the left neighboring lane,
86 * with their headway relative to our GTU, and information about the status of the adjacent objects
87 */
88 Collection<Headway> getNeighboringHeadwaysLeft();
89
90 /**
91 * @return neighboringHeadwaysRight, the objects (e.g., GTUs) in parallel, in front and behind on the right neighboring
92 * lane, with their headway relative to our GTU, and information about the status of the adjacent objects
93 */
94 Collection<Headway> getNeighboringHeadwaysRight();
95
96 /**
97 * @param lateralDirection the direction to return the parallel headway collection for
98 * @return the the objects (e.g., GTUs) in parallel, in front and behind for the lane in the given direction, with their
99 * headway relative to our GTU, and information about the status of the adjacent objects
100 */
101 Collection<Headway> getNeighboringHeadways(LateralDirectionality lateralDirection);
102
103 /**
104 * @return parallelHeadwaysLeft, the parallel objects (e.g., GTUs) on the left, with information about their status and
105 * parallel overlap with our GTU.
106 */
107 Collection<Headway> getParallelHeadwaysLeft();
108
109 /**
110 * @return parallelHeadwaysRight, the parallel objects (e.g., GTUs) on the right, with information about their status and
111 * parallel overlap with our GTU.
112 */
113 Collection<Headway> getParallelHeadwaysRight();
114
115 /**
116 * @param lateralDirection the direction to return the neighboring headway collection for
117 * @return the the parallel objects (e.g., GTUs) for the given direction, with information about their status and parallel
118 * overlap with our GTU.
119 */
120 Collection<Headway> getParallelHeadways(LateralDirectionality lateralDirection);
121
122 /**
123 * @return speedLimit
124 */
125 Speed getSpeedLimit();
126
127 /**********************/
128 /** Surrounding GTUs **/
129 /**********************/
130
131 /**
132 * Set of leaders on a lane, which is usually 0 or 1, but possibly more in case of a downstream split with no intermediate
133 * GTU. This is shown below. Suppose A needs to go straight. If A considers a lane change to the left, both GTUs B (who's
134 * tail ~ is still on the straight lane) and C need to be considered for whether it's safe to do so. In case of multiple
135 * splits close to one another, the returned set may contain even more than 2 leaders. Leaders are sorted by headway value.
136 *
137 * <pre>
138 * | |
139 * _________/B/_____
140 * _ _?_ _ _~_ _C_ _
141 * _ _A_ _ _ _ _ _ _
142 * _________________
143 * </pre>
144 * @param lat LEFT, null (current) or RIGHT
145 * @return list of followers on a lane
146 */
147 SortedSet<AbstractHeadwayGTU> getFirstLeaders(LateralDirectionality lat);
148
149 /**
150 * Set of followers on a lane, which is usually 0 or 1, but possibly more in case of an upstream merge with no intermediate
151 * GTU. This is shown below. If A considers a lane change to the left, both GTUs B and C need to be considered for whether
152 * it's safe to do so. In case of multiple merges close to one another, the returned set may contain even more than 2
153 * followers. Followers are sorted by tailway value.
154 *
155 * <pre>
156 * | |
157 * |C|
158 * ________\ \______
159 * _ _B_|_ _ _ _ _?_
160 * _ _ _|_ _ _ _ _A_
161 * _____|___________
162 * </pre>
163 * @param lat LEFT, null (current) or RIGHT
164 * @return list of followers on a lane
165 */
166 SortedSet<AbstractHeadwayGTU> getFirstFollowers(LateralDirectionality lat);
167
168 /**
169 * Whether there is a GTU alongside, i.e. with overlap, in an adjacent lane.
170 * @param lat LEFT or RIGHT, null not allowed
171 * @return whether there is a GTU alongside, i.e. with overlap, in an adjacent lane
172 * @throws NullPointerException if {@code lat == null}
173 */
174 boolean existsGtuAlongside(LateralDirectionality lat);
175
176 /**
177 * Set of leaders on a lane, including adjacent GTU's who's FRONT is ahead of the own vehicle FRONT. Leaders are sorted by
178 * headway value.
179 * @param lane relative lateral lane
180 * @return set of leaders on a lane, including adjacent GTU's who's FRONT is ahead of the own vehicle FRONT
181 */
182 SortedSet<AbstractHeadwayGTU> getLeaders(RelativeLane lane);
183
184 /**
185 * Set of followers on a lane, including adjacent GTU's who's REAR is back of the own vehicle REAR. Follower are are sorted
186 * by tailway value.
187 * @param lane relative lateral lane
188 * @return set of followers on a lane, including adjacent GTU's who's REAR is back of the own vehicle REAR
189 */
190 SortedSet<AbstractHeadwayGTU> getFollowers(RelativeLane lane);
191
192 /********************/
193 /** Infrastructure **/
194 /********************/
195
196 /**
197 * Returns infrastructure lane change info of a lane. A set is returned as multiple points may force lane changes. Which
198 * point is considered most critical is a matter of driver interpretation and may change over time. This is shown below.
199 * Suppose vehicle A needs to take the off-ramp, and that behavior is that the minimum distance per required lane change
200 * determines how critical it is. First, 400m before the lane-drop, the off-ramp is critical. 300m downstream, the lane-drop
201 * is critical. Info is sorted by distance, closest first.
202 *
203 * <pre>
204 * _______
205 * _ _A_ _\_________
206 * _ _ _ _ _ _ _ _ _
207 * _________ _ _ ___
208 * \_______
209 * (-) Lane-drop: 1 lane change in 400m (400m per lane change)
210 * (--------) Off-ramp: 3 lane changes in 900m (300m per lane change, critical)
211 *
212 * (-) Lane-drop: 1 lane change in 100m (100m per lane change, critical)
213 * (--------) Off-ramp: 3 lane changes in 600m (200m per lane change)
214 * </pre>
215 * @param lane relative lateral lane
216 * @return infrastructure lane change info of a lane
217 */
218 SortedSet<InfrastructureLaneChangeInfo> getInfrastructureLaneChangeInfo(RelativeLane lane);
219
220 /**
221 * Split number of given infrastructure lane change info, 0 if it does not regard a split.
222 * <pre>
223 * ________________
224 * _ _ _ _ _ _ _ _____________
225 * A___.....____________.....__
226 * \______ \______ (destination of A)
227 * ^
228 * |
229 * This split provides the 1st
230 * infrastructure info on the current lane.
231 * It regards the 3rd split along the road.
232 * split number = 3
233 * </pre>
234 * @param info infrastructure lane change info
235 * @return split number of given infrastructure lane change info, 0 if it does not regard a split
236 */
237 int getSplitNumber(InfrastructureLaneChangeInfo info);
238
239 /**
240 * Returns the prospect for speed limits on a lane (dynamic speed limits may vary between lanes).
241 * @param lane relative lateral lane
242 * @return prospect for speed limits on a lane
243 */
244 SpeedLimitProspect getSpeedLimitProspect(RelativeLane lane);
245
246 /**
247 * Returns the distance over which a lane change remains legally possible.
248 * @param fromLane lane from which the lane change possibility is requested
249 * @param lat LEFT or RIGHT, null not allowed
250 * @return distance over which a lane change remains possible
251 * @throws NullPointerException if {@code lat == null}
252 */
253 Length getLegalLaneChangePossibility(RelativeLane fromLane, LateralDirectionality lat);
254
255 /**
256 * Returns the distance over which a lane change remains physically possible.
257 * @param fromLane lane from which the lane change possibility is requested
258 * @param lat LEFT or RIGHT, null not allowed
259 * @return distance over which a lane change remains possible
260 * @throws NullPointerException if {@code lat == null}
261 */
262 Length getPhysicalLaneChangePossibility(RelativeLane fromLane, LateralDirectionality lat);
263
264 /**
265 * Returns a set of relative lanes representing the current cross section. Lanes are sorted left to right.
266 * @return set of relative lanes representing the current cross section
267 */
268 SortedSet<RelativeLane> getCurrentCrossSection();
269
270 /*************************/
271 /** Perceivable objects **/
272 /*************************/
273
274 /**
275 * Returns a set of traffic lights along the route. Traffic lights are sorted by headway value.
276 * @return set of traffic lights along the route
277 */
278 SortedSet<HeadwayTrafficLight> getTrafficLights();
279
280 /**
281 * Returns a set of intersection conflicts along the route. Conflicts are sorted by headway value.
282 * @param lane relative lateral lane
283 * @return set of intersection conflicts along the route
284 */
285 SortedSet<HeadwayConflict> getIntersectionConflicts(RelativeLane lane);
286
287 /************************************************************************************************************/
288 /********************************** RETRIEVING TIMESTAMPED INFORMATION ************************************/
289 /************************************************************************************************************/
290
291 /**
292 * @return TimeStamped forwardHeadway, the forward headway and first object (e.g., a GTU) in front
293 */
294 TimeStampedObject<Headway> getTimeStampedForwardHeadway();
295
296 /**
297 * @return TimeStamped backwardHeadwayGTU, the backward headway and first object (e.g., a GTU) behind
298 */
299 TimeStampedObject<Headway> getTimeStampedBackwardHeadway();
300
301 /**
302 * @return TimeStamped accessibleAdjacentLanesLeft, the accessible adjacent lanes on the left
303 */
304 TimeStampedObject<Map<Lane, Set<Lane>>> getTimeStampedAccessibleAdjacentLanesLeft();
305
306 /**
307 * @return TimeStamped accessibleAdjacentLanesRight, the accessible adjacent lanes on the right
308 */
309 TimeStampedObject<Map<Lane, Set<Lane>>> getTimeStampedAccessibleAdjacentLanesRight();
310
311 /**
312 * @return TimeStamped neighboringHeadwaysLeft, the objects (e.g., GTUs) in parallel, in front and behind on the left
313 * neighboring lane, with their headway relative to our GTU, and information about the status of the adjacent
314 * objects
315 */
316 TimeStampedObject<Collection<Headway>> getTimeStampedNeighboringHeadwaysLeft();
317
318 /**
319 * @return TimeStamped neighboringHeadwaysRight, the objects (e.g., GTUs) in parallel, in front and behind on the right
320 * neighboring lane, with their headway relative to our GTU, and information about the status of the adjacent
321 * objects
322 */
323 TimeStampedObject<Collection<Headway>> getTimeStampedNeighboringHeadwaysRight();
324
325 /**
326 * @return TimeStamped parallelHeadwaysLeft, the parallel objects (e.g., GTUs) on the left, with information about their
327 * status and parallel overlap with our GTU.
328 */
329 TimeStampedObject<Collection<Headway>> getTimeStampedParallelHeadwaysLeft();
330
331 /**
332 * @return TimeStamped parallelHeadwaysRight, the parallel objects (e.g., GTUs) on the right, with information about their
333 * status and parallel overlap with our GTU.
334 */
335 TimeStampedObject<Collection<Headway>> getTimeStampedParallelHeadwaysRight();
336
337 /**
338 * @return TimeStamped speedLimit
339 */
340 TimeStampedObject<Speed> getTimeStampedSpeedLimit();
341
342 /**********************/
343 /** Surrounding GTUs **/
344 /**********************/
345
346 /**
347 * Set of leaders on a lane, which is usually 0 or 1, but possibly more in case of a downstream split with no intermediate
348 * GTU. This is shown below. Suppose A needs to go straight. If A considers a lane change to the left, both GTUs B (who's
349 * tail ~ is still on the straight lane) and C need to be considered for whether it's safe to do so. In case of multiple
350 * splits close to one another, the returned set may contain even more than 2 leaders. Leaders are sorted by headway value.
351 *
352 * <pre>
353 * | |
354 * _________/B/_____
355 * _ _?_ _ _~_ _C_ _
356 * _ _A_ _ _ _ _ _ _
357 * _________________
358 * </pre>
359 * @param lat LEFT, null (current) or RIGHT
360 * @return list of followers on a lane
361 */
362 TimeStampedObject<SortedSet<AbstractHeadwayGTU>> getTimeStampedFirstLeaders(LateralDirectionality lat);
363
364 /**
365 * Set of followers on a lane, which is usually 0 or 1, but possibly more in case of an upstream merge with no intermediate
366 * GTU. This is shown below. If A considers a lane change to the left, both GTUs B and C need to be considered for whether
367 * it's safe to do so. In case of multiple merges close to one another, the returned set may contain even more than 2
368 * followers. Followers are sorted by tailway value.
369 *
370 * <pre>
371 * | |
372 * |C|
373 * ________\ \______
374 * _ _B_|_ _ _ _ _?_
375 * _ _ _|_ _ _ _ _A_
376 * _____|___________
377 * </pre>
378 * @param lat LEFT, null (current) or RIGHT
379 * @return list of followers on a lane
380 */
381 TimeStampedObject<SortedSet<AbstractHeadwayGTU>> getTimeStampedFirstFollowers(LateralDirectionality lat);
382
383 /**
384 * Whether there is a GTU alongside, i.e. with overlap, in an adjacent lane.
385 * @param lat LEFT or RIGHT, null not allowed
386 * @return whether there is a GTU alongside, i.e. with overlap, in an adjacent lane
387 * @throws NullPointerException if {@code lat == null}
388 */
389 TimeStampedObject<Boolean> existsGtuAlongsideTimeStamped(LateralDirectionality lat);
390
391 /**
392 * Set of leaders on a lane, including adjacent GTU's who's FRONT is ahead of the own vehicle FRONT. Leaders are sorted by
393 * headway value.
394 * @param lane relative lateral lane
395 * @return set of leaders on a lane, including adjacent GTU's who's FRONT is ahead of the own vehicle FRONT
396 */
397 TimeStampedObject<SortedSet<AbstractHeadwayGTU>> getTimeStampedLeaders(RelativeLane lane);
398
399 /**
400 * Set of followers on a lane, including adjacent GTU's who's REAR is back of the own vehicle REAR. Follower are are sorted
401 * by tailway value.
402 * @param lane relative lateral lane
403 * @return set of followers on a lane, including adjacent GTU's who's REAR is back of the own vehicle REAR
404 */
405 TimeStampedObject<SortedSet<AbstractHeadwayGTU>> getTimeStampedFollowers(RelativeLane lane);
406
407 /********************/
408 /** Infrastructure **/
409 /********************/
410
411 /**
412 * Returns infrastructure lane change info of a lane. A set is returned as multiple points may force lane changes. Which
413 * point is considered most critical is a matter of driver interpretation and may change over time. This is shown below.
414 * Suppose vehicle A needs to take the off-ramp, and that behavior is that the minimum distance per required lane change
415 * determines how critical it is. First, 400m before the lane-drop, the off-ramp is critical. 300m downstream, the lane-drop
416 * is critical. Info is sorted by distance, closest first.
417 *
418 * <pre>
419 * _______
420 * _ _A_ _\_________
421 * _ _ _ _ _ _ _ _ _
422 * _________ _ _ ___
423 * \_______
424 * (-) Lane-drop: 1 lane change in 400m (400m per lane change)
425 * (--------) Off-ramp: 3 lane changes in 900m (300m per lane change, critical)
426 *
427 * (-) Lane-drop: 1 lane change in 100m (100m per lane change, critical)
428 * (--------) Off-ramp: 3 lane changes in 600m (200m per lane change)
429 * </pre>
430 * @param lane relative lateral lane
431 * @return infrastructure lane change info of a lane
432 */
433 TimeStampedObject<SortedSet<InfrastructureLaneChangeInfo>> getTimeStampedInfrastructureLaneChangeInfo(RelativeLane lane);
434
435 /**
436 * Split number of given infrastructure lane change info, 0 if it does not regard a split.
437 * <pre>
438 * ________________
439 * _ _ _ _ _ _ _ _____________
440 * A___.....____________.....__
441 * \______ \______ (destination of A)
442 * ^
443 * |
444 * This split provides the 1st
445 * infrastructure info on the current lane.
446 * It regards the 3rd split along the road.
447 * split number = 3
448 * </pre>
449 * @param info infrastructure lane change info
450 * @return split number of given infrastructure lane change info, 0 if it does not regard a split
451 */
452 TimeStampedObject<Integer> getTimeStampedSplitNumber(InfrastructureLaneChangeInfo info);
453
454 /**
455 * Returns the prospect for speed limits on a lane (dynamic speed limits may vary between lanes).
456 * @param lane relative lateral lane
457 * @return prospect for speed limits on a lane
458 */
459 TimeStampedObject<SpeedLimitProspect> getTimeStampedSpeedLimitProspect(RelativeLane lane);
460
461 /**
462 * Returns the distance over which a lane change remains legally possible.
463 * @param fromLane lane from which the lane change possibility is requested
464 * @param lat LEFT or RIGHT, null not allowed
465 * @return distance over which a lane change remains possible
466 * @throws NullPointerException if {@code lat == null}
467 */
468 TimeStampedObject<Length> getTimeStampedLegalLaneChangePossibility(RelativeLane fromLane, LateralDirectionality lat);
469
470 /**
471 * Returns the distance over which a lane change remains physically possible.
472 * @param fromLane lane from which the lane change possibility is requested
473 * @param lat LEFT or RIGHT, null not allowed
474 * @return distance over which a lane change remains possible
475 * @throws NullPointerException if {@code lat == null}
476 */
477 TimeStampedObject<Length> getTimeStampedPhysicalLaneChangePossibility(RelativeLane fromLane, LateralDirectionality lat);
478
479 /**
480 * Returns a set of relative lanes representing the current cross section. Lanes are sorted left to right.
481 * @return set of relative lanes representing the current cross section
482 */
483 TimeStampedObject<SortedSet<RelativeLane>> getTimeStampedCurrentCrossSection();
484
485 /*************************/
486 /** Perceivable objects **/
487 /*************************/
488
489 /**
490 * Returns a set of traffic lights along the route. Traffic lights are sorted by headway value.
491 * @return set of traffic lights along the route
492 */
493 TimeStampedObject<SortedSet<HeadwayTrafficLight>> getTimeStampedTrafficLights();
494
495 /**
496 * Returns a set of intersection conflicts along the route. Conflicts are sorted by headway value.
497 * @param lane relative lateral lane
498 * @return set of intersection conflicts along the route
499 */
500 TimeStampedObject<SortedSet<HeadwayConflict>> getTimeStampedIntersectionConflicts(RelativeLane lane);
501
502 /************************************************************************************************************/
503 /********************************** UPDATING OF THE INFORMATION *********************************************/
504 /************************************************************************************************************/
505
506 /**
507 * Update who's in front of us and how far away the nearest object (e.g., a GTU) is.
508 * @throws GTUException when the GTU was not initialized yet.
509 * @throws NetworkException when the headway cannot be determined for this GTU, usually due to routing problems.
510 * @throws ParameterException when there is a parameter problem, e.g., retrieving the forwardHeadwayDistance.
511 */
512 void updateForwardHeadway() throws GTUException, NetworkException, ParameterException;
513
514 /**
515 * Update who's behind us and how far away the nearest object (e.g., a GTU) is.
516 * @throws GTUException when the GTU was not initialized yet.
517 * @throws NetworkException when the headway cannot be determined for this GTU, usually due to routing problems.
518 * @throws ParameterException when there is a parameter problem, e.g., retrieving the backwardHeadwayDistance.
519 */
520 void updateBackwardHeadway() throws GTUException, NetworkException, ParameterException;
521
522 /**
523 * Build a set of Lanes that is adjacent to the given lane that this GTU can enter, for the left lateral direction.
524 * @throws GTUException when the GTU was not initialized yet.
525 */
526 void updateAccessibleAdjacentLanesLeft() throws GTUException;
527
528 /**
529 * Build a set of Lanes that is adjacent to the given lane that this GTU can enter, for the left lateral direction.
530 * @throws GTUException when the GTU was not initialized yet.
531 */
532 void updateAccessibleAdjacentLanesRight() throws GTUException;
533
534 /**
535 * Update the information about the objects (e.g., GTUs) parallel to our GTU on the left side.
536 * @throws GTUException when the GTU was not initialized yet.
537 */
538 void updateParallelHeadwaysLeft() throws GTUException;
539
540 /**
541 * Update the information about the objects (e.g., GTUs) parallel to our GTU on the right side.
542 * @throws GTUException when the GTU was not initialized yet.
543 */
544 void updateParallelHeadwaysRight() throws GTUException;
545
546 /**
547 * Update the information about the objects (e.g., GTUs) left of our GTU, and behind us or ahead on the left hand side.
548 * @throws GTUException when the GTU was not initialized yet.
549 * @throws NetworkException when there is an inconsistency in the lanes on this network
550 * @throws ParameterException when there is a parameter problem.
551 */
552 void updateLaneTrafficLeft() throws GTUException, NetworkException, ParameterException;
553
554 /**
555 * Update the information about the objects (e.g., GTUs) right of our GTU, and behind us or ahead on the left hand side.
556 * @throws GTUException when the GTU was not initialized yet.
557 * @throws NetworkException when there is an inconsistency in the lanes on this network
558 * @throws ParameterException when there is a parameter problem.
559 */
560 void updateLaneTrafficRight() throws GTUException, NetworkException, ParameterException;
561
562 /**
563 * Update the perceived speed limit.
564 * @throws NetworkException when the speed limit for a GTU type cannot be retreived from the network.
565 * @throws GTUException when the GTU was not initialized yet.
566 */
567 void updateSpeedLimit() throws GTUException, NetworkException;
568
569 /**********************/
570 /** Surrounding GTUs **/
571 /**********************/
572
573 /**
574 * Updates of leaders on a lane, which is usually 0 or 1, but possibly more in case of a downstream split with no intermediate
575 * GTU. This is shown below. Suppose A needs to go straight. If A considers a lane change to the left, both GTUs B (who's
576 * tail ~ is still on the straight lane) and C need to be considered for whether it's safe to do so. In case of multiple
577 * splits close to one another, the returned set may contain even more than 2 leaders. Leaders are sorted by headway value.
578 *
579 * <pre>
580 * | |
581 * _________/B/_____
582 * _ _?_ _ _~_ _C_ _
583 * _ _A_ _ _ _ _ _ _
584 * _________________
585 * </pre>
586 */
587 void updateFirstLeaders();
588
589 /**
590 * Updates of followers on a lane, which is usually 0 or 1, but possibly more in case of an upstream merge with no intermediate
591 * GTU. This is shown below. If A considers a lane change to the left, both GTUs B and C need to be considered for whether
592 * it's safe to do so. In case of multiple merges close to one another, the returned set may contain even more than 2
593 * followers. Followers are sorted by tailway value.
594 *
595 * <pre>
596 * | |
597 * |C|
598 * ________\ \______
599 * _ _B_|_ _ _ _ _?_
600 * _ _ _|_ _ _ _ _A_
601 * _____|___________
602 * </pre>
603 */
604 void updateFirstFollowers();
605
606 /**
607 * Updates whether there is a GTU alongside, i.e. with overlap, in an adjacent lane.
608 * @throws NullPointerException if {@code lat == null}
609 */
610 void updateGtuAlongside();
611
612 /**
613 * Updates set of leaders on a lane, including adjacent GTU's who's FRONT is ahead of the own vehicle FRONT. Leaders are sorted by
614 * headway value.
615 */
616 void updateLeaders();
617
618 /**
619 * Updates set of followers on a lane, including adjacent GTU's who's REAR is back of the own vehicle REAR. Follower are are sorted
620 * by tailway value.
621 */
622 void updateFollowers();
623
624 /********************/
625 /** Infrastructure **/
626 /********************/
627
628 /**
629 * Updates infrastructure lane change info of a lane. A set is returned as multiple points may force lane changes. Which
630 * point is considered most critical is a matter of driver interpretation and may change over time. This is shown below.
631 * Suppose vehicle A needs to take the off-ramp, and that behavior is that the minimum distance per required lane change
632 * determines how critical it is. First, 400m before the lane-drop, the off-ramp is critical. 300m downstream, the lane-drop
633 * is critical. Info is sorted by distance, closest first.
634 *
635 * <pre>
636 * _______
637 * _ _A_ _\_________
638 * _ _ _ _ _ _ _ _ _
639 * _________ _ _ ___
640 * \_______
641 * (-) Lane-drop: 1 lane change in 400m (400m per lane change)
642 * (--------) Off-ramp: 3 lane changes in 900m (300m per lane change, critical)
643 *
644 * (-) Lane-drop: 1 lane change in 100m (100m per lane change, critical)
645 * (--------) Off-ramp: 3 lane changes in 600m (200m per lane change)
646 * </pre>
647 */
648 void updateInfrastructureLaneChangeInfo();
649
650 /**
651 * Updates split numbers of infrastructure lane change info, 0 if it does not regard a split.
652 * <pre>
653 * ________________
654 * _ _ _ _ _ _ _ _____________
655 * A___.....____________.....__
656 * \______ \______ (destination of A)
657 * ^
658 * |
659 * This split provides the 1st
660 * infrastructure info on the current lane.
661 * It regards the 3rd split along the road.
662 * split number = 3
663 * </pre>
664 */
665 void updateSplitNumber();
666
667 /**
668 * Updates the prospect for speed limits on a lane (dynamic speed limits may vary between lanes).
669 */
670 void updateSpeedLimitProspect();
671
672 /**
673 * Updates the distance over which a lane change remains legally possible.
674 * @throws NullPointerException if {@code lat == null}
675 */
676 void updateLegalLaneChangePossibility();
677
678 /**
679 * Updates the distance over which a lane change remains physically possible.
680 * @throws NullPointerException if {@code lat == null}
681 */
682 void updatePhysicalLaneChangePossibility();
683
684 /**
685 * Updates a set of relative lanes representing the current cross section. Lanes are sorted left to right.
686 */
687 void updateCurrentCrossSection();
688
689 /*************************/
690 /** Perceivable objects **/
691 /*************************/
692
693 /**
694 * Updates a set of traffic lights along the route. Traffic lights are sorted by headway value.
695 */
696 void updateTrafficLights();
697
698 /**
699 * Updates a set of intersection conflicts along the route. Conflicts are sorted by headway value.
700 */
701 void updateIntersectionConflicts();
702
703 }