RollingLaneStructure (Open Traffic Sim road classes 1.00.02 API)

java.lang.Object
- org.opentrafficsim.road.gtu.lane.perception.RollingLaneStructure

All Implemented Interfaces:: Serializable, LaneStructure

public class RollingLaneStructure
extends Object
implements LaneStructure, Serializable

This data structure can clearly indicate the lane structure ahead of us, e.g. in the following situation:

     (---- a ----)(---- b ----)(---- c ----)(---- d ----)(---- e ----)(---- f ----)(---- g ----)  
                                             __________                             __________
                                            / _________ 1                          / _________ 2
                                           / /                                    / /
                                __________/ /             _______________________/ /
  1  ____________ ____________ /_ _ _ _ _ _/____________ /_ _ _ _ _ _ _ _ _ _ _ _ /      
  0 |_ _X_ _ _ _ |_ _ _ _ _ _ |_ _ _ _ _ _ |_ _ _ _ _ _ |_ _ _ _ _ _ |_ _ _ _ _ _ \____________
 -1 |____________|_ _ _ _ _ _ |____________|____________|  __________|____________|____________| 3
 -2              / __________/                           \ \  
        ________/ /                                       \ \___________  
      5 _________/                                         \____________  4

When the GTU is looking ahead, it needs to know that when it continues to destination 3, it needs to shift one lane to the right at some point, but not two lanes to the right in link b, and not later than at the end of link f. When it needs to go to destination 1, it needs to shift to the left in link c. When it has to go to destination 2, it has to shift to the left, but not earlier than at link e. At node [de], it is possible to leave the rightmost lane of link e, and go to destination 4. The rightmost lane just splits into two lanes at the end of link d, and the GTU can either continue driving to destination 3, turn right to destination 4. This means that the right lane of link d has two successor lanes.

In the data structures, lanes are numbered laterally. Suppose that the lane where vehicle X resides would be number 0. Consistent with "left is positive" for angles, the lane right of X would have number -1, and entry 5 would have number -2.

In the data structure, this can be indicated as follows (N = next, P = previous, L = left, R = right, D = lane drop, . = continued but not in this structure). The merge lane in b is considered "off limits" for the GTUs on the "main" lane -1; the "main" lane 0 is considered off limits from the exit lanes on c, e, and f. Still, we need to maintain pointers to these lanes, as we are interested in the GTUs potentially driving next to us, feeding into our lane, etc.

       1                0               -1               -2
       
                       ROOT 
                   _____|_____      ___________      ___________            
                  |_-_|_._|_R_|----|_L_|_._|_-_|    |_-_|_._|_-_|  a           
                        |                |                |
                   _____V_____      _____V_____      _____V_____            
                  |_-_|_N_|_R_|----|_L_|_N_|_R_|<---|_L_|_D_|_-_|  b           
                        |                |                 
  ___________      _____V_____      _____V_____                 
 |_-_|_N_|_R_|<---|_L_|_N_|_R_|----|_L_|_N_|_-_|                   c
       |                |                |                 
  _____V_____      _____V_____      _____V_____                 
 |_-_|_._|_-_|    |_-_|_N_|_R_|----|_L_|_NN|_-_|                   d          
                        |                ||_______________ 
  ___________      _____V_____      _____V_____      _____V_____            
 |_-_|_N_|_R_|<---|_L_|_N_|_R_|----|_L_|_N_|_-_|    |_-_|_N_|_-_|  e          
       |                |                |                |
  _____V_____      _____V_____      _____V_____      _____V_____            
 |_-_|_N_|_R_|<---|_L_|_D_|_R_|----|_L_|_N_|_-_|    |_-_|_._|_-_|  f          
       |                                 |                 
  _____V_____                       _____V_____                             
 |_-_|_._|_-_|                     |_-_|_._|_-_|                   g

Copyright (c) 2013-2018 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
BSD-style license. See OpenTrafficSim License.

$LastChangedDate: 2015-07-24 02:58:59 +0200 (Fri, 24 Jul 2015) $, @version $Revision: 1147 $, by $Author: averbraeck $, initial version Feb 20, 2016

Author:: Alexander Verbraeck
See Also:: Serialized Form

Nested Class Summary
- Nested classes/interfaces inherited from interface org.opentrafficsim.road.gtu.lane.perception.LaneStructure
  LaneStructure.Entry<T extends LaneBasedObject>

Constructor Summary

Constructors
Constructor and Description
`RollingLaneStructure(Length lookAhead, Length down, Length up, Length downSplit, Length upMerge, LaneBasedGTU gtu)` Constructor.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`<T extends LaneBasedObject> Map<RelativeLane,SortedSet<LaneStructure.Entry<T>>>`	`getDownstreamObjects(Class<T> clazz, LaneBasedGTU gtu, RelativePosition.TYPE pos)` Retrieve objects of a specific type.
`<T extends LaneBasedObject> SortedSet<LaneStructure.Entry<T>>`	`getDownstreamObjects(RelativeLane lane, Class<T> clazz, LaneBasedGTU gtu, RelativePosition.TYPE pos)` Retrieve objects on a lane of a specific type.
`<T extends LaneBasedObject> Map<RelativeLane,SortedSet<LaneStructure.Entry<T>>>`	`getDownstreamObjectsOnRoute(Class<T> clazz, LaneBasedGTU gtu, RelativePosition.TYPE pos, Route route)` Retrieve objects of a specific type.
`<T extends LaneBasedObject> SortedSet<LaneStructure.Entry<T>>`	`getDownstreamObjectsOnRoute(RelativeLane lane, Class<T> clazz, LaneBasedGTU gtu, RelativePosition.TYPE pos, Route route)` Retrieve objects on a lane of a specific type.
`SortedSet<RelativeLane>`	`getExtendedCrossSection()` Returns the extended cross-section, which includes all lanes for which a first record is present.
`RollingLaneStructureRecord`	`getFirstRecord(RelativeLane lane)` Returns the first record on the given lane.
`LaneStructureRecord`	`getRootRecord()` Returns the root record.
`LaneStructureRecord`	`getRootRecord(Time time)`
`<T extends LaneBasedObject> SortedSet<LaneStructure.Entry<T>>`	`getUpstreamObjects(RelativeLane lane, Class<T> clazz, LaneBasedGTU gtu, RelativePosition.TYPE pos)` Retrieve objects on a lane of a specific type.
`String`	`toString()`
`void`	`update(DirectedLanePosition pos, Route route, GTUType gtuType)` Updates the underlying structure shifting the root position to the input.
`void`	`visualize(GTU gtu)` Enables visualization of this lane structure.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail
- RollingLaneStructure
```
public RollingLaneStructure(Length lookAhead,
                            Length down,
                            Length up,
                            Length downSplit,
                            Length upMerge,
                            LaneBasedGTU gtu)
```
  Constructor.
  
  Parameters:
  
  lookAhead - Length; distance over which visual objects are included
  
  down - Length; downstream distance over which the structure is made
  
  up - Length; upstream distance over which the structure is made, should include a margin for reaction time
  
  downSplit - Length; downstream distance at splits (links not on route) included in the structure
  
  upMerge - Length; upstream distance at downstream merges (links not on route) included in the structure
  
  gtu - LaneBasedGTU; GTU

Method Detail

update
```
public final void update(DirectedLanePosition pos,
                         Route route,
                         GTUType gtuType)
                  throws GTUException
```
Updates the underlying structure shifting the root position to the input.

Specified by:

update in interface LaneStructure

Parameters:

pos - DirectedLanePosition; current position of the GTU

route - Route; current route of the GTU

gtuType - GTUType; GTU type

Throws:

GTUException - on a problem while updating the structure

getRootRecord
```
public final LaneStructureRecord getRootRecord()
```
Returns the root record.

Specified by:

getRootRecord in interface LaneStructure

Returns:

LaneRecord; root record

getRootRecord
```
public final LaneStructureRecord getRootRecord(Time time)
```
Parameters:

time - Time; time to obtain the root at

Returns:

rootRecord

getExtendedCrossSection
```
public final SortedSet<RelativeLane> getExtendedCrossSection()
```
Returns the extended cross-section, which includes all lanes for which a first record is present.

Specified by:

getExtendedCrossSection in interface LaneStructure

Returns:

SortedSet; the cross-section

getFirstRecord
```
public final RollingLaneStructureRecord getFirstRecord(RelativeLane lane)
```
Returns the first record on the given lane. This is often a record in the current cross section, but it may be one downstream for a lane that starts further downstream.

Specified by:

getFirstRecord in interface LaneStructure

Parameters:

lane - RelativeLane; lane

Returns:

first record on the given lane, or null if no such record

getDownstreamObjects

public final <T extends LaneBasedObject> Map<RelativeLane,SortedSet<LaneStructure.Entry<T>>> getDownstreamObjects(Class<T> clazz,
                                                                                                                  LaneBasedGTU gtu,
                                                                                                                  RelativePosition.TYPE pos)
                                                                                                           throws GTUException

Retrieve objects of a specific type. Returns objects over a maximum length of the look ahead distance downstream from the relative position, or as far as the lane map goes.

Specified by:: getDownstreamObjects in interface LaneStructure
Type Parameters:: T - type of objects to find
Parameters:: clazz - class of objects to find; gtu - gtu; pos - relative position to start search from
Returns:: Sorted set of objects of requested type per lane
Throws:: GTUException - if lane is not in current set

getDownstreamObjects

public final <T extends LaneBasedObject> SortedSet<LaneStructure.Entry<T>> getDownstreamObjects(RelativeLane lane,
                                                                                                Class<T> clazz,
                                                                                                LaneBasedGTU gtu,
                                                                                                RelativePosition.TYPE pos)
                                                                                         throws GTUException

Retrieve objects on a lane of a specific type. Returns objects over a maximum length of the look ahead distance downstream from the relative position, or as far as the lane map goes.

Specified by:: getDownstreamObjects in interface LaneStructure
Type Parameters:: T - type of objects to find
Parameters:: lane - lane; clazz - class of objects to find; gtu - gtu; pos - relative position to start search from
Returns:: Sorted set of objects of requested type
Throws:: GTUException - if lane is not in current set

getDownstreamObjectsOnRoute

public final <T extends LaneBasedObject> SortedSet<LaneStructure.Entry<T>> getDownstreamObjectsOnRoute(RelativeLane lane,
                                                                                                       Class<T> clazz,
                                                                                                       LaneBasedGTU gtu,
                                                                                                       RelativePosition.TYPE pos,
                                                                                                       Route route)
                                                                                                throws GTUException

Retrieve objects on a lane of a specific type. Returns objects over a maximum length of the look ahead distance downstream from the relative position, or as far as the lane map goes. Objects on links not on the route are ignored.

Specified by:: getDownstreamObjectsOnRoute in interface LaneStructure
Type Parameters:: T - type of objects to find
Parameters:: lane - lane; clazz - class of objects to find; gtu - gtu; pos - relative position to start search from; route - the route
Returns:: Sorted set of objects of requested type
Throws:: GTUException - if lane is not in current set

getDownstreamObjectsOnRoute

public final <T extends LaneBasedObject> Map<RelativeLane,SortedSet<LaneStructure.Entry<T>>> getDownstreamObjectsOnRoute(Class<T> clazz,
                                                                                                                         LaneBasedGTU gtu,
                                                                                                                         RelativePosition.TYPE pos,
                                                                                                                         Route route)
                                                                                                                  throws GTUException

Retrieve objects of a specific type. Returns objects over a maximum length of the look ahead distance downstream from the relative position, or as far as the lane map goes. Objects on links not on the route are ignored.

Specified by:: getDownstreamObjectsOnRoute in interface LaneStructure
Type Parameters:: T - type of objects to find
Parameters:: clazz - class of objects to find; gtu - gtu; pos - relative position to start search from; route - the route
Returns:: Sorted set of objects of requested type per lane
Throws:: GTUException - if lane is not in current set

getUpstreamObjects

public final <T extends LaneBasedObject> SortedSet<LaneStructure.Entry<T>> getUpstreamObjects(RelativeLane lane,
                                                                                              Class<T> clazz,
                                                                                              LaneBasedGTU gtu,
                                                                                              RelativePosition.TYPE pos)
                                                                                       throws GTUException

Retrieve objects on a lane of a specific type. Returns upstream objects from the relative position for as far as the lane map goes. Distances to upstream objects are given as positive values.

Specified by:: getUpstreamObjects in interface LaneStructure
Type Parameters:: T - type of objects to find
Parameters:: lane - lane; clazz - class of objects to find; gtu - gtu; pos - relative position to start search from
Returns:: Sorted set of objects of requested type
Throws:: GTUException - if lane is not in current set

toString
```
public final String toString()
```
Overrides:

toString in class Object

visualize
```
public final void visualize(GTU gtu)
```
Enables visualization of this lane structure. This is purely for debugging purposes.

Parameters:

gtu - GTU to animate the LaneStructure off

Class RollingLaneStructure

Nested Class Summary

Nested classes/interfaces inherited from interface org.opentrafficsim.road.gtu.lane.perception.LaneStructure

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

RollingLaneStructure

Method Detail

update

getRootRecord

getRootRecord

getExtendedCrossSection

getFirstRecord

getDownstreamObjects

getDownstreamObjects

getDownstreamObjectsOnRoute

getDownstreamObjectsOnRoute

getUpstreamObjects

toString

visualize