1 package org.opentrafficsim.road.gtu.lane.perception;
2
3 import org.djunits.value.vdouble.scalar.Length;
4 import org.djunits.value.vdouble.scalar.Time;
5 import org.opentrafficsim.base.parameters.ParameterException;
6 import org.opentrafficsim.base.parameters.ParameterTypeLength;
7 import org.opentrafficsim.base.parameters.ParameterTypes;
8 import org.opentrafficsim.core.gtu.GtuException;
9 import org.opentrafficsim.core.gtu.perception.AbstractPerception;
10 import org.opentrafficsim.core.network.NetworkException;
11 import org.opentrafficsim.road.gtu.lane.LaneBasedGtu;
12 import org.opentrafficsim.road.gtu.lane.perception.mental.Mental;
13 import org.opentrafficsim.road.network.lane.LanePosition;
14
15 /**
16 * The perception module of a GTU based on lanes. It is responsible for perceiving (sensing) the environment of the GTU, which
17 * includes the locations of other GTUs. Perception is done at a certain time, and the perceived information might have a
18 * limited validity. In that sense, Perception is stateful. Information can be requested as often as needed, but will only be
19 * recalculated when asked explicitly. This abstract class provides the building blocks for lane-based perception. <br>
20 * Perception for lane-based GTUs involves information about GTUs in front of the owner GTU on the same lane (the 'leader' GTU),
21 * parallel vehicles (important if we want to change lanes), distance to other vehicles on parallel lanes, as well in front as
22 * to the back (important if we want to change lanes), and information about obstacles, traffic lights, speed signs, and ending
23 * lanes.
24 * <p>
25 * This class allows {@code PerceptionCategory}s that are either eager or lazy. All categories will have the {@code updateAll}
26 * method invoked prior to an operational plan being determined. Categories may ignore this and instead evaluate results only
27 * when the tactical planner requests them.
28 * <p>
29 * Copyright (c) 2013-2024 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
30 * BSD-style license. See <a href="https://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
31 * </p>
32 * @author <a href="https://github.com/averbraeck">Alexander Verbraeck</a>
33 * @author <a href="https://tudelft.nl/staff/p.knoppers-1">Peter Knoppers</a>
34 * @author <a href="https://github.com/wjschakel">Wouter Schakel</a>
35 */
36 public abstract class AbstractLanePerception extends AbstractPerception<LaneBasedGtu> implements LanePerception
37 {
38
39 /** */
40 private static final long serialVersionUID = 20151128L;
41
42 /** Perception parameter type. */
43 protected static final ParameterTypeLength PERCEPTION = ParameterTypes.PERCEPTION;
44
45 /** Look ahead parameter type. */
46 protected static final ParameterTypeLength LOOKAHEAD = ParameterTypes.LOOKAHEAD;
47
48 /** Look back parameter type. */
49 protected static final ParameterTypeLength LOOKBACK = ParameterTypes.LOOKBACK;
50
51 /** Lane structure to perform the perception with. */
52 private LaneStructure laneStructure = null;
53
54 /** Most recent update time of lane structure. */
55 private Time updateTime = null;
56
57 /** Mental module. */
58 private Mental mental;
59
60 /**
61 * Create a new LanePerception module without mental module.
62 * @param gtu LaneBasedGtu; GTU
63 */
64 public AbstractLanePerception(final LaneBasedGtu gtu)
65 {
66 super(gtu);
67 this.mental = null;
68 }
69
70 /**
71 * Create a new LanePerception module with mental module.
72 * @param gtu LaneBasedGtu; GTU
73 * @param mental Mental; mental module
74 */
75 public AbstractLanePerception(final LaneBasedGtu gtu, final Mental mental)
76 {
77 super(gtu);
78 this.mental = mental;
79 }
80
81 /** {@inheritDoc} */
82 @Override
83 public final LaneStructure getLaneStructure() throws ParameterException
84 {
85
86 if (this.laneStructure == null || this.updateTime.lt(getGtu().getSimulator().getSimulatorAbsTime()))
87 {
88 if (this.laneStructure == null)
89 {
90 // downstream structure length
91 Length down = getGtu().getParameters().getParameter(PERCEPTION);
92 // upstream structure length
93 Length up = getGtu().getParameters().getParameter(LOOKBACK);
94 // structure length downstream of split on link not on route
95 Length lookAhead = getGtu().getParameters().getParameter(LOOKAHEAD);
96 // structure length upstream of merge on link not on route
97 Length upMerge = Length.max(up, lookAhead);
98 // negative values for upstream
99 up = up.neg();
100 upMerge = upMerge.neg();
101 this.laneStructure = new RollingLaneStructure(lookAhead, down, up, lookAhead, upMerge, getGtu());
102 }
103 LanePosition dlp;
104 try
105 {
106 dlp = getGtu().getReferencePosition();
107 this.laneStructure.update(dlp, getGtu().getStrategicalPlanner().getRoute(), getGtu().getType());
108 }
109 catch (GtuException exception)
110 {
111 exception.printStackTrace();
112 throw new RuntimeException("Error while updating the lane map.", exception);
113 }
114 this.updateTime = getGtu().getSimulator().getSimulatorAbsTime();
115 }
116 return this.laneStructure;
117 }
118
119 /** {@inheritDoc} */
120 @Override
121 public Mental getMental()
122 {
123 return this.mental;
124 }
125
126 /** {@inheritDoc} */
127 @Override
128 public void perceive() throws GtuException, NetworkException, ParameterException
129 {
130 if (this.mental != null)
131 {
132 this.mental.apply(this);
133 }
134 super.perceive();
135 }
136
137 }