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