1 package org.opentrafficsim.road.gtu.lane;
2
3 import java.util.Map;
4
5 import org.djunits.value.vdouble.scalar.Length;
6 import org.djunits.value.vdouble.scalar.Time;
7 import org.opentrafficsim.core.dsol.OTSSimTimeDouble;
8 import org.opentrafficsim.core.gtu.GTU;
9 import org.opentrafficsim.core.gtu.GTUDirectionality;
10 import org.opentrafficsim.core.gtu.GTUException;
11 import org.opentrafficsim.core.gtu.RelativePosition;
12 import org.opentrafficsim.core.network.LateralDirectionality;
13 import org.opentrafficsim.road.gtu.lane.tactical.LaneBasedTacticalPlanner;
14 import org.opentrafficsim.road.gtu.strategical.LaneBasedStrategicalPlanner;
15 import org.opentrafficsim.road.network.lane.DirectedLanePosition;
16 import org.opentrafficsim.road.network.lane.Lane;
17
18 import nl.tudelft.simulation.dsol.formalisms.eventscheduling.SimEvent;
19 import nl.tudelft.simulation.event.EventType;
20 import nl.tudelft.simulation.language.d3.DirectedPoint;
21
22 /**
23 * This interface defines a lane based GTU.
24 * <p>
25 * Copyright (c) 2013-2017 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
26 * BSD-style license. See <a href="http://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
27 * <p>
28 * @version $Revision: 1401 $, $LastChangedDate: 2015-09-14 01:33:02 +0200 (Mon, 14 Sep 2015) $, by $Author: averbraeck $,
29 * initial version Oct 22, 2014 <br>
30 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
31 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
32 */
33 public interface LaneBasedGTU extends GTU
34 {
35 /** {@inheritDoc} */
36 @Override
37 LaneBasedStrategicalPlanner getStrategicalPlanner();
38
39 /** {@inheritDoc} */
40 @Override
41 LaneBasedTacticalPlanner getTacticalPlanner();
42
43 /**
44 * Return the location without a RemoteException. {@inheritDoc}
45 */
46 @Override
47 DirectedPoint getLocation();
48
49 /**
50 * insert GTU at a certain position. This can happen at setup (first initialization), and after a lane change of the GTU.
51 * The relative position that will be registered is the referencePosition (dx, dy, dz) = (0, 0, 0). Front and rear positions
52 * are relative towards this position.
53 * @param lane the lane to add to the list of lanes on which the GTU is registered.
54 * @param gtuDirection the direction of the GTU on the lane (which can be bidirectional). If the GTU has a positive speed,
55 * it is moving in this direction.
56 * @param position the position on the lane.
57 * @throws GTUException when positioning the GTU on the lane causes a problem
58 */
59 void enterLane(Lane lane, Length position, GTUDirectionality gtuDirection) throws GTUException;
60
61 /**
62 * Unregister the GTU from a lane.
63 * @param lane the lane to remove from the list of lanes on which the GTU is registered.
64 * @throws GTUException when leaveLane should not be called
65 */
66 void leaveLane(Lane lane) throws GTUException;
67
68 /**
69 * Change lanes instantaneously.
70 * @param laneChangeDirection the direction to change to
71 * @throws GTUException in case lane change fails
72 */
73 void changeLaneInstantaneously(LateralDirectionality laneChangeDirection) throws GTUException;
74
75 /**
76 * Return the longitudinal positions of a point relative to this GTU, relative to the center line of the Lanes in which the
77 * vehicle is registered. <br>
78 * <b>Note:</b> If a GTU is registered in multiple parallel lanes, the lateralLaneChangeModel is used to determine the
79 * center line of the vehicle at this point in time. Otherwise, the average of the center positions of the lines will be
80 * taken.
81 * @param relativePosition the position on the vehicle relative to the reference point.
82 * @return the lanes and the position on the lanes where the GTU is currently registered, for the given position of the GTU.
83 * @throws GTUException when the vehicle is not on one of the lanes on which it is registered.
84 */
85 Map<Lane, Length> positions(RelativePosition relativePosition) throws GTUException;
86
87 /**
88 * Return the longitudinal positions of a point relative to this GTU, relative to the center line of the Lanes in which the
89 * vehicle is registered.
90 * @param relativePosition the position on the vehicle relative to the reference point.
91 * @param when the future time for which to calculate the positions.
92 * @return the lanes and the position on the lanes where the GTU will be registered at the time, for the given position of
93 * the GTU.
94 * @throws GTUException when the vehicle is not on one of the lanes on which it is registered.
95 */
96 Map<Lane, Length> positions(RelativePosition relativePosition, Time when) throws GTUException;
97
98 /**
99 * Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane at the current
100 * simulation time. <br>
101 * @param lane the position on this lane will be returned.
102 * @param relativePosition the position on the vehicle relative to the reference point.
103 * @return DoubleScalarAbs<LengthUnit>; the position, relative to the center line of the Lane.
104 * @throws GTUException when the vehicle is not on the given lane.
105 */
106 Length position(Lane lane, RelativePosition relativePosition) throws GTUException;
107
108 /**
109 * Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane.
110 * @param lane the position on this lane will be returned.
111 * @param relativePosition the position on the vehicle relative to the reference point.
112 * @param when the future time for which to calculate the positions.
113 * @return DoubleScalarAbs<LengthUnit>; the position, relative to the center line of the Lane.
114 * @throws GTUException when the vehicle is not on the given lane.
115 */
116 Length position(Lane lane, RelativePosition relativePosition, Time when) throws GTUException;
117
118 /**
119 * Return the longitudinal positions of a point relative to this GTU, relative to the center line of the Lanes in which the
120 * vehicle is registered, as fractions of the length of the lane. This is important when we want to see if two vehicles are
121 * next to each other and we compare an 'inner' and 'outer' curve.<br>
122 * @param relativePosition the position on the vehicle relative to the reference point.
123 * @return the lanes and the position on the lanes where the GTU is currently registered, for the given position of the GTU.
124 * @throws GTUException when the vehicle is not on one of the lanes on which it is registered.
125 */
126 Map<Lane, Double> fractionalPositions(RelativePosition relativePosition) throws GTUException;
127
128 /**
129 * Return the longitudinal positions of a point relative to this GTU, relative to the center line of the Lanes in which the
130 * vehicle is registered, as fractions of the length of the lane. This is important when we want to see if two vehicles are
131 * next to each other and we compare an 'inner' and 'outer' curve.
132 * @param relativePosition the position on the vehicle relative to the reference point.
133 * @param when the future time for which to calculate the positions.
134 * @return the lanes and the position on the lanes where the GTU will be registered at the time, for the given position of
135 * the GTU.
136 * @throws GTUException when the vehicle is not on one of the lanes on which it is registered.
137 */
138 Map<Lane, Double> fractionalPositions(RelativePosition relativePosition, Time when) throws GTUException;
139
140 /**
141 * Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane, as a fraction
142 * 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
143 * 'inner' and 'outer' curve.
144 * @param lane the position on this lane will be returned.
145 * @param relativePosition the position on the vehicle relative to the reference point.
146 * @param when the future time for which to calculate the positions.
147 * @return the fractional relative position on the lane at the given time.
148 * @throws GTUException when the vehicle is not on the given lane.
149 */
150 double fractionalPosition(Lane lane, RelativePosition relativePosition, Time when) throws GTUException;
151
152 /**
153 * Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane, as a fraction
154 * 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
155 * 'inner' and 'outer' curve.<br>
156 * @param lane the position on this lane will be returned.
157 * @param relativePosition the position on the vehicle relative to the reference point.
158 * @return the fractional relative position on the lane at the given time.
159 * @throws GTUException when the vehicle is not on the given lane.
160 */
161 double fractionalPosition(Lane lane, RelativePosition relativePosition) throws GTUException;
162
163 /**
164 * Return the longitudinal position that the indicated relative position of this GTU would have if it were to change to
165 * another Lane with a / the current CrossSectionLink. This point may be before the begin or after the end of the link of
166 * the projection lane of the GTU. This preserves the length of the GTU.
167 * @param projectionLane Lane; the lane onto which the position of this GTU must be projected
168 * @param relativePosition RelativePosition; the point on this GTU that must be projected
169 * @param when Time; the time for which to project the position of this GTU
170 * @return Length; the position of this GTU in the projectionLane
171 * @throws GTUException when projectionLane it not in any of the CrossSectionLink that the GTU is on
172 */
173 Length translatedPosition(Lane projectionLane, RelativePosition relativePosition, Time when) throws GTUException;
174
175 /**
176 * Return the longitudinal position on the projection lane that has the same fractional position on one of the current lanes
177 * of the indicated relative position. This preserves the fractional positions of all relative positions of the GTU.
178 * @param projectionLane Lane; the lane onto which the position of this GTU must be projected
179 * @param relativePosition RelativePosition; the point on this GTU that must be projected
180 * @param when Time; the time for which to project the position of this GTU
181 * @return Length; the position of this GTU in the projectionLane
182 * @throws GTUException when projectionLane it not in any of the CrossSectionLink that the GTU is on
183 */
184 Length projectedPosition(Lane projectionLane, RelativePosition relativePosition, Time when) throws GTUException;
185
186 /**
187 * Return the current Lane, position and directionality of the GTU.
188 * @return DirectedLanePosition; the current Lane, position and directionality of the GTU
189 * @throws GTUException in case the reference position of the GTU cannot be found on the lanes in its current path
190 */
191 DirectedLanePosition getReferencePosition() throws GTUException;
192
193 /**
194 * Return the directionality of a lane on which the GTU is registered for its current operational plan.
195 * @param lane Lane; the lane for which we want to know the direction
196 * @return GTUDirectionality; the direction on the given lane
197 * @throws GTUException in case the GTU is not registered on the Lane
198 */
199 GTUDirectionality getDirection(Lane lane) throws GTUException;
200
201 /**
202 * Add an event to the list of lane triggers scheduled for this GTU.
203 * @param lane Lane; the lane on which the event occurs
204 * @param event SimeEvent<OTSSimTimeDouble> the event
205 */
206 void addTrigger(Lane lane, SimEvent<OTSSimTimeDouble> event);
207
208 /**
209 * Set distance over which the GTU should not change lane after being created.
210 * @param distance distance over which the GTU should not change lane after being created
211 */
212 void setNoLaneChangeDistance(Length distance);
213
214 /**
215 * Returns whether a lane change is allowed.
216 * @return whether a lane change is allowed
217 */
218 boolean laneChangeAllowed();
219
220 /**
221 * The lane-based event type for pub/sub indicating the initialization of a new GTU. <br>
222 * Payload: [String gtuId, DirectedPoint initialPosition, Length length, Length width, Color gtuBaseColor, Lane
223 * referenceLane, Length positionOnReferenceLane, GTUDirectionality direction, GTUType gtuType]
224 */
225 EventType LANEBASED_INIT_EVENT = new EventType("LANEBASEDGTU.INIT");
226
227 /**
228 * The lane-based event type for pub/sub indicating a move. <br>
229 * Payload: [String gtuId, DirectedPoint position, Speed speed, Acceleration acceleration, TurnIndicatorStatus
230 * turnIndicatorStatus, Length odometer, Lane referenceLane, Length positionOnReferenceLane, GTUDirectionality direction]
231 */
232 EventType LANEBASED_MOVE_EVENT = new EventType("LANEBASEDGTU.MOVE");
233
234 /**
235 * The lane-based event type for pub/sub indicating destruction of the GTU. <br>
236 * Payload: [String gtuId, DirectedPoint lastPosition, Length odometer, Lane referenceLane, Length positionOnReferenceLane,
237 * GTUDirectionality direction]
238 */
239 EventType LANEBASED_DESTROY_EVENT = new EventType("LANEBASEDGTU.DESTROY");
240
241 /**
242 * The event type for pub/sub indicating that the GTU entered a new link (with the FRONT position if driving forward; REAR
243 * if driving backward). <br>
244 * Payload: [String gtuId, Link link]
245 */
246 EventType LINK_ENTER_EVENT = new EventType("LINK.ENTER");
247
248 /**
249 * The event type for pub/sub indicating that the GTU exited a link (with the REAR position if driving forward; FRONT if
250 * driving backward). <br>
251 * Payload: [String gtuId, Link link]
252 */
253 EventType LINK_EXIT_EVENT = new EventType("LINK.EXIT");
254
255 /**
256 * The event type for pub/sub indicating that the GTU entered a new lane (with the FRONT position if driving forward; REAR
257 * if driving backward). <br>
258 * Payload: [String gtuId, Lane lane]
259 */
260 EventType LANE_ENTER_EVENT = new EventType("LANE.ENTER");
261
262 /**
263 * The event type for pub/sub indicating that the GTU exited a lane (with the REAR position if driving forward; FRONT if
264 * driving backward). <br>
265 * Payload: [String gtuId, Lane lane]
266 */
267 EventType LANE_EXIT_EVENT = new EventType("LANE.EXIT");
268
269 }