1 package org.opentrafficsim.road.gtu.lane.perception.headway;
2
3 import org.djunits.value.vdouble.scalar.Acceleration;
4 import org.djunits.value.vdouble.scalar.Length;
5 import org.djunits.value.vdouble.scalar.Speed;
6 import org.opentrafficsim.core.perception.PerceivedObject;
7
8 /**
9 * Interface for a reference to information about a (lane based) GTU and a headway. The Headway can store information about GTUs
10 * or objects ahead of the reference GTU, behind the reference GTU, or (partially) parallel to the reference GTU. In addition to
11 * the (perceived) headway, several other pieces of information can be stored, such as (perceived) speed, (perceived)
12 * acceleration, (perceived) turn indicators, and (perceived) braking lights. <br>
13 * Special care must be taken in curves when perceiving headway of a GTU or object on an adjacent lane.The question is whether
14 * we perceive the parallel or ahead/behind based on a line perpendicular to the front/back of the GTU (rectangular), or
15 * perpendicular to the center line of the lane (wedge-shaped in case of a curve). The difficulty of a wedge-shaped situation is
16 * that reciprocity might be violated: in case of a clothoid, for instance, it is not sure that the point on the center line
17 * 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
18 * sharp bends. Therefore, algorithms implementing headway should only project the <i>reference point</i> of the reference GTU
19 * on the center line of the adjacent lane, and then calculate the forward position and backward position on the adjacent lane
20 * based on the reference point. Still, our human perception of what is parallel and what not, is not reflected by fractional
21 * positions. See examples in
22 * <a href= "http://simulation.tudelft.nl:8085/browse/OTS-113">http://simulation.tudelft.nl:8085/browse/OTS-113</a>.
23 * <p>
24 * Copyright (c) 2013-2018 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: 1368 $, $LastChangedDate: 2015-09-02 00:20:20 +0200 (Wed, 02 Sep 2015) $, by $Author: averbraeck $,
28 * initial version 11 feb. 2015 <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 Headway extends PerceivedObject, Comparable<Headway>
33 {
34 /** the object types that can be distinguished for headway. */
35 enum ObjectType
36 {
37 /** the observed object for headway is a GTU. */
38 GTU,
39
40 /** the observed object for headway is a traffic light. */
41 TRAFFICLIGHT,
42
43 /** the observed object for headway is a generic object. */
44 OBJECT,
45
46 /** there is no observed object, just a distance. */
47 DISTANCEONLY,
48
49 /** intersection conflict. */
50 CONFLICT,
51
52 /** stop line. */
53 STOPLINE,
54
55 /** bus stop. */
56 BUSSTOP;
57
58 /** @return whether this object is a GTU or not. */
59 public boolean isGtu()
60 {
61 return this.equals(GTU);
62 }
63
64 /** @return whether this object is a GTU or not. */
65 public boolean isTrafficLight()
66 {
67 return this.equals(TRAFFICLIGHT);
68 }
69
70 /** @return whether this object is an object or not. */
71 public boolean isObject()
72 {
73 return this.equals(OBJECT);
74 }
75
76 /** @return whether no object was observed and only a distance was stored. */
77 public boolean isDistanceOnly()
78 {
79 return this.equals(DISTANCEONLY);
80 }
81
82 /** @return whether this object is a conflict or not. */
83 public boolean isConflict()
84 {
85 return this.equals(CONFLICT);
86 }
87
88 /** @return whether this object is a stop line or not. */
89 public boolean isStopLine()
90 {
91 return this.equals(STOPLINE);
92 }
93
94 /** @return whether this object is a bus stop or not. */
95 public boolean isBusStop()
96 {
97 return this.equals(BUSSTOP);
98 }
99
100 }
101
102 /**
103 * @return String; the id of the other object for comparison purposes, cannot be null.
104 */
105 @Override
106 String getId();
107
108 /**
109 * @return Length; the length of the other object; can be null if unknown.
110 */
111 Length getLength();
112
113 /**
114 * @return Speed; the (perceived) speed of the other object; can be null if unknown.
115 */
116 Speed getSpeed();
117
118 /**
119 * Retrieve the strongly typed distance to the other object.
120 * @return Length; the distance to the object, return value null indicates that the other object is parallel to the
121 * reference object
122 */
123 Length getDistance();
124
125 /**
126 * @return Length; the (perceived) object Type, can be null if no object type unknown.
127 */
128 ObjectType getObjectType();
129
130 /**
131 * @return Acceleration; acceleration the (perceived) acceleration of the other object; can be null if unknown.
132 */
133 Acceleration getAcceleration();
134
135 /**
136 * Return the (perceived) front overlap to the other object. This value should be null if there is no overlap. In the figure
137 * for two GTUs below, it is distance c, positive for GTU1, negative for GTU2.
138 *
139 * <pre>
140 * ----------
141 * | GTU 1 | ----->
142 * ----------
143 * ---------------
144 * | GTU 2 | ----->
145 * ---------------
146 * | a | b | c |
147 * </pre>
148 *
149 * @return Length; the (perceived) front overlap to the other object or null if there is no overlap.
150 */
151 Length getOverlapFront();
152
153 /**
154 * Return the (perceived) rear overlap to the other object. This value should be null if there is no overlap.In the figure
155 * below for two GTUs, it is distance a, positive for GTU1, negative for GTU2.
156 *
157 * <pre>
158 * ----------
159 * | GTU 1 | ----->
160 * ----------
161 * ---------------
162 * | GTU 2 | ----->
163 * ---------------
164 * | a | b | c |
165 * </pre>
166 *
167 * @return Length; the (perceived) rear overlap to the other object or null if there is no overlap.
168 */
169 Length getOverlapRear();
170
171 /**
172 * Return the (perceived) overlap with the other object. This value should be null if there is no overlap. In the figure
173 * below for two GTUs, it is distance b, positive for GTU1 and GTU2.
174 *
175 * <pre>
176 * ----------
177 * | GTU 1 | ----->
178 * ----------
179 * ---------------
180 * | GTU 2 | ----->
181 * ---------------
182 * | a | b | c |
183 * </pre>
184 *
185 * @return Length, the (perceived) overlap with the other object or null if there is no overlap.
186 */
187 Length getOverlap();
188
189 /**
190 * @return whether the other object is in front of the reference object.
191 */
192 boolean isAhead();
193
194 /**
195 * @return whether the other object is behind the reference object.
196 */
197 boolean isBehind();
198
199 /**
200 * @return whether the other object is parallel the reference object.
201 */
202 boolean isParallel();
203
204 /** {@inheritDoc} */
205 @Override
206 default int compareTo(final Headway headway)
207 {
208 if (getDistance() != null)
209 {
210 if (headway.getDistance() != null)
211 {
212 return getDistance().compareTo(headway.getDistance());
213 }
214 return 1;
215 }
216 else if (headway.getDistance() != null)
217 {
218 return -1;
219 }
220 return getOverlapFront().compareTo(headway.getOverlapFront());
221 }
222 }