1 package org.opentrafficsim.road.gtu.lane.perception;
2
3 import java.util.Collection;
4 import java.util.Map;
5 import java.util.Set;
6
7 import org.djunits.value.vdouble.scalar.Speed;
8 import org.opentrafficsim.core.gtu.GTUException;
9 import org.opentrafficsim.core.gtu.behavioralcharacteristics.ParameterException;
10 import org.opentrafficsim.core.gtu.perception.Perception;
11 import org.opentrafficsim.core.gtu.perception.TimeStampedObject;
12 import org.opentrafficsim.core.network.LateralDirectionality;
13 import org.opentrafficsim.core.network.NetworkException;
14 import org.opentrafficsim.road.gtu.lane.LaneBasedGTU;
15 import org.opentrafficsim.road.network.lane.Lane;
16
17 /**
18 * Interface for perception in a lane-based model. The following information can be perceived:
19 * <ul>
20 * <li>maximum speed we can use at the current location; either time stamped or just the information</li>
21 * <li>forward headway and first object (e.g., GTU) in front; either time stamped or just the information</li>
22 * <li>backward headway and first object (e.g., GTU) behind; either time stamped or just the information</li>
23 * <li>accessible adjacent lanes on the left or right; either time stamped or just the information</li>
24 * <li>parallel objects (e.g., GTUa) on the left or right; either time stamped or just the information</li>
25 * <li>Objects (e.g., GTUs) in parallel, in front and behind on the left or right neighboring lane, with their headway relative
26 * to our GTU; either time stamped or just the information</li>
27 * </ul>
28 * <p>
29 * Copyright (c) 2013-2015 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
30 * BSD-style license. See <a href="http://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
31 * </p>
32 * $LastChangedDate: 2015-07-24 02:58:59 +0200 (Fri, 24 Jul 2015) $, @version $Revision: 1147 $, by $Author: averbraeck $,
33 * initial version Jan 30, 2016 <br>
34 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
35 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
36 */
37 public interface LanePerception extends Perception
38 {
39 /**
40 * Sets the GTU -- call this method before any call to the perceive() method!
41 * @param gtu the GTU for which this is the perception module
42 */
43 void setGTU(LaneBasedGTU gtu);
44
45 /**
46 * @return the gtu for which this is the perception
47 */
48 LaneBasedGTU getGTU();
49
50 /************************************************************************************************************/
51 /********************************** RETRIEVING OF THE INFORMATION *****************************************/
52 /************************************************************************************************************/
53
54 /**
55 * @return forwardHeadway, the forward headway and first object (e.g., a GTU) in front
56 */
57 Headway getForwardHeadway();
58
59 /**
60 * @return backwardHeadwayGTU, the backward headway and first object (e.g., a GTU) behind
61 */
62 Headway getBackwardHeadway();
63
64 /**
65 * @return accessibleAdjacentLanesLeft, the accessible adjacent lanes on the left
66 */
67 Map<Lane, Set<Lane>> getAccessibleAdjacentLanesLeft();
68
69 /**
70 * @return accessibleAdjacentLanesRight, the accessible adjacent lanes on the right
71 */
72 Map<Lane, Set<Lane>> getAccessibleAdjacentLanesRight();
73
74 /**
75 * @param lateralDirection the direction to return the accessible adjacent lane map for
76 * @return the accessible adjacent lane map for the given direction
77 */
78 Map<Lane, Set<Lane>> accessibleAdjacentLaneMap(LateralDirectionality lateralDirection);
79
80 /**
81 * @return neighboringHeadwaysLeft, the objects (e.g., GTUs) in parallel, in front and behind on the left neighboring lane,
82 * with their headway relative to our GTU, and information about the status of the adjacent objects
83 */
84 Collection<Headway> getNeighboringHeadwaysLeft();
85
86 /**
87 * @return neighboringHeadwaysRight, the objects (e.g., GTUs) in parallel, in front and behind on the right neighboring
88 * lane, with their headway relative to our GTU, and information about the status of the adjacent objects
89 */
90 Collection<Headway> getNeighboringHeadwaysRight();
91
92 /**
93 * @param lateralDirection the direction to return the parallel headway collection for
94 * @return the the objects (e.g., GTUs) in parallel, in front and behind for the lane in the given direction, with their
95 * headway relative to our GTU, and information about the status of the adjacent objects
96 */
97 Collection<Headway> getNeighboringHeadways(LateralDirectionality lateralDirection);
98
99 /**
100 * @return parallelHeadwaysLeft, the parallel objects (e.g., GTUs) on the left, with information about their status and
101 * parallel overlap with our GTU.
102 */
103 Collection<Headway> getParallelHeadwaysLeft();
104
105 /**
106 * @return parallelHeadwaysRight, the parallel objects (e.g., GTUs) on the right, with information about their status and
107 * parallel overlap with our GTU.
108 */
109 Collection<Headway> getParallelHeadwaysRight();
110
111 /**
112 * @param lateralDirection the direction to return the neighboring headway collection for
113 * @return the the parallel objects (e.g., GTUs) for the given direction, with information about their status and parallel
114 * overlap with our GTU.
115 */
116 Collection<Headway> getParallelHeadways(LateralDirectionality lateralDirection);
117
118 /**
119 * @return speedLimit
120 */
121 Speed getSpeedLimit();
122
123 /************************************************************************************************************/
124 /********************************** RETRIEVING TIMESTAMPED INFORMATION ************************************/
125 /************************************************************************************************************/
126
127 /**
128 * @return TimeStamped forwardHeadway, the forward headway and first object (e.g., a GTU) in front
129 */
130 TimeStampedObject<Headway> getTimeStampedForwardHeadway();
131
132 /**
133 * @return TimeStamped backwardHeadwayGTU, the backward headway and first object (e.g., a GTU) behind
134 */
135 TimeStampedObject<Headway> getTimeStampedBackwardHeadway();
136
137 /**
138 * @return TimeStamped accessibleAdjacentLanesLeft, the accessible adjacent lanes on the left
139 */
140 TimeStampedObject<Map<Lane, Set<Lane>>> getTimeStampedAccessibleAdjacentLanesLeft();
141
142 /**
143 * @return TimeStamped accessibleAdjacentLanesRight, the accessible adjacent lanes on the right
144 */
145 TimeStampedObject<Map<Lane, Set<Lane>>> getTimeStampedAccessibleAdjacentLanesRight();
146
147 /**
148 * @return TimeStamped neighboringHeadwaysLeft, the objects (e.g., GTUs) in parallel, in front and behind on the left
149 * neighboring lane, with their headway relative to our GTU, and information about the status of the adjacent
150 * objects
151 */
152 TimeStampedObject<Collection<Headway>> getTimeStampedNeighboringHeadwaysLeft();
153
154 /**
155 * @return TimeStamped neighboringHeadwaysRight, the objects (e.g., GTUs) in parallel, in front and behind on the right
156 * neighboring lane, with their headway relative to our GTU, and information about the status of the adjacent
157 * objects
158 */
159 TimeStampedObject<Collection<Headway>> getTimeStampedNeighboringHeadwaysRight();
160
161 /**
162 * @return TimeStamped parallelHeadwaysLeft, the parallel objects (e.g., GTUs) on the left, with information about their
163 * status and parallel overlap with our GTU.
164 */
165 TimeStampedObject<Collection<Headway>> getTimeStampedParallelHeadwaysLeft();
166
167 /**
168 * @return TimeStamped parallelHeadwaysRight, the parallel objects (e.g., GTUs) on the right, with information about their
169 * status and parallel overlap with our GTU.
170 */
171 TimeStampedObject<Collection<Headway>> getTimeStampedParallelHeadwaysRight();
172
173 /**
174 * @return TimeStamped speedLimit
175 */
176 TimeStampedObject<Speed> getTimeStampedSpeedLimit();
177
178 /************************************************************************************************************/
179 /********************************** UPDATING OF THE INFORMATION *********************************************/
180 /************************************************************************************************************/
181
182 /**
183 * Update who's in front of us and how far away the nearest object (e.g., a GTU) is.
184 * @throws GTUException when the GTU was not initialized yet.
185 * @throws NetworkException when the headway cannot be determined for this GTU, usually due to routing problems.
186 * @throws ParameterException when there is a parameter problem, e.g., retrieving the forwardHeadwayDistance.
187 */
188 void updateForwardHeadway() throws GTUException, NetworkException, ParameterException;
189
190 /**
191 * Update who's behind us and how far away the nearest object (e.g., a GTU) is.
192 * @throws GTUException when the GTU was not initialized yet.
193 * @throws NetworkException when the headway cannot be determined for this GTU, usually due to routing problems.
194 * @throws ParameterException when there is a parameter problem, e.g., retrieving the backwardHeadwayDistance.
195 */
196 void updateBackwardHeadway() throws GTUException, NetworkException, ParameterException;
197
198 /**
199 * Build a set of Lanes that is adjacent to the given lane that this GTU can enter, for the left lateral direction.
200 * @throws GTUException when the GTU was not initialized yet.
201 */
202 void updateAccessibleAdjacentLanesLeft() throws GTUException;
203
204 /**
205 * Build a set of Lanes that is adjacent to the given lane that this GTU can enter, for the left lateral direction.
206 * @throws GTUException when the GTU was not initialized yet.
207 */
208 void updateAccessibleAdjacentLanesRight() throws GTUException;
209
210 /**
211 * Update the information about the objects (e.g., GTUs) parallel to our GTU on the left side.
212 * @throws GTUException when the GTU was not initialized yet.
213 */
214 void updateParallelHeadwaysLeft() throws GTUException;
215
216 /**
217 * Update the information about the objects (e.g., GTUs) parallel to our GTU on the right side.
218 * @throws GTUException when the GTU was not initialized yet.
219 */
220 void updateParallelHeadwaysRight() throws GTUException;
221
222 /**
223 * Update the information about the objects (e.g., GTUs) left of our GTU, and behind us or ahead on the left hand side.
224 * @throws GTUException when the GTU was not initialized yet.
225 * @throws NetworkException when there is an inconsistency in the lanes on this network
226 * @throws ParameterException when there is a parameter problem.
227 */
228 void updateLaneTrafficLeft() throws GTUException, NetworkException, ParameterException;
229
230 /**
231 * Update the information about the objects (e.g., GTUs) right of our GTU, and behind us or ahead on the left hand side.
232 * @throws GTUException when the GTU was not initialized yet.
233 * @throws NetworkException when there is an inconsistency in the lanes on this network
234 * @throws ParameterException when there is a parameter problem.
235 */
236 void updateLaneTrafficRight() throws GTUException, NetworkException, ParameterException;
237
238 /**
239 * Update the perceived speed limit.
240 * @throws NetworkException when the speed limit for a GTU type cannot be retreived from the network.
241 * @throws GTUException when the GTU was not initialized yet.
242 */
243 void updateSpeedLimit() throws GTUException, NetworkException;
244
245 }