1 package org.opentrafficsim.road.gtu.lane;
2
3 import java.util.Map;
4
5 import nl.tudelft.simulation.dsol.formalisms.eventscheduling.SimEvent;
6 import nl.tudelft.simulation.event.EventType;
7
8 import org.djunits.value.vdouble.scalar.Length;
9 import org.djunits.value.vdouble.scalar.Time;
10 import org.opentrafficsim.core.dsol.OTSSimTimeDouble;
11 import org.opentrafficsim.core.gtu.GTU;
12 import org.opentrafficsim.core.gtu.GTUDirectionality;
13 import org.opentrafficsim.core.gtu.GTUException;
14 import org.opentrafficsim.core.gtu.RelativePosition;
15 import org.opentrafficsim.road.gtu.lane.tactical.LaneBasedTacticalPlanner;
16 import org.opentrafficsim.road.gtu.strategical.LaneBasedStrategicalPlanner;
17 import org.opentrafficsim.road.network.lane.Lane;
18
19 /**
20 * This interface defines a lane based GTU.
21 * <p>
22 * Copyright (c) 2013-2016 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
23 * BSD-style license. See <a href="http://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
24 * <p>
25 * @version $Revision: 1401 $, $LastChangedDate: 2015-09-14 01:33:02 +0200 (Mon, 14 Sep 2015) $, by $Author: averbraeck $,
26 * initial version Oct 22, 2014 <br>
27 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
28 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
29 */
30 public interface LaneBasedGTU extends GTU
31 {
32 /** {@inheritDoc} */
33 @Override
34 LaneBasedStrategicalPlanner getStrategicalPlanner();
35
36 /** {@inheritDoc} */
37 @Override
38 LaneBasedTacticalPlanner getTacticalPlanner();
39
40 /**
41 * @return a safe copy of the lanes on which the GTU is registered.
42 */
43 Map<Lane, GTUDirectionality> getLanes();
44
45 /**
46 * insert GTU at a certain position. This can happen at setup (first initialization), and after a lane change of the GTU.
47 * The relative position that will be registered is the referencePosition (dx, dy, dz) = (0, 0, 0). Front and rear positions
48 * are relative towards this position.
49 * @param lane the lane to add to the list of lanes on which the GTU is registered.
50 * @param gtuDirection the direction of the GTU on the lane (which can be bidirectional). If the GTU has a positive speed,
51 * it is moving in this direction.
52 * @param position the position on the lane.
53 * @throws GTUException when positioning the GTU on the lane causes a problem
54 */
55 void enterLane(Lane lane, Length position, GTUDirectionality gtuDirection) throws GTUException;
56
57 /**
58 * Unregister the GTU from a lane.
59 * @param lane the lane to remove from the list of lanes on which the GTU is registered.
60 * @throws GTUException when leaveLane should not be called
61 */
62 void leaveLane(Lane lane) throws GTUException;
63
64 /**
65 * Return the longitudinal positions of a point relative to this GTU, relative to the center line of the Lanes in which the
66 * vehicle is registered. <br>
67 * <b>Note:</b> If a GTU is registered in multiple parallel lanes, the lateralLaneChangeModel is used to determine the
68 * center line of the vehicle at this point in time. Otherwise, the average of the center positions of the lines will be
69 * taken.
70 * @param relativePosition the position on the vehicle relative to the reference point.
71 * @return the lanes and the position on the lanes where the GTU is currently registered, for the given position of the GTU.
72 * @throws GTUException when the vehicle is not on one of the lanes on which it is registered.
73 */
74 Map<Lane, Length> positions(RelativePosition relativePosition) throws GTUException;
75
76 /**
77 * Return the longitudinal positions of a point relative to this GTU, relative to the center line of the Lanes in which the
78 * vehicle is registered.
79 * @param relativePosition the position on the vehicle relative to the reference point.
80 * @param when the future time for which to calculate the positions.
81 * @return the lanes and the position on the lanes where the GTU will be registered at the time, for the given position of
82 * 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, Time when) throws GTUException;
86
87 /**
88 * Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane at the current
89 * simulation time. <br>
90 * @param lane the position on this lane will be returned.
91 * @param relativePosition the position on the vehicle relative to the reference point.
92 * @return DoubleScalarAbs<LengthUnit>; the position, relative to the center line of the Lane.
93 * @throws GTUException when the vehicle is not on the given lane.
94 */
95 Length position(Lane lane, RelativePosition relativePosition) throws GTUException;
96
97 /**
98 * Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane.
99 * @param lane the position on this lane will be returned.
100 * @param relativePosition the position on the vehicle relative to the reference point.
101 * @param when the future time for which to calculate the positions.
102 * @return DoubleScalarAbs<LengthUnit>; the position, relative to the center line of the Lane.
103 * @throws GTUException when the vehicle is not on the given lane.
104 */
105 Length position(Lane lane, RelativePosition relativePosition, Time when) throws GTUException;
106
107 /**
108 * Return the longitudinal positions of a point relative to this GTU, relative to the center line of the Lanes in which the
109 * vehicle is registered, as fractions of the length of the lane. This is important when we want to see if two vehicles are
110 * next to each other and we compare an 'inner' and 'outer' curve.<br>
111 * @param relativePosition the position on the vehicle relative to the reference point.
112 * @return the lanes and the position on the lanes where the GTU is currently registered, for the given position of the GTU.
113 * @throws GTUException when the vehicle is not on one of the lanes on which it is registered.
114 */
115 Map<Lane, Double> fractionalPositions(RelativePosition relativePosition) throws GTUException;
116
117 /**
118 * Return the longitudinal positions of a point relative to this GTU, relative to the center line of the Lanes in which the
119 * vehicle is registered, as fractions of the length of the lane. This is important when we want to see if two vehicles are
120 * next to each other and we compare an 'inner' and 'outer' curve.
121 * @param relativePosition the position on the vehicle relative to the reference point.
122 * @param when the future time for which to calculate the positions.
123 * @return the lanes and the position on the lanes where the GTU will be registered at the time, for the given position of
124 * the GTU.
125 * @throws GTUException when the vehicle is not on one of the lanes on which it is registered.
126 */
127 Map<Lane, Double> fractionalPositions(RelativePosition relativePosition, Time when) throws GTUException;
128
129 /**
130 * Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane, as a fraction
131 * 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
132 * 'inner' and 'outer' curve.
133 * @param lane the position on this lane will be returned.
134 * @param relativePosition the position on the vehicle relative to the reference point.
135 * @param when the future time for which to calculate the positions.
136 * @return the fractional relative position on the lane at the given time.
137 * @throws GTUException when the vehicle is not on the given lane.
138 */
139 double fractionalPosition(Lane lane, RelativePosition relativePosition, Time when) throws GTUException;
140
141 /**
142 * Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane, as a fraction
143 * 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
144 * 'inner' and 'outer' curve.<br>
145 * @param lane the position on this lane will be returned.
146 * @param relativePosition the position on the vehicle relative to the reference point.
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) throws GTUException;
151
152 /**
153 * Return the longitudinal position that this GTU would have if it were to change to another Lane with a / the current
154 * CrossSectionLink.
155 * @param projectionLane Lane; the lane onto which the position of this GTU must be projected
156 * @param relativePosition RelativePosition; the point on this GTU that must be projected
157 * @param when Time; the time for which to project the position of this GTU
158 * @return Length; the position of this GTU in the projectionLane
159 * @throws GTUException when projectionLane it not in any of the CrossSectionLink that the GTU is on
160 */
161 Length projectedPosition(Lane projectionLane, RelativePosition relativePosition, Time when) throws GTUException;
162
163 /**
164 * Add an event to the list of lane triggers scheduled for this GTU.
165 * @param lane Lane; the lane on which the event occurs
166 * @param event SimeEvent<OTSSimTimeDouble> the event
167 */
168 void addTrigger(Lane lane, SimEvent<OTSSimTimeDouble> event);
169
170 /**
171 * The lane-based event type for pub/sub indicating a move. <br>
172 * Payload: [String id, DirectedPoint position, Speed speed, Acceleration acceleration, TurnIndicatorStatus
173 * turnIndicatorStatus, Length odometer, Lane referenceLane, Length positionOnReferenceLane]
174 */
175 EventType MOVE_EVENT = new EventType("LANEBASEDGTU.MOVE");
176
177 /**
178 * The lane-based event type for pub/sub indicating the initialization of a new GTU. <br>
179 * Payload: [String id, DirectedPoint initialPosition, Length length, Length width, Lane referenceLane, Length
180 * positionOnReferenceLane]
181 */
182 EventType INIT_EVENT = new EventType("LANEBASEDGTU.INIT");
183
184 /**
185 * The lane-based event type for pub/sub indicating destruction of the GTU. <br>
186 * Payload: [String id, DirectedPoint lastPosition, Length odometer, Lane referenceLane, Length positionOnReferenceLane]
187 */
188 EventType DESTROY_EVENT = new EventType("LANEBASEDGTU.DESTROY");
189
190 }