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.
22 * <p>
23 * Copyright (c) 2013-2024 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
24 * BSD-style license. See <a href="https://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
25 * </p>
26 * @author <a href="https://github.com/averbraeck">Alexander Verbraeck</a>
27 * @author <a href="https://tudelft.nl/staff/p.knoppers-1">Peter Knoppers</a>
28 */
29 public interface Headway extends PerceivedObject, Comparable<Headway>
30 {
31 /** the object types that can be distinguished for headway. */
32 enum ObjectType
33 {
34 /** the observed object for headway is a GTU. */
35 GTU,
36
37 /** the observed object for headway is a traffic light. */
38 TRAFFICLIGHT,
39
40 /** the observed object for headway is a generic object. */
41 OBJECT,
42
43 /** there is no observed object, just a distance. */
44 DISTANCEONLY,
45
46 /** intersection conflict. */
47 CONFLICT,
48
49 /** stop line. */
50 STOPLINE,
51
52 /** bus stop. */
53 BUSSTOP;
54
55 /** @return whether this object is a GTU or not. */
56 public boolean isGtu()
57 {
58 return this.equals(GTU);
59 }
60
61 /** @return whether this object is a GTU or not. */
62 public boolean isTrafficLight()
63 {
64 return this.equals(TRAFFICLIGHT);
65 }
66
67 /** @return whether this object is an object or not. */
68 public boolean isObject()
69 {
70 return this.equals(OBJECT);
71 }
72
73 /** @return whether no object was observed and only a distance was stored. */
74 public boolean isDistanceOnly()
75 {
76 return this.equals(DISTANCEONLY);
77 }
78
79 /** @return whether this object is a conflict or not. */
80 public boolean isConflict()
81 {
82 return this.equals(CONFLICT);
83 }
84
85 /** @return whether this object is a stop line or not. */
86 public boolean isStopLine()
87 {
88 return this.equals(STOPLINE);
89 }
90
91 /** @return whether this object is a bus stop or not. */
92 public boolean isBusStop()
93 {
94 return this.equals(BUSSTOP);
95 }
96
97 }
98
99 /**
100 * @return String; the id of the other object for comparison purposes, cannot be null.
101 */
102 @Override
103 String getId();
104
105 /**
106 * @return Length; the length of the other object; can be null if unknown.
107 */
108 Length getLength();
109
110 /**
111 * @return Speed; the (perceived) speed of the other object; can be null if unknown.
112 */
113 Speed getSpeed();
114
115 /**
116 * Retrieve the strongly typed distance to the other object.
117 * @return Length; the distance to the object, return value null indicates that the other object is parallel to the
118 * reference object
119 */
120 Length getDistance();
121
122 /**
123 * @return Length; the (perceived) object Type, can be null if no object type unknown.
124 */
125 ObjectType getObjectType();
126
127 /**
128 * @return Acceleration; acceleration the (perceived) acceleration of the other object; can be null if unknown.
129 */
130 Acceleration getAcceleration();
131
132 /**
133 * Return the (perceived) front overlap to the other object. This value should be null if there is no overlap. In the figure
134 * for two GTUs below, it is distance c, positive for GTU1, negative for GTU2.
135 *
136 * <pre>
137 * ----------
138 * | GTU 1 | ----->
139 * ----------
140 * ---------------
141 * | GTU 2 | ----->
142 * ---------------
143 * | a | b | c |
144 * </pre>
145 *
146 * @return Length; the (perceived) front overlap to the other object or null if there is no overlap.
147 */
148 Length getOverlapFront();
149
150 /**
151 * Return the (perceived) rear overlap to the other object. This value should be null if there is no overlap.In the figure
152 * below for two GTUs, it is distance a, positive for GTU1, negative for GTU2.
153 *
154 * <pre>
155 * ----------
156 * | GTU 1 | ----->
157 * ----------
158 * ---------------
159 * | GTU 2 | ----->
160 * ---------------
161 * | a | b | c |
162 * </pre>
163 *
164 * @return Length; the (perceived) rear overlap to the other object or null if there is no overlap.
165 */
166 Length getOverlapRear();
167
168 /**
169 * Return the (perceived) overlap with the other object. This value should be null if there is no overlap. In the figure
170 * below for two GTUs, it is distance b, positive for GTU1 and GTU2.
171 *
172 * <pre>
173 * ----------
174 * | GTU 1 | ----->
175 * ----------
176 * ---------------
177 * | GTU 2 | ----->
178 * ---------------
179 * | a | b | c |
180 * </pre>
181 *
182 * @return Length, the (perceived) overlap with the other object or null if there is no overlap.
183 */
184 Length getOverlap();
185
186 /**
187 * @return whether the other object is in front of the reference object.
188 */
189 boolean isAhead();
190
191 /**
192 * @return whether the other object is behind the reference object.
193 */
194 boolean isBehind();
195
196 /**
197 * @return whether the other object is parallel the reference object.
198 */
199 boolean isParallel();
200
201 /** {@inheritDoc} */
202 @Override
203 default int compareTo(final Headway headway)
204 {
205 if (getDistance() != null)
206 {
207 if (headway.getDistance() != null)
208 {
209 return getDistance().compareTo(headway.getDistance());
210 }
211 return 1;
212 }
213 else if (headway.getDistance() != null)
214 {
215 return -1;
216 }
217 return getOverlapFront().compareTo(headway.getOverlapFront());
218 }
219 }