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 <a href=
22 * "http://simulation.tudelft.nl:8085/browse/OTS-113">http://simulation.tudelft.nl:8085/browse/OTS-113</a>.
23 * <p>
24 * Copyright (c) 2013-2016 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 /** @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 }
92
93 /**
94 * @return String; the id of the other object for comparison purposes, cannot be null.
95 */
96 String getId();
97
98 /**
99 * @return Length; the length of the other object; can be null if unknown.
100 */
101 Length getLength();
102
103 /**
104 * @return Speed; the (perceived) speed of the other object; can be null if unknown.
105 */
106 Speed getSpeed();
107
108 /**
109 * Retrieve the strongly typed distance to the other object.
110 * @return Length; the distance to the object, return value null indicates that the other object is parallel to the
111 * reference object
112 */
113 Length getDistance();
114
115 /**
116 * @return Length; the (perceived) object Type, can be null if no object type unknown.
117 */
118 ObjectType getObjectType();
119
120 /**
121 * @return Acceleration; acceleration the (perceived) acceleration of the other object; can be null if unknown.
122 */
123 Acceleration getAcceleration();
124
125 /**
126 * Return the (perceived) front overlap to the other object. This value should be null if there is no overlap. In the figure
127 * for two GTUs below, it is distance c, positive for GTU1, negative for GTU2.
128 *
129 * <pre>
130 * ----------
131 * | GTU 1 | ----->
132 * ----------
133 * ---------------
134 * | GTU 2 | ----->
135 * ---------------
136 * | a | b | c |
137 * </pre>
138 * @return Length; the (perceived) front overlap to the other object or null if there is no overlap.
139 */
140 Length getOverlapFront();
141
142 /**
143 * Return the (perceived) rear overlap to the other object. This value should be null if there is no overlap.In the figure
144 * below for two GTUs, it is distance a, positive for GTU1, negative for GTU2.
145 *
146 * <pre>
147 * ----------
148 * | GTU 1 | ----->
149 * ----------
150 * ---------------
151 * | GTU 2 | ----->
152 * ---------------
153 * | a | b | c |
154 * </pre>
155 * @return Length; the (perceived) rear overlap to the other object or null if there is no overlap.
156 */
157 Length getOverlapRear();
158
159 /**
160 * Return the (perceived) overlap with the other object. This value should be null if there is no overlap. In the figure
161 * below for two GTUs, it is distance b, positive for GTU1 and GTU2.
162 *
163 * <pre>
164 * ----------
165 * | GTU 1 | ----->
166 * ----------
167 * ---------------
168 * | GTU 2 | ----->
169 * ---------------
170 * | a | b | c |
171 * </pre>
172 * @return Length, the (perceived) overlap with the other object or null if there is no overlap.
173 */
174 Length getOverlap();
175
176 /**
177 * @return whether the other object is in front of the reference object.
178 */
179 boolean isAhead();
180
181 /**
182 * @return whether the other object is behind the reference object.
183 */
184 boolean isBehind();
185
186 /**
187 * @return whether the other object is behind the reference object.
188 */
189 boolean isParallel();
190
191 /** {@inheritDoc} */
192 @Override
193 default int compareTo(Headway headway)
194 {
195 return getDistance().compareTo(headway.getDistance());
196 }
197 }