1 package org.opentrafficsim.road.gtu.lane.perception.headway;
2
3 import java.util.EnumSet;
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.opentrafficsim.core.gtu.GTUException;
9 import org.opentrafficsim.core.gtu.GTUType;
10 import org.opentrafficsim.core.gtu.behavioralcharacteristics.BehavioralCharacteristics;
11 import org.opentrafficsim.road.gtu.lane.tactical.following.CarFollowingModel;
12 import org.opentrafficsim.road.network.speed.SpeedLimitInfo;
13
14 /**
15 * Container for a reference to information about a (lane based) GTU and a headway. The Headway can store information about GTUs
16 * or objects ahead of the reference GTU, behind the reference GTU, or (partially) parallel to the reference GTU. In addition to
17 * the (perceived) headway, several other pieces of information can be stored, such as (perceived) speed, (perceived)
18 * acceleration, (perceived) turn indicators, and (perceived) braking lights. <br>
19 * Special care must be taken in curves when perceiving headway of a GTU or object on an adjacent lane.The question is whether
20 * we perceive the parallel or ahead/behind based on a line perpendicular to the front/back of the GTU (rectangular), or
21 * perpendicular to the center line of the lane (wedge-shaped in case of a curve). The difficulty of a wedge-shaped situation is
22 * that reciprocity might be violated: in case of a clothoid, for instance, it is not sure that the point on the center line
23 * when projected from lane 1 to lane 2 is the same as the projection from lane 2 to lane 1. The same holds for shapes with
24 * sharp bends. Therefore, algorithms implementing headway should only project the <i>reference point</i> of the reference GTU
25 * on the center line of the adjacent lane, and then calculate the forward position and backward position on the adjacent lane
26 * based on the reference point. Still, our human perception of what is parallel and what not, is not reflected by fractional
27 * positions. See examples in
28 * <a href= "http://simulation.tudelft.nl:8085/browse/OTS-113">http://simulation.tudelft.nl:8085/browse/OTS-113</a>.
29 * <p>
30 * Copyright (c) 2013-2016 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
31 * BSD-style license. See <a href="http://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
32 * <p>
33 * @version $Revision: 1368 $, $LastChangedDate: 2015-09-02 00:20:20 +0200 (Wed, 02 Sep 2015) $, by $Author: averbraeck $,
34 * initial version 11 feb. 2015 <br>
35 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
36 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
37 */
38 public abstract class AbstractHeadwayGTU extends AbstractHeadway
39 {
40 /** */
41 private static final long serialVersionUID = 20160410L;
42
43 /** The perceived GTU Type, or null if unknown. */
44 private final GTUType gtuType;
45
46 /** Whether the GTU is facing the same direction. */
47 private final boolean facingSameDirection;
48
49 /** Observable characteristics of a GTU. */
50 public enum GTUStatus
51 {
52 /** Braking lights are on when observing the headway. */
53 BRAKING_LIGHTS,
54
55 /** Left turn indicator was on when observing the headway. */
56 LEFT_TURNINDICATOR,
57
58 /** Right turn indicator was on when observing the headway. */
59 RIGHT_TURNINDICATOR,
60
61 /** Alarm lights are on. */
62 EMERGENCY_LIGHTS,
63
64 /** GTU was honking (car) or ringing a bell (cyclist) when observing the headway. */
65 HONK;
66 }
67
68 /** The observable characteristics of the GTU. */
69 private final EnumSet<GTUStatus> gtuStatus = EnumSet.noneOf(GTUStatus.class);
70
71 /**
72 * Construct a new Headway information object, for a moving GTU ahead of us or behind us.
73 * @param id the id of the GTU for comparison purposes, can not be null.
74 * @param gtuType the perceived GTU Type, or null if unknown.
75 * @param distance the distance to the other object; if this constructor is used, distance cannot be null.
76 * @param facingSameDirection whether the GTU is facing the same direction.
77 * @param length the (perceived) length of the other object; can not be null.
78 * @param speed the (perceived) speed of the other object; can be null if unknown.
79 * @param acceleration the (perceived) acceleration of the other object; can be null if unknown.
80 * @param gtuStatus the observable characteristics of the GTU.
81 * @throws GTUException when id is null, objectType is null, or parameters are inconsistent
82 */
83 @SuppressWarnings("checkstyle:parameternumber")
84 public AbstractHeadwayGTU(final String id, final GTUType gtuType, final Length distance, final boolean facingSameDirection,
85 final Length length, final Speed speed, final Acceleration acceleration, final GTUStatus... gtuStatus)
86 throws GTUException
87 {
88 super(ObjectType.GTU, id, distance, length, speed, acceleration);
89 this.facingSameDirection = facingSameDirection;
90 this.gtuType = gtuType;
91 for (GTUStatus status : gtuStatus)
92 {
93 this.gtuStatus.add(status);
94 }
95 }
96
97 /**
98 * Construct a new Headway information object, for a non-moving GTU ahead of us or behind us.
99 * @param id String; the id of the GTU for comparison purposes, can not be null.
100 * @param gtuType GTUType; the perceived GTU Type, or null if unknown.
101 * @param distance Length; the distance to the other GTU; if this constructor is used, distance cannot be null.
102 * @param facingSameDirection whether the GTU is facing the same direction.
103 * @param length the (perceived) length of the other object; can not be null.
104 * @throws GTUException when id is null, or parameters are inconsistent
105 */
106 public AbstractHeadwayGTU(final String id, final GTUType gtuType, final Length distance, final boolean facingSameDirection,
107 final Length length) throws GTUException
108 {
109 super(ObjectType.GTU, id, distance, length);
110 this.facingSameDirection = facingSameDirection;
111 this.gtuType = gtuType;
112 }
113
114 /**
115 * Construct a new Headway information object, for a moving GTU parallel with us.
116 * @param id the id of the GTU for comparison purposes, can not be null.
117 * @param gtuType the perceived GTU Type, or null if unknown.
118 * @param overlapFront the front-front distance to the other GTU; if this constructor is used, this value cannot be null.
119 * @param overlap the 'center' overlap with the other GTU; if this constructor is used, this value cannot be null.
120 * @param overlapRear the rear-rear distance to the other GTU; if this constructor is used, this value cannot be null.
121 * @param facingSameDirection whether the GTU is facing the same direction.
122 * @param length the (perceived) length of the other object; can not be null.
123 * @param speed the (perceived) speed of the other GTU; can be null if unknown.
124 * @param acceleration the (perceived) acceleration of the other GTU; can be null if unknown.
125 * @throws GTUException when id is null, or parameters are inconsistent
126 */
127 @SuppressWarnings("checkstyle:parameternumber")
128 public AbstractHeadwayGTU(final String id, final GTUType gtuType, final Length overlapFront, final Length overlap,
129 final Length overlapRear, final boolean facingSameDirection, final Length length, final Speed speed,
130 final Acceleration acceleration) throws GTUException
131 {
132 super(ObjectType.GTU, id, overlapFront, overlap, overlapRear, length, speed, acceleration);
133 this.facingSameDirection = facingSameDirection;
134 this.gtuType = gtuType;
135 }
136
137 /**
138 * Construct a new Headway information object, for a non-moving GTU parallel with us.
139 * @param id the id of the GTU for comparison purposes, can not be null.
140 * @param gtuType the perceived GTU Type, or null if unknown.
141 * @param overlapFront the front-front distance to the other GTU; if this constructor is used, this value cannot be null.
142 * @param overlap the 'center' overlap with the other GTU; if this constructor is used, this value cannot be null.
143 * @param overlapRear the rear-rear distance to the other GTU; if this constructor is used, this value cannot be null.
144 * @param facingSameDirection whether the GTU is facing the same direction.
145 * @param length the (perceived) length of the other object; can not be null.
146 * @throws GTUException when id is null, or parameters are inconsistent
147 */
148 public AbstractHeadwayGTU(final String id, final GTUType gtuType, final Length overlapFront, final Length overlap,
149 final Length overlapRear, final boolean facingSameDirection, final Length length) throws GTUException
150 {
151 super(ObjectType.GTU, id, overlapFront, overlap, overlapRear, length);
152 this.facingSameDirection = facingSameDirection;
153 this.gtuType = gtuType;
154 }
155
156 /**
157 * @return gtuType
158 */
159 public final GTUType getGtuType()
160 {
161 return this.gtuType;
162 }
163
164 /**
165 * @return facingSameDirection
166 */
167 public final boolean isFacingSameDirection()
168 {
169 return this.facingSameDirection;
170 }
171
172 /** @return were the braking lights on? */
173 public final boolean isBrakingLightsOn()
174 {
175 return this.gtuStatus.contains(GTUStatus.BRAKING_LIGHTS);
176 }
177
178 /** @return was the left turn indicator on? */
179 public final boolean isLeftTurnIndicatorOn()
180 {
181 return this.gtuStatus.contains(GTUStatus.LEFT_TURNINDICATOR);
182 }
183
184 /** @return was the right turn indicator on? */
185 public final boolean isRightTurnIndicatorOn()
186 {
187 return this.gtuStatus.contains(GTUStatus.RIGHT_TURNINDICATOR);
188 }
189
190 /** @return were the emergency lights on? */
191 public final boolean isEmergencyLightsOn()
192 {
193 return this.gtuStatus.contains(GTUStatus.EMERGENCY_LIGHTS);
194 }
195
196 /** @return was the vehicle honking or ringing its bell when being observed for the headway? */
197 public final boolean isHonking()
198 {
199 return this.gtuStatus.contains(GTUStatus.HONK);
200 }
201
202 /**
203 * Many models that observe a GTU need to predict the imminent behavior of that GTU. Having a car following model of the
204 * observed GTU can help with that. The car following model that is returned can be on a continuum between the actual car
205 * following model of the observed GTU and the own car following model of the observing GTU, not making any assumptions
206 * about the observed GTU. When successive observations of the GTU take place, parameters about its behavior can be
207 * estimated more accurately. Another interesting easy-to-implement solution is to return a car following model per GTU
208 * type, where the following model of a truck can differ from that of a car.
209 * @return a car following model that represents the expected behavior of the observed GTU
210 */
211 public abstract CarFollowingModel getCarFollowingModel();
212
213 /**
214 * Many models that observe a GTU need to predict the imminent behavior of that GTU. Having an estimate of the behavioral
215 * characteristics of the observed GTU can help with that. The behavioral characteristics that are returned can be on a
216 * continuum between the actual behavioral characteristics of the observed GTU and the own behavioral characteristics of the
217 * observing GTU, not making any assumptions about the observed GTU. When successive observations of the GTU take place,
218 * parameters about its behavior can be estimated more accurately. Another interesting easy-to-implement solution is to
219 * return a set of behavioral characteristics per GTU type, where the behavioral characteristics of a truck can differ from
220 * that of a car.
221 * @return the behavioral characteristics that represent the expected behavior of the observed GTU
222 */
223 public abstract BehavioralCharacteristics getBehavioralCharacteristics();
224
225 /**
226 * Many models that observe a GTU need to predict the imminent behavior of that GTU. Having a model of the speed info
227 * profile for the observed GTU can help with predicting its future behavior. The speed limit info that is returned can be
228 * on a continuum between the actual speed limit model of the observed GTU and the own speed limit model of the observing
229 * GTU, not making any assumptions about the observed GTU. When successive observations of the GTU take place, parameters
230 * about its behavior, such as the maximum speed it accepts, can be estimated more accurately. Another interesting
231 * easy-to-implement solution is to return a speed limit info object per GTU type, where the returned information of a truck
232 * -- with a maximum allowed speed on 80 km/h -- can differ from that of a car -- which can have a maximum allowed speed of
233 * 100 km/h on the same road.
234 * @return a speed limit model that helps in determining the expected behavior of the observed GTU
235 */
236 public abstract SpeedLimitInfo getSpeedLimitInfo();
237
238 /** {@inheritDoc} */
239 @Override
240 public final String toString()
241 {
242 return "HeadwayGTU [gtuType=" + this.gtuType + ", gtuStatus=" + this.gtuStatus + "]";
243 }
244
245 }