1 package org.opentrafficsim.road.gtu.lane;
2
3 import java.util.Map;
4
5 import nl.tudelft.simulation.dsol.formalisms.eventscheduling.SimEvent;
6
7 import org.djunits.value.vdouble.scalar.Length;
8 import org.djunits.value.vdouble.scalar.Time;
9 import org.opentrafficsim.core.dsol.OTSSimTimeDouble;
10 import org.opentrafficsim.core.gtu.GTU;
11 import org.opentrafficsim.core.gtu.GTUDirectionality;
12 import org.opentrafficsim.core.gtu.GTUException;
13 import org.opentrafficsim.core.gtu.RelativePosition;
14 import org.opentrafficsim.road.gtu.lane.driver.LaneBasedBehavioralCharacteristics;
15 import org.opentrafficsim.road.gtu.lane.perception.LanePerceptionFull;
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-2015 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 // TODO change into LanePerception interface!
35 LanePerceptionFull getPerception();
36
37 /** {@inheritDoc} */
38 @Override
39 LaneBasedBehavioralCharacteristics getBehavioralCharacteristics();
40
41 /** {@inheritDoc} */
42 @Override
43 LaneBasedStrategicalPlanner getStrategicalPlanner();
44
45 /**
46 * @return a safe copy of the lanes on which the GTU is registered.
47 */
48 Map<Lane, GTUDirectionality> getLanes();
49
50 /**
51 * insert GTU at a certain position. This can happen at setup (first initialization), and after a lane change of the GTU.
52 * The relative position that will be registered is the referencePosition (dx, dy, dz) = (0, 0, 0). Front and rear positions
53 * are relative towards this position.
54 * @param lane the lane to add to the list of lanes on which the GTU is registered.
55 * @param gtuDirection the direction of the GTU on the lane (which can be bidirectional). If the GTU has a positive
56 * velocity, it is moving in this direction.
57 * @param position the position on the lane.
58 * @throws GTUException when positioning the GTU on the lane causes a problem
59 */
60 void enterLane(Lane lane, Length.Rel position, GTUDirectionality gtuDirection) throws GTUException;
61
62 /**
63 * Unregister the GTU from a lane.
64 * @param lane the lane to remove from the list of lanes on which the GTU is registered.
65 * @throws GTUException when leaveLane should not be called
66 */
67 void leaveLane(Lane lane) throws GTUException;
68
69 /**
70 * Return the longitudinal positions of a point relative to this GTU, relative to the center line of the Lanes in which the
71 * vehicle is registered. <br>
72 * <b>Note:</b> If a GTU is registered in multiple parallel lanes, the lateralLaneChangeModel is used to determine the
73 * center line of the vehicle at this point in time. Otherwise, the average of the center positions of the lines will be
74 * taken.
75 * @param relativePosition the position on the vehicle relative to the reference point.
76 * @return the lanes and the position on the lanes where the GTU is currently registered, for the given position of the GTU.
77 * @throws GTUException when the vehicle is not on one of the lanes on which it is registered.
78 */
79 Map<Lane, Length.Rel> positions(RelativePosition relativePosition) throws GTUException;
80
81 /**
82 * Return the longitudinal positions of a point relative to this GTU, relative to the center line of the Lanes in which the
83 * vehicle is registered.
84 * @param relativePosition the position on the vehicle relative to the reference point.
85 * @param when the future time for which to calculate the positions.
86 * @return the lanes and the position on the lanes where the GTU will be registered at the time, for the given position of
87 * the GTU.
88 * @throws GTUException when the vehicle is not on one of the lanes on which it is registered.
89 */
90 Map<Lane, Length.Rel> positions(RelativePosition relativePosition, Time.Abs when) throws GTUException;
91
92 /**
93 * Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane at the current
94 * simulation time. <br>
95 * @param lane the position on this lane will be returned.
96 * @param relativePosition the position on the vehicle relative to the reference point.
97 * @return DoubleScalarAbs<LengthUnit>; the position, relative to the center line of the Lane.
98 * @throws GTUException when the vehicle is not on the given lane.
99 */
100 Length.Rel position(Lane lane, RelativePosition relativePosition) throws GTUException;
101
102 /**
103 * Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane.
104 * @param lane the position on this lane will be returned.
105 * @param relativePosition the position on the vehicle relative to the reference point.
106 * @param when the future time for which to calculate the positions.
107 * @return DoubleScalarAbs<LengthUnit>; the position, relative to the center line of the Lane.
108 * @throws GTUException when the vehicle is not on the given lane.
109 */
110 Length.Rel position(Lane lane, RelativePosition relativePosition, Time.Abs when) throws GTUException;
111
112 /**
113 * Return the longitudinal positions of a point relative to this GTU, relative to the center line of the Lanes in which the
114 * vehicle is registered, as fractions of the length of the lane. This is important when we want to see if two vehicles are
115 * next to each other and we compare an 'inner' and 'outer' curve.<br>
116 * @param relativePosition the position on the vehicle relative to the reference point.
117 * @return the lanes and the position on the lanes where the GTU is currently registered, for the given position of the GTU.
118 * @throws GTUException when the vehicle is not on one of the lanes on which it is registered.
119 */
120 Map<Lane, Double> fractionalPositions(RelativePosition relativePosition) throws GTUException;
121
122 /**
123 * Return the longitudinal positions of a point relative to this GTU, relative to the center line of the Lanes in which the
124 * vehicle is registered, as fractions of the length of the lane. This is important when we want to see if two vehicles are
125 * next to each other and we compare an 'inner' and 'outer' curve.
126 * @param relativePosition the position on the vehicle relative to the reference point.
127 * @param when the future time for which to calculate the positions.
128 * @return the lanes and the position on the lanes where the GTU will be registered at the time, for the given position of
129 * the GTU.
130 * @throws GTUException when the vehicle is not on one of the lanes on which it is registered.
131 */
132 Map<Lane, Double> fractionalPositions(RelativePosition relativePosition, Time.Abs when) throws GTUException;
133
134 /**
135 * Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane, as a fraction
136 * 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
137 * 'inner' and 'outer' curve.
138 * @param lane the position on this lane will be returned.
139 * @param relativePosition the position on the vehicle relative to the reference point.
140 * @param when the future time for which to calculate the positions.
141 * @return the fractional relative position on the lane at the given time.
142 * @throws GTUException when the vehicle is not on the given lane.
143 */
144 double fractionalPosition(Lane lane, RelativePosition relativePosition, Time.Abs when) throws GTUException;
145
146 /**
147 * Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane, as a fraction
148 * 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
149 * 'inner' and 'outer' curve.<br>
150 * @param lane the position on this lane will be returned.
151 * @param relativePosition the position on the vehicle relative to the reference point.
152 * @return the fractional relative position on the lane at the given time.
153 * @throws GTUException when the vehicle is not on the given lane.
154 */
155 double fractionalPosition(Lane lane, RelativePosition relativePosition) throws GTUException;
156
157 /**
158 * Return the longitudinal position that this GTU would have if it were to change to another Lane with a / the current
159 * CrossSectionLink.
160 * @param projectionLane Lane; the lane onto which the position of this GTU must be projected
161 * @param relativePosition RelativePosition; the point on this GTU that must be projected
162 * @param when Time.Abs; the time for which to project the position of this GTU
163 * @return Length.Rel; the position of this GTU in the projectionLane
164 * @throws GTUException when projectionLane it not in any of the CrossSectionLink that the GTU is on
165 */
166 Length.Rel projectedPosition(Lane projectionLane, RelativePosition relativePosition, Time.Abs when)
167 throws GTUException;
168
169 /**
170 * Add an event to the list of lane triggers scheduled for this GTU.
171 * @param lane Lane; the lane on which the event occurs
172 * @param event SimeEvent<OTSSimTimeDouble> the event
173 */
174 public void addTrigger(final Lane lane, final SimEvent<OTSSimTimeDouble> event);
175
176 }