1 package org.opentrafficsim.road.gtu.lane.perception;
2
3 import java.util.Iterator;
4 import java.util.function.Supplier;
5
6 import org.djunits.value.vdouble.scalar.Length;
7 import org.opentrafficsim.road.gtu.lane.perception.headway.Headway;
8
9 /**
10 * Iterable that additionally provides support for PerceptionCollectors. These gather raw data, to only 'perceive' the result.
11 * <p>
12 * Copyright (c) 2013-2022 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
13 * BSD-style license. See <a href="http://opentrafficsim.org/node/13">OpenTrafficSim License</a>.
14 * <p>
15 * @version $Revision$, $LastChangedDate$, by $Author$, initial version 1 mrt. 2018 <br>
16 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
17 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
18 * @author <a href="http://www.transport.citg.tudelft.nl">Wouter Schakel</a>
19 * @param <H> headway type
20 * @param <U> underlying object type
21 */
22 public interface PerceptionCollectable<H extends Headway, U> extends PerceptionIterable<H>
23 {
24
25 /**
26 * Collect the underlying objects in to a perceived result. This methodology is loosely based on Stream.collect().
27 * @param collector PerceptionCollector<C, ? super U, I>; collector
28 * @param <C> collection result type
29 * @param <I> intermediate type
30 * @return C; collection result
31 */
32 default <C, I> C collect(final PerceptionCollector<C, ? super U, I> collector)
33 {
34 return collect(collector.getIdentity(), collector.getAccumulator(), collector.getFinalizer());
35 }
36
37 /**
38 * Collect the underlying objects in to a perceived result. This methodology is loosely based on Stream.collect().
39 * @param identity Supplier<I>; the initial intermediate result value
40 * @param accumulator PerceptionAccumulator<? super U, I>; accumulator
41 * @param finalizer PerceptionFinalizer<C, I>; finalizer
42 * @param <C> collection result type
43 * @param <I> intermediate type
44 * @return C; collection result
45 */
46 <C, I> C collect(Supplier<I> identity, PerceptionAccumulator<? super U, I> accumulator,
47 PerceptionFinalizer<C, I> finalizer);
48
49 /**
50 * Returns an iterator over the underlying objects.
51 * @return Iterator<U>; iterator
52 */
53 Iterator<U> underlying();
54
55 /**
56 * Returns an iterator over the underlying objects coupled with the distance.
57 * @return Iterator<UnderlyingDistance<U>>; iterator
58 */
59 Iterator<UnderlyingDistance<U>> underlyingWithDistance();
60
61 /**
62 * Combination of an accumulator and a finalizer.
63 * <p>
64 * Copyright (c) 2013-2022 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
65 * <br>
66 * BSD-style license. See <a href="http://opentrafficsim.org/node/13">OpenTrafficSim License</a>.
67 * <p>
68 * @version $Revision$, $LastChangedDate$, by $Author$, initial version 28 feb. 2018 <br>
69 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
70 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
71 * @author <a href="http://www.transport.citg.tudelft.nl">Wouter Schakel</a>
72 * @param <C> collection result type
73 * @param <U> underlying object type
74 * @param <I> intermediate result type
75 */
76 public interface PerceptionCollector<C, U, I>
77 {
78 /**
79 * Returns the identity value, the initial intermediate value.
80 * @return I; identity value, the initial intermediate value
81 */
82 Supplier<I> getIdentity();
83
84 /**
85 * Returns the accumulator.
86 * @return PerceptionAccumulator; accumulator
87 */
88 PerceptionAccumulator<U, I> getAccumulator();
89
90 /**
91 * Returns the finalizer.
92 * @return PerceptionFinalizer; finalizer
93 */
94 PerceptionFinalizer<C, I> getFinalizer();
95 }
96
97 /**
98 * Accumulates an object one at a time in to an accumulating intermediate result.
99 * <p>
100 * Copyright (c) 2013-2022 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
101 * <br>
102 * BSD-style license. See <a href="http://opentrafficsim.org/node/13">OpenTrafficSim License</a>.
103 * <p>
104 * @version $Revision$, $LastChangedDate$, by $Author$, initial version 28 feb. 2018 <br>
105 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
106 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
107 * @author <a href="http://www.transport.citg.tudelft.nl">Wouter Schakel</a>
108 * @param <U> underlying object type
109 * @param <I> intermediate result type
110 */
111 public interface PerceptionAccumulator<U, I>
112 {
113 /**
114 * Accumulate the next object to intermediate result.
115 * @param intermediate Intermediate<I>; intermediate result before accumulation of object
116 * @param object U; next object to include
117 * @param distance Length; distance to the considered object
118 * @return I; intermediate result after accumulation of object
119 */
120 Intermediate<I> accumulate(Intermediate<I> intermediate, U object, Length distance);
121 }
122
123 /**
124 * Translates the last intermediate result of an accumulator in to the collection output.
125 * <p>
126 * Copyright (c) 2013-2022 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
127 * <br>
128 * BSD-style license. See <a href="http://opentrafficsim.org/node/13">OpenTrafficSim License</a>.
129 * <p>
130 * @version $Revision$, $LastChangedDate$, by $Author$, initial version 28 feb. 2018 <br>
131 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
132 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
133 * @author <a href="http://www.transport.citg.tudelft.nl">Wouter Schakel</a>
134 * @param <C> collection result type
135 * @param <I> intermediate result type
136 */
137 public interface PerceptionFinalizer<C, I>
138 {
139 /**
140 * Translate the last intermediate result in to a final result.
141 * @param intermediate I; last intermediate result
142 * @return C; final result
143 */
144 C collect(I intermediate);
145 }
146
147 /**
148 * Wrapper of intermediate result with info for the iterator algorithm.
149 * <p>
150 * Copyright (c) 2013-2022 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
151 * <br>
152 * BSD-style license. See <a href="http://opentrafficsim.org/node/13">OpenTrafficSim License</a>.
153 * <p>
154 * @version $Revision$, $LastChangedDate$, by $Author$, initial version 3 apr. 2018 <br>
155 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
156 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
157 * @author <a href="http://www.transport.citg.tudelft.nl">Wouter Schakel</a>]
158 * @param <I> intermediate result type
159 */
160 class Intermediate<I>
161 {
162 /** Number of underlying object being iterated. */
163 private int number = 0;
164
165 /** Intermediate object. */
166 private I object;
167
168 /** Whether to stop accumulating. */
169 private boolean stop = false;
170
171 /**
172 * Constructor.
173 * @param object I; identity value
174 */
175 public Intermediate(final I object)
176 {
177 this.object = object;
178 }
179
180 /**
181 * Get intermediate object.
182 * @return I; intermediate object
183 */
184 public I getObject()
185 {
186 return this.object;
187 }
188
189 /**
190 * Set intermediate object.
191 * @param object I; intermediate object
192 */
193 public void setObject(final I object)
194 {
195 this.object = object;
196 }
197
198 /**
199 * Returns the number of the underlying object currently being accumulated, starts at 0 for the first.
200 * @return int; number of the underlying object currently being accumulated
201 */
202 public int getNumber()
203 {
204 return this.number;
205 }
206
207 /**
208 * Method for the iterator to increase the underlying object number.
209 */
210 public void step()
211 {
212 this.number++;
213 }
214
215 /**
216 * Method for the accumulator to indicate the iterator can stop.
217 */
218 public void stop()
219 {
220 this.stop = true;
221 }
222
223 /**
224 * Method for the iterator to check if it can stop.
225 * @return boolean; whether the iterator can stop
226 */
227 public boolean isStop()
228 {
229 return this.stop;
230 }
231 }
232
233 /**
234 * Wrapper for object and its distance.
235 * <p>
236 * Copyright (c) 2013-2022 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
237 * <br>
238 * BSD-style license. See <a href="http://opentrafficsim.org/node/13">OpenTrafficSim License</a>.
239 * <p>
240 * @version $Revision$, $LastChangedDate$, by $Author$, initial version Aug 6, 2019 <br>
241 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
242 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
243 * @author <a href="http://www.transport.citg.tudelft.nl">Wouter Schakel</a>
244 * @param <U> underlying object type
245 */
246 class UnderlyingDistance<U>
247 {
248 /** Object. */
249 final U object;
250
251 /** Distance. */
252 final Length distance;
253
254 /**
255 * @param object U; object
256 * @param distance Length; distance
257 */
258 public UnderlyingDistance(final U object, final Length distance)
259 {
260 this.object = object;
261 this.distance = distance;
262 }
263
264 /**
265 * @return U; object.
266 */
267 public U getObject()
268 {
269 return this.object;
270 }
271
272 /**
273 * @return Length; distance.
274 */
275 public Length getDistance()
276 {
277 return this.distance;
278 }
279 }
280
281 }