1 package org.opentrafficsim.road.gtu.lane.perception.categories.neighbors;
2
3 import java.util.SortedSet;
4
5 import org.opentrafficsim.base.parameters.ParameterException;
6 import org.opentrafficsim.core.network.LateralDirectionality;
7 import org.opentrafficsim.road.gtu.lane.LaneBasedGTU;
8 import org.opentrafficsim.road.gtu.lane.perception.PerceptionCollectable;
9 import org.opentrafficsim.road.gtu.lane.perception.RelativeLane;
10 import org.opentrafficsim.road.gtu.lane.perception.categories.LaneBasedPerceptionCategory;
11 import org.opentrafficsim.road.gtu.lane.perception.headway.HeadwayGTU;
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 NeighborsPerception extends LaneBasedPerceptionCategory
24 {
25
26 /**
27 * Set of leaders on a lane, which is usually 0 or 1, but possibly more in case of a downstream split with no intermediate
28 * 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
29 * 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
30 * splits close to one another, the returned set may contain even more than 2 leaders. Leaders are sorted by headway value.
31 *
32 * <pre>
33 * | |
34 * _________/B/_____
35 * _ _?_ _ _~_ _C_ _
36 * _ _A_ _ _ _ _ _ _
37 * _________________
38 * </pre>
39 *
40 * <b>Only vehicles who's rear is beyond the own front are considered, no alongside vehicles.</b><br>
41 * <br>
42 * @param lat LateralDirectionality; LEFT or RIGHT
43 * @return list of followers on a lane
44 * @throws ParameterException if parameter is not defined
45 * @throws NullPointerException if {@code lat} is {@code null}
46 * @throws IllegalArgumentException if {@code lat} is {@code NONE}
47 */
48 SortedSet<HeadwayGTU> getFirstLeaders(LateralDirectionality lat)
49 throws ParameterException, NullPointerException, IllegalArgumentException;
50
51 /**
52 * Set of followers on a lane, which is usually 0 or 1, but possibly more in case of an upstream merge with no intermediate
53 * 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
54 * it's safe to do so. In case of multiple merges close to one another, the returned set may contain even more than 2
55 * followers. Followers are sorted by tailway value.
56 *
57 * <pre>
58 * | |
59 * |C|
60 * ________\ \______
61 * _ _B_|_ _ _ _ _?_
62 * _ _ _|_ _ _ _ _A_
63 * _____|___________
64 * </pre>
65 *
66 * <b>Only vehicles who's front is before the own rear are considered, no alongside vehicles.</b><br>
67 * <br>
68 * @param lat LateralDirectionality; LEFT or RIGHT
69 * @return list of followers on a lane
70 * @throws ParameterException if parameter is not defined
71 * @throws NullPointerException if {@code lat} is {@code null}
72 * @throws IllegalArgumentException if {@code lat} is {@code NONE}
73 */
74 SortedSet<HeadwayGTU> getFirstFollowers(LateralDirectionality lat)
75 throws ParameterException, NullPointerException, IllegalArgumentException;
76
77 /**
78 * Whether there is a GTU alongside, i.e. with overlap, in an adjacent lane.
79 * @param lat LateralDirectionality; LEFT or RIGHT
80 * @return whether there is a GTU alongside, i.e. with overlap, in an adjacent lane
81 * @throws ParameterException if parameter is not defined
82 * @throws NullPointerException if {@code lat} is {@code null}
83 * @throws IllegalArgumentException if {@code lat} is {@code NONE}
84 */
85 boolean isGtuAlongside(LateralDirectionality lat) throws ParameterException, NullPointerException, IllegalArgumentException;
86
87 /**
88 * Set of leaders on a lane, including adjacent GTU's who's FRONT is ahead of the own vehicle FRONT. Leaders are sorted by
89 * headway value.
90 * @param lane RelativeLane; relative lateral lane
91 * @return set of leaders on a lane, including adjacent GTU's who's FRONT is ahead of the own vehicle FRONT
92 */
93 PerceptionCollectable<HeadwayGTU, LaneBasedGTU> getLeaders(RelativeLane lane);
94
95 /**
96 * Set of followers on a lane, including adjacent GTU's who's FRONT is back of the own vehicle FRONT. Follower are are
97 * sorted by distance.
98 * @param lane RelativeLane; relative lateral lane
99 * @return set of followers on a lane, including adjacent GTU's who's FRONT is back of the own vehicle FRONT
100 */
101 PerceptionCollectable<HeadwayGTU, LaneBasedGTU> getFollowers(RelativeLane lane);
102
103 }