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