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