1 package org.opentrafficsim.road.gtu.lane;
2
3 import java.util.Map;
4
5 import org.djunits.value.vdouble.scalar.Acceleration;
6 import org.djunits.value.vdouble.scalar.Length;
7 import org.djunits.value.vdouble.scalar.Speed;
8 import org.djunits.value.vdouble.scalar.Time;
9 import org.opentrafficsim.core.gtu.GTU;
10 import org.opentrafficsim.core.gtu.GTUDirectionality;
11 import org.opentrafficsim.core.gtu.GTUException;
12 import org.opentrafficsim.core.gtu.RelativePosition;
13 import org.opentrafficsim.core.gtu.TurnIndicatorStatus;
14 import org.opentrafficsim.core.network.LateralDirectionality;
15 import org.opentrafficsim.road.gtu.lane.tactical.LaneBasedTacticalPlanner;
16 import org.opentrafficsim.road.gtu.strategical.LaneBasedStrategicalPlanner;
17 import org.opentrafficsim.road.network.RoadNetwork;
18 import org.opentrafficsim.road.network.lane.DirectedLanePosition;
19 import org.opentrafficsim.road.network.lane.Lane;
20
21 import nl.tudelft.simulation.dsol.formalisms.eventscheduling.SimEventInterface;
22 import nl.tudelft.simulation.dsol.simtime.SimTimeDoubleUnit;
23 import nl.tudelft.simulation.event.EventType;
24 import nl.tudelft.simulation.language.d3.DirectedPoint;
25
26 /**
27 * This interface defines a lane based GTU.
28 * <p>
29 * Copyright (c) 2013-2019 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 * @version $Revision: 1401 $, $LastChangedDate: 2015-09-14 01:33:02 +0200 (Mon, 14 Sep 2015) $, by $Author: averbraeck $,
33 * initial version Oct 22, 2014 <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 LaneBasedGTU extends GTU
38 {
39 /** @return the road network to which the LaneBasedGTU belongs*/
40 RoadNetwork getNetwork();
41
42 /** {@inheritDoc} */
43 @Override
44 LaneBasedStrategicalPlanner getStrategicalPlanner();
45
46 /** {@inheritDoc} */
47 @Override
48 LaneBasedStrategicalPlanner getStrategicalPlanner(Time time);
49
50 /** {@inheritDoc} */
51 @Override
52 default LaneBasedTacticalPlanner getTacticalPlanner()
53 {
54 return getStrategicalPlanner().getTacticalPlanner();
55 }
56
57 /** {@inheritDoc} */
58 @Override
59 default LaneBasedTacticalPlanner getTacticalPlanner(final Time time)
60 {
61 return getStrategicalPlanner(time).getTacticalPlanner(time);
62 }
63
64 /**
65 * Return the location without a RemoteException. {@inheritDoc}
66 */
67 @Override
68 DirectedPoint getLocation();
69
70 /**
71 * insert GTU at a certain position. This can happen at setup (first initialization), and after a lane change of the GTU.
72 * The relative position that will be registered is the referencePosition (dx, dy, dz) = (0, 0, 0). Front and rear positions
73 * are relative towards this position.
74 * @param lane Lane; the lane to add to the list of lanes on which the GTU is registered.
75 * @param gtuDirection GTUDirectionality; the direction of the GTU on the lane (which can be bidirectional). If the GTU has
76 * a positive speed, it is moving in this direction.
77 * @param position Length; the position on the lane.
78 * @throws GTUException when positioning the GTU on the lane causes a problem
79 */
80 void enterLane(Lane lane, Length position, GTUDirectionality gtuDirection) throws GTUException;
81
82 /**
83 * Unregister the GTU from a lane.
84 * @param lane Lane; the lane to remove from the list of lanes on which the GTU is registered.
85 * @throws GTUException when leaveLane should not be called
86 */
87 void leaveLane(Lane lane) throws GTUException;
88
89 /**
90 * Change lanes instantaneously.
91 * @param laneChangeDirection LateralDirectionality; the direction to change to
92 * @throws GTUException in case lane change fails
93 */
94 void changeLaneInstantaneously(LateralDirectionality laneChangeDirection) throws GTUException;
95
96 /**
97 * Sets event to finalize lane change.
98 * @param event SimEventInterface<SimTimeDoubleUnit>; event
99 */
100 void setFinalizeLaneChangeEvent(SimEventInterface<SimTimeDoubleUnit> event);
101
102 /**
103 * Return the longitudinal positions of a point relative to this GTU, relative to the center line of the Lanes in which the
104 * vehicle is registered. <br>
105 * <b>Note:</b> If a GTU is registered in multiple parallel lanes, the lateralLaneChangeModel is used to determine the
106 * center line of the vehicle at this point in time. Otherwise, the average of the center positions of the lines will be
107 * taken.
108 * @param relativePosition RelativePosition; the position on the vehicle relative to the reference point.
109 * @return the lanes and the position on the lanes where the GTU is currently registered, for the given position of the GTU.
110 * @throws GTUException when the vehicle is not on one of the lanes on which it is registered.
111 */
112 Map<Lane, Length> positions(RelativePosition relativePosition) throws GTUException;
113
114 /**
115 * Return the longitudinal positions of a point relative to this GTU, relative to the center line of the Lanes in which the
116 * vehicle is registered.
117 * @param relativePosition RelativePosition; the position on the vehicle relative to the reference point.
118 * @param when Time; the future time for which to calculate the positions.
119 * @return the lanes and the position on the lanes where the GTU will be registered at the time, for the given position of
120 * the GTU.
121 * @throws GTUException when the vehicle is not on one of the lanes on which it is registered.
122 */
123 Map<Lane, Length> positions(RelativePosition relativePosition, Time when) throws GTUException;
124
125 /**
126 * Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane at the current
127 * simulation time. <br>
128 * @param lane Lane; the position on this lane will be returned.
129 * @param relativePosition RelativePosition; the position on the vehicle relative to the reference point.
130 * @return DoubleScalarAbs<LengthUnit>; the position, relative to the center line of the Lane.
131 * @throws GTUException when the vehicle is not on the given lane.
132 */
133 Length position(Lane lane, RelativePosition relativePosition) throws GTUException;
134
135 /**
136 * Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane.
137 * @param lane Lane; the position on this lane will be returned.
138 * @param relativePosition RelativePosition; the position on the vehicle relative to the reference point.
139 * @param when Time; the future time for which to calculate the positions.
140 * @return DoubleScalarAbs<LengthUnit>; the position, relative to the center line of the Lane.
141 * @throws GTUException when the vehicle is not on the given lane.
142 */
143 Length position(Lane lane, RelativePosition relativePosition, Time when) throws GTUException;
144
145 /**
146 * Return the longitudinal positions of a point relative to this GTU, relative to the center line of the Lanes in which the
147 * vehicle is registered, as fractions of the length of the lane. This is important when we want to see if two vehicles are
148 * next to each other and we compare an 'inner' and 'outer' curve.<br>
149 * @param relativePosition RelativePosition; the position on the vehicle relative to the reference point.
150 * @return the lanes and the position on the lanes where the GTU is currently registered, for the given position of the GTU.
151 * @throws GTUException when the vehicle is not on one of the lanes on which it is registered.
152 */
153 Map<Lane, Double> fractionalPositions(RelativePosition relativePosition) throws GTUException;
154
155 /**
156 * Return the longitudinal positions of a point relative to this GTU, relative to the center line of the Lanes in which the
157 * vehicle is registered, as fractions of the length of the lane. This is important when we want to see if two vehicles are
158 * next to each other and we compare an 'inner' and 'outer' curve.
159 * @param relativePosition RelativePosition; the position on the vehicle relative to the reference point.
160 * @param when Time; the future time for which to calculate the positions.
161 * @return the lanes and the position on the lanes where the GTU will be registered at the time, for the given position of
162 * the GTU.
163 * @throws GTUException when the vehicle is not on one of the lanes on which it is registered.
164 */
165 Map<Lane, Double> fractionalPositions(RelativePosition relativePosition, Time when) throws GTUException;
166
167 /**
168 * Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane, as a fraction
169 * of the length of the lane. This is important when we want to see if two vehicles are next to each other and we compare an
170 * 'inner' and 'outer' curve.
171 * @param lane Lane; the position on this lane will be returned.
172 * @param relativePosition RelativePosition; the position on the vehicle relative to the reference point.
173 * @param when Time; the future time for which to calculate the positions.
174 * @return the fractional relative position on the lane at the given time.
175 * @throws GTUException when the vehicle is not on the given lane.
176 */
177 double fractionalPosition(Lane lane, RelativePosition relativePosition, Time when) throws GTUException;
178
179 /**
180 * Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane, as a fraction
181 * of the length of the lane. This is important when we want to see if two vehicles are next to each other and we compare an
182 * 'inner' and 'outer' curve.<br>
183 * @param lane Lane; the position on this lane will be returned.
184 * @param relativePosition RelativePosition; the position on the vehicle relative to the reference point.
185 * @return the fractional relative position on the lane at the given time.
186 * @throws GTUException when the vehicle is not on the given lane.
187 */
188 double fractionalPosition(Lane lane, RelativePosition relativePosition) throws GTUException;
189
190 /**
191 * Return the longitudinal position that the indicated relative position of this GTU would have if it were to change to
192 * another Lane with a / the current CrossSectionLink. This point may be before the begin or after the end of the link of
193 * the projection lane of the GTU. This preserves the length of the GTU.
194 * @param projectionLane Lane; the lane onto which the position of this GTU must be projected
195 * @param relativePosition RelativePosition; the point on this GTU that must be projected
196 * @param when Time; the time for which to project the position of this GTU
197 * @return Length; the position of this GTU in the projectionLane
198 * @throws GTUException when projectionLane it not in any of the CrossSectionLink that the GTU is on
199 */
200 Length translatedPosition(Lane projectionLane, RelativePosition relativePosition, Time when) throws GTUException;
201
202 /**
203 * Return the longitudinal position on the projection lane that has the same fractional position on one of the current lanes
204 * of the indicated relative position. This preserves the fractional positions of all relative positions of the GTU.
205 * @param projectionLane Lane; the lane onto which the position of this GTU must be projected
206 * @param relativePosition RelativePosition; the point on this GTU that must be projected
207 * @param when Time; the time for which to project the position of this GTU
208 * @return Length; the position of this GTU in the projectionLane
209 * @throws GTUException when projectionLane it not in any of the CrossSectionLink that the GTU is on
210 */
211 Length projectedPosition(Lane projectionLane, RelativePosition relativePosition, Time when) throws GTUException;
212
213 /**
214 * Return the current Lane, position and directionality of the GTU.
215 * @return DirectedLanePosition; the current Lane, position and directionality of the GTU
216 * @throws GTUException in case the reference position of the GTU cannot be found on the lanes in its current path
217 */
218 DirectedLanePosition getReferencePosition() throws GTUException;
219
220 /**
221 * Return the directionality of a lane on which the GTU is registered for its current operational plan.
222 * @param lane Lane; the lane for which we want to know the direction
223 * @return GTUDirectionality; the direction on the given lane
224 * @throws GTUException in case the GTU is not registered on the Lane
225 */
226 GTUDirectionality getDirection(Lane lane) throws GTUException;
227
228 /**
229 * Add an event to the list of lane triggers scheduled for this GTU.
230 * @param lane Lane; the lane on which the event occurs
231 * @param event SimEventInterface<SimTimeDoubleUnit>; SimeEvent<SimTimeDoubleUnit> the event
232 */
233 void addTrigger(Lane lane, SimEventInterface<SimTimeDoubleUnit> event);
234
235 /**
236 * Set distance over which the GTU should not change lane after being created.
237 * @param distance Length; distance over which the GTU should not change lane after being created
238 */
239 void setNoLaneChangeDistance(Length distance);
240
241 /**
242 * Returns whether a lane change is allowed.
243 * @return whether a lane change is allowed
244 */
245 boolean laneChangeAllowed();
246
247 /**
248 * This method returns the current desired speed of the GTU. This value is required often, so implementations can cache it.
249 * @return Speed; current desired speed
250 */
251 Speed getDesiredSpeed();
252
253 /**
254 * This method returns the current car-following acceleration of the GTU. This value is required often, so implementations
255 * can cache it.
256 * @return Acceleration; current car-following acceleration
257 */
258 Acceleration getCarFollowingAcceleration();
259
260 /**
261 * Returns the vehicle model.
262 * @return VehicleModel; vehicle model
263 */
264 default VehicleModel getVehicleModel()
265 {
266 return VehicleModel.MINMAX;
267 }
268
269 /**
270 * The default implementation returns {@code true} if the deceleration is larger than a speed-dependent threshold given
271 * by:<br>
272 * <br>
273 * c0 * g(v) + c1 + c3*v^2<br>
274 * <br>
275 * where c0 = 0.2, c1 = 0.15 and c3 = 0.00025 (with c2 = 0 implicit) are empirically derived averages, and g(v) is 0 below
276 * 25 km/h or 1 otherwise, representing that the engine is disengaged at low speeds.
277 * @return boolean; whether the braking lights are on
278 */
279 default boolean isBrakingLightsOn()
280 {
281 return isBrakingLightsOn(getSimulator().getSimulatorTime());
282 }
283
284 /**
285 * The default implementation returns {@code true} if the deceleration is larger than a speed-dependent threshold given
286 * by:<br>
287 * <br>
288 * c0 * g(v) + c1 + c3*v^2<br>
289 * <br>
290 * where c0 = 0.2, c1 = 0.15 and c3 = 0.00025 (with c2 = 0 implicit) are empirically derived averages, and g(v) is 0 below
291 * 25 km/h or 1 otherwise, representing that the engine is disengaged at low speeds.
292 * @param when Time; time
293 * @return boolean; whether the braking lights are on
294 */
295 default boolean isBrakingLightsOn(final Time when)
296 {
297 double v = getSpeed(when).si;
298 double a = getAcceleration(when).si;
299 return a < (v < 6.944 ? 0.0 : -0.2) - 0.15 * v - 0.00025 * v * v;
300 }
301
302 /** @return the status of the turn indicator */
303 TurnIndicatorStatus getTurnIndicatorStatus();
304
305 /**
306 * @param time Time; time to obtain the turn indicator status at
307 * @return the status of the turn indicator at the given time
308 */
309 TurnIndicatorStatus getTurnIndicatorStatus(Time time);
310
311 /**
312 * Set the status of the turn indicator.
313 * @param turnIndicatorStatus TurnIndicatorStatus; the new status of the turn indicator.
314 * @throws GTUException when GTUType does not have a turn indicator
315 */
316 void setTurnIndicatorStatus(TurnIndicatorStatus turnIndicatorStatus) throws GTUException;
317
318 /**
319 * The lane-based event type for pub/sub indicating the initialization of a new GTU. <br>
320 * Payload: [String gtuId, DirectedPoint initialPosition, Length length, Length width, Lane referenceLane, Length
321 * positionOnReferenceLane, GTUDirectionality direction, GTUType gtuType]
322 */
323 EventType LANEBASED_INIT_EVENT = new EventType("LANEBASEDGTU.INIT");
324
325 /**
326 * The lane-based event type for pub/sub indicating a move. <br>
327 * Payload: [String gtuId, DirectedPoint position, Speed speed, Acceleration acceleration, TurnIndicatorStatus
328 * turnIndicatorStatus, Length odometer, Lane referenceLane, Length positionOnReferenceLane, GTUDirectionality direction]
329 */
330 EventType LANEBASED_MOVE_EVENT = new EventType("LANEBASEDGTU.MOVE");
331
332 /**
333 * The lane-based event type for pub/sub indicating destruction of the GTU. <br>
334 * Payload: [String gtuId, DirectedPoint lastPosition, Length odometer, Lane referenceLane, Length positionOnReferenceLane,
335 * GTUDirectionality direction]
336 */
337 EventType LANEBASED_DESTROY_EVENT = new EventType("LANEBASEDGTU.DESTROY");
338
339 /**
340 * The event type for pub/sub indicating that the GTU entered a new link (with the FRONT position if driving forward; REAR
341 * if driving backward). <br>
342 * Payload: [String gtuId, Link link]
343 */
344 EventType LINK_ENTER_EVENT = new EventType("LINK.ENTER");
345
346 /**
347 * The event type for pub/sub indicating that the GTU exited a link (with the REAR position if driving forward; FRONT if
348 * driving backward). <br>
349 * Payload: [String gtuId, Link link]
350 */
351 EventType LINK_EXIT_EVENT = new EventType("LINK.EXIT");
352
353 /**
354 * The event type for pub/sub indicating that the GTU entered a new lane (with the FRONT position if driving forward; REAR
355 * if driving backward). <br>
356 * Payload: [String gtuId, Lane lane]
357 */
358 EventType LANE_ENTER_EVENT = new EventType("LANE.ENTER");
359
360 /**
361 * The event type for pub/sub indicating that the GTU exited a lane (with the REAR position if driving forward; FRONT if
362 * driving backward). <br>
363 * Payload: [String gtuId, Lane lane]
364 */
365 EventType LANE_EXIT_EVENT = new EventType("LANE.EXIT");
366
367 /**
368 * The event type for pub/sub indicating that the GTU change lane. <br>
369 * Payload: [String gtuId, LateralDirectionality direction, DirectedLanePosition from]
370 */
371 EventType LANE_CHANGE_EVENT = new EventType("LANE.CHANGE");
372
373 }