1 package org.opentrafficsim.road.gtu.lane.perception;
2
3 import java.util.Map;
4 import java.util.SortedSet;
5
6 import org.djunits.value.vdouble.scalar.Length;
7 import org.opentrafficsim.core.gtu.GTUException;
8 import org.opentrafficsim.core.gtu.GTUType;
9 import org.opentrafficsim.core.gtu.RelativePosition;
10 import org.opentrafficsim.core.network.route.Route;
11 import org.opentrafficsim.road.gtu.lane.LaneBasedGTU;
12 import org.opentrafficsim.road.network.lane.DirectedLanePosition;
13 import org.opentrafficsim.road.network.lane.object.LaneBasedObject;
14
15 /**
16 * Interface for lane structures.
17 * <p>
18 * Copyright (c) 2013-2019 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
19 * BSD-style license. See <a href="http://opentrafficsim.org/node/13">OpenTrafficSim License</a>.
20 * <p>
21 * @version $Revision$, $LastChangedDate$, by $Author$, initial version 13 aug. 2018 <br>
22 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
23 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
24 * @author <a href="http://www.transport.citg.tudelft.nl">Wouter Schakel</a>
25 */
26 public interface LaneStructure
27 {
28
29 /**
30 * Updates the underlying structure shifting the root position to the input.
31 * @param pos DirectedLanePosition; current position of the GTU
32 * @param route Route; current route of the GTU
33 * @param gtuType GTUType; GTU type
34 * @throws GTUException on a problem while updating the structure
35 */
36 void update(DirectedLanePosition pos, Route route, GTUType gtuType) throws GTUException;
37
38 /**
39 * Returns the root record.
40 * @return LaneRecord; root record
41 */
42 LaneStructureRecord getRootRecord();
43
44 /**
45 * Returns the extended cross-section, which includes all lanes for which a first record is present.
46 * @return SortedSet; the cross-section
47 */
48 SortedSet<RelativeLane> getExtendedCrossSection();
49
50 /**
51 * Returns the first record on the given lane. This is often a record in the current cross section, but it may be one
52 * downstream for a lane that starts further downstream.
53 * @param lane RelativeLane; lane
54 * @return first record on the given lane, or {@code null} if no such record
55 */
56 LaneStructureRecord getFirstRecord(RelativeLane lane);
57
58 /**
59 * Retrieve objects of a specific type. Returns objects over a maximum length of the look ahead distance downstream from the
60 * relative position, or as far as the lane structure goes.
61 * @param clazz Class<T>; class of objects to find
62 * @param gtu LaneBasedGTU; gtu
63 * @param pos RelativePosition.TYPE; relative position to start search from
64 * @param <T> type of objects to find
65 * @return Map; sorted set of objects of requested type per lane
66 * @throws GTUException if lane is not in current set
67 */
68 <T extends LaneBasedObject> Map<RelativeLane, SortedSet<Entry<T>>> getDownstreamObjects(Class<T> clazz, LaneBasedGTU gtu,
69 RelativePosition.TYPE pos) throws GTUException;
70
71 /**
72 * Retrieve objects on a lane of a specific type. Returns objects over a maximum length of the look ahead distance
73 * downstream from the relative position, or as far as the lane structure goes.
74 * @param lane RelativeLane; lane
75 * @param clazz Class<T>; class of objects to find
76 * @param gtu LaneBasedGTU; gtu
77 * @param pos RelativePosition.TYPE; relative position to start search from
78 * @param <T> type of objects to find
79 * @return SortedSet; sorted set of objects of requested type
80 * @throws GTUException if lane is not in current set
81 */
82 <T extends LaneBasedObject> SortedSet<Entry<T>> getDownstreamObjects(RelativeLane lane, Class<T> clazz, LaneBasedGTU gtu,
83 RelativePosition.TYPE pos) throws GTUException;
84
85 /**
86 * Retrieve objects of a specific type. Returns objects over a maximum length of the look ahead distance downstream from the
87 * relative position, or as far as the lane structure goes. Objects on links not on the route are ignored.
88 * @param clazz Class<T>; class of objects to find
89 * @param gtu LaneBasedGTU; gtu
90 * @param pos RelativePosition.TYPE; relative position to start search from
91 * @param <T> type of objects to find
92 * @param route Route; the route
93 * @return SortedSet; sorted set of objects of requested type per lane
94 * @throws GTUException if lane is not in current set
95 */
96 <T extends LaneBasedObject> Map<RelativeLane, SortedSet<Entry<T>>> getDownstreamObjectsOnRoute(Class<T> clazz,
97 LaneBasedGTU gtu, RelativePosition.TYPE pos, Route route) throws GTUException;
98
99 /**
100 * Retrieve objects on a lane of a specific type. Returns objects over a maximum length of the look ahead distance
101 * downstream from the relative position, or as far as the lane structure goes. Objects on links not on the route are
102 * ignored.
103 * @param lane RelativeLane; lane
104 * @param clazz Class<T>; class of objects to find
105 * @param gtu LaneBasedGTU; gtu
106 * @param pos RelativePosition.TYPE; relative position to start search from
107 * @param <T> type of objects to find
108 * @param route Route; the route
109 * @return SortedSet; sorted set of objects of requested type
110 * @throws GTUException if lane is not in current set
111 */
112 <T extends LaneBasedObject> SortedSet<Entry<T>> getDownstreamObjectsOnRoute(RelativeLane lane, Class<T> clazz,
113 LaneBasedGTU gtu, RelativePosition.TYPE pos, Route route) throws GTUException;
114
115 /**
116 * Retrieve objects on a lane of a specific type. Returns upstream objects from the relative position for as far as the lane
117 * structure goes. Distances to upstream objects are given as positive values.
118 * @param lane RelativeLane; lane
119 * @param clazz Class<T>; class of objects to find
120 * @param gtu LaneBasedGTU; gtu
121 * @param pos RelativePosition.TYPE; relative position to start search from
122 * @param <T> type of objects to find
123 * @return SortedSet; sorted set of objects of requested type
124 * @throws GTUException if lane is not in current set
125 */
126 <T extends LaneBasedObject> SortedSet<Entry<T>> getUpstreamObjects(RelativeLane lane, Class<T> clazz, LaneBasedGTU gtu,
127 RelativePosition.TYPE pos) throws GTUException;
128
129 /**
130 * Wrapper to hold lane-based object and it's distance.
131 * <p>
132 * Copyright (c) 2013-2019 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
133 * <br>
134 * BSD-style license. See <a href="http://opentrafficsim.org/docs/current/license.html">OpenTrafficSim License</a>.
135 * <p>
136 * @version $Revision$, $LastChangedDate$, by $Author$, initial version Sep 15, 2016 <br>
137 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
138 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
139 * @author <a href="http://www.transport.citg.tudelft.nl">Wouter Schakel</a>
140 * @param <T> class of lane based object contained
141 */
142 class Entry<T extends LaneBasedObject> implements Comparable<Entry<T>>
143 {
144
145 /** Distance to lane based object. */
146 private final Length distance;
147
148 /** Lane based object. */
149 private final T laneBasedObject;
150
151 /**
152 * @param distance Length; distance to lane based object
153 * @param laneBasedObject T; lane based object
154 */
155 public Entry(final Length distance, final T laneBasedObject)
156 {
157 this.distance = distance;
158 this.laneBasedObject = laneBasedObject;
159 }
160
161 /**
162 * @return distance.
163 */
164 public final Length getDistance()
165 {
166 return this.distance;
167 }
168
169 /**
170 * @return laneBasedObject.
171 */
172 public final T getLaneBasedObject()
173 {
174 return this.laneBasedObject;
175 }
176
177 /** {@inheritDoc} */
178 @Override
179 public final int hashCode()
180 {
181 final int prime = 31;
182 int result = 1;
183 result = prime * result + ((this.distance == null) ? 0 : this.distance.hashCode());
184 result = prime * result + ((this.laneBasedObject == null) ? 0 : this.laneBasedObject.hashCode());
185 return result;
186 }
187
188 /** {@inheritDoc} */
189 @Override
190 public final boolean equals(final Object obj)
191 {
192 if (this == obj)
193 {
194 return true;
195 }
196 if (obj == null)
197 {
198 return false;
199 }
200 if (getClass() != obj.getClass())
201 {
202 return false;
203 }
204 Entry<?> other = (Entry<?>) obj;
205 if (this.distance == null)
206 {
207 if (other.distance != null)
208 {
209 return false;
210 }
211 }
212 else if (!this.distance.equals(other.distance))
213 {
214 return false;
215 }
216 if (this.laneBasedObject == null)
217 {
218 if (other.laneBasedObject != null)
219 {
220 return false;
221 }
222 }
223 // laneBasedObject does not implement equals...
224 else if (!this.laneBasedObject.equals(other.laneBasedObject))
225 {
226 return false;
227 }
228 return true;
229 }
230
231 /** {@inheritDoc} */
232 @Override
233 public final int compareTo(final Entry<T> arg)
234 {
235 int d = this.distance.compareTo(arg.distance);
236 if (d != 0 || this.laneBasedObject.equals(arg.laneBasedObject))
237 {
238 return d; // different distance (-1 or 1), or same distance but also equal lane based object (0)
239 }
240 return 1; // same distance, unequal lane based object (1)
241 }
242
243 /** {@inheritDoc} */
244 @Override
245 public final String toString()
246 {
247 return "LaneStructure.Entry [distance=" + this.distance + ", laneBasedObject=" + this.laneBasedObject + "]";
248 }
249
250 }
251
252 }