org.opentrafficsim.road.network.lane

Class Lane

java.lang.Object

nl.tudelft.simulation.event.EventProducer

org.opentrafficsim.road.network.lane.CrossSectionElement

org.opentrafficsim.road.network.lane.Lane

All Implemented Interfaces:

Serializable, Locatable, EventProducerInterface, Identifiable, Drawable

Direct Known Subclasses:

NoTrafficLane

public class Lane
extends CrossSectionElement
implements Serializable

The Lane is the CrossSectionElement of a CrossSectionLink on which GTUs can drive. The Lane stores several important properties, such as the successor lane(s), predecessor lane(s), and adjacent lane(s), all separated per GTU type. It can, for instance, be that a truck is not allowed to move into an adjacent lane, while a car is allowed to do so. Furthermore, the lane contains sensors that can be triggered by passing GTUs. The Lane class also contains methods to determine to trigger the sensors at exactly calculated and scheduled times, given the movement of the GTUs.
Finally, the Lane stores the GTUs on the lane, and contains several access methods to determine successor and predecessor GTUs, as well as methods to add a GTU to a lane (either at the start or in the middle when changing lanes), and remove a GTU from the lane (either at the end, or in the middle when changing onto another lane).

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

$LastChangedDate: 2015-09-24 14:17:07 +0200 (Thu, 24 Sep 2015) $, @version $Revision: 1407 $, by $Author: averbraeck $, initial version Aug 19, 2014

Author:

Alexander Verbraeck, Peter Knoppers

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static EventType	GTU_ADD_EVENT The timed event type for pub/sub indicating the addition of a GTU to the lane.
static EventType	GTU_REMOVE_EVENT The timed event type for pub/sub indicating the removal of a GTU from the lane.
static Length	MARGIN Lateral alignment margin for longitudinally connected Lanes.
static EventType	OBJECT_ADD_EVENT The event type for pub/sub indicating the addition of a LaneBasedObject to the lane.
static EventType	OBJECT_REMOVE_EVENT The event type for pub/sub indicating the removal of a LaneBasedObject from the lane.
static EventType	SENSOR_ADD_EVENT The timed event type for pub/sub indicating the addition of a Sensor to the lane.
static EventType	SENSOR_REMOVE_EVENT The timed event type for pub/sub indicating the removal of a Sensor from the lane.

Fields inherited from class org.opentrafficsim.road.network.lane.CrossSectionElement

crossSectionSlices, length, parentLink

Fields inherited from class nl.tudelft.simulation.event.EventProducer

listeners

Fields inherited from interface nl.tudelft.simulation.event.EventProducerInterface

FIRST_POSITION, LAST_POSITION

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Lane(CrossSectionLink newParentLink, SimulatorInterface.TimeDoubleUnit newSimulator, Lane cse) Clone a Lane for a new network.
	Lane(CrossSectionLink parentLink, String id, Length lateralOffset, Length width, LaneType laneType, Map<GTUType,Speed> speedLimitMap, OvertakingConditions overtakingConditions) Construct a new Lane.
	Lane(CrossSectionLink parentLink, String id, Length lateralOffset, Length width, LaneType laneType, Speed speedLimit, OvertakingConditions overtakingConditions) Construct a new Lane.
	Lane(CrossSectionLink parentLink, String id, Length lateralOffsetAtStart, Length lateralOffsetAtEnd, Length beginWidth, Length endWidth, LaneType laneType, Map<GTUType,Speed> speedLimitMap, OvertakingConditions overtakingConditions) Construct a new Lane.
	Lane(CrossSectionLink parentLink, String id, Length lateralOffsetAtStart, Length lateralOffsetAtEnd, Length beginWidth, Length endWidth, LaneType laneType, Speed speedLimit, OvertakingConditions overtakingConditions) Construct a new Lane.
	Lane(CrossSectionLink parentLink, String id, List<CrossSectionSlice> crossSectionSlices, LaneType laneType, Map<GTUType,Speed> speedLimitMap, OvertakingConditions overtakingConditions) Construct a new Lane.
	Lane(CrossSectionLink parentLink, String id, List<CrossSectionSlice> crossSectionSlices, LaneType laneType, Speed speedLimit, OvertakingConditions overtakingConditions) Construct a new Lane.

Method Summary

Modifier and Type	Method and Description
Set<Lane>	accessibleAdjacentLanesLegal(LateralDirectionality lateralDirection, GTUType gtuType, GTUDirectionality drivingDirection) Determine the set of lanes to the left or to the right of this lane, which are accessible from this lane, or an empty set if no lane could be found.
Set<Lane>	accessibleAdjacentLanesPhysical(LateralDirectionality lateralDirection, GTUType gtuType, GTUDirectionality drivingDirection) Determine the set of lanes to the left or to the right of this lane, which are accessible from this lane, or an empty set if no lane could be found.
int	addGTU(LaneBasedGTU gtu, double fractionalPosition) Add a LaneBasedGTU to the list of this Lane.
int	addGTU(LaneBasedGTU gtu, Length longitudinalPosition) Add a LaneBasedGTU to the list of this Lane.
void	addLaneBasedObject(LaneBasedObject laneBasedObject) Insert a laneBasedObject at the right place in the laneBasedObject list of this Lane.
void	addSensor(SingleSensor sensor) Insert a sensor at the right place in the sensor list of this Lane.
Lane	clone(CrossSectionLink newParentLink, SimulatorInterface.TimeDoubleUnit newSimulator) Clone the CrossSectionElement for e.g., copying a network.
Map<Lane,GTUDirectionality>	downstreamLanes(GTUDirectionality direction, GTUType gtuType) Returns the lanes that could be followed in a given direction and for the given GTU type.
boolean	equals(Object obj)
double	fraction(Length position) Transform a position on the lane (can be less than zero or larger than the lane length) to a fraction.
double	fractionSI(double positionSI) Transform a position on the lane in SI units (can be less than zero or larger than the lane length) to a fraction.
LaneBasedGTU	getFirstGtu(GTUDirectionality direction) Get the first GTU on the lane, relative to a driving direction on this lane.
LaneBasedGTU	getGtu(int index) Returns the index'th GTU.
LaneBasedGTU	getGtu(int index, Time time) Returns the index'th GTU at specified time.
LaneBasedGTU	getGtuAhead(Length position, GTUDirectionality direction, RelativePosition.TYPE relativePosition, Time when) Get the first GTU where the relativePosition is in front of another GTU on the lane, in a driving direction on this lane, compared to the DESIGN LINE.
LaneBasedGTU	getGtuBehind(Length position, GTUDirectionality direction, RelativePosition.TYPE relativePosition, Time when) Get the first GTU where the relativePosition is behind a certain position on the lane, in a driving direction on this lane, compared to the DESIGN LINE.
ImmutableList<LaneBasedGTU>	getGtuList()
List<LaneBasedGTU>	getGtuList(Time time) Returns the list of GTU's at the specified time.
Speed	getHighestSpeedLimit() Get the highest speed limit of this lane.
SortedMap<Double,List<LaneBasedObject>>	getLaneBasedObjectMap() Retrieve the list of LaneBasedObjects of this Lane.
List<LaneBasedObject>	getLaneBasedObjects() Retrieve the list of all LaneBasedObjects of this Lane.
List<LaneBasedObject>	getLaneBasedObjects(Length minimumPosition, Length maximumPosition) Retrieve the list of LaneBasedObjects of this Lane in the specified distance range.
LaneType	getLaneType()
LaneBasedGTU	getLastGtu(GTUDirectionality direction) Get the last GTU on the lane, relative to a driving direction on this lane.
Speed	getLowestSpeedLimit() Get the lowest speed limit of this lane.
List<LaneBasedObject>	getObjectAhead(Length position, GTUDirectionality direction) Get the first object where the relativePosition is in front of a certain position on the lane, in a driving direction on this lane, compared to the DESIGN LINE.
List<LaneBasedObject>	getObjectBehind(Length position, GTUDirectionality direction) Get the first object where the relativePosition is behind of a certain position on the lane, in a driving direction on this lane, compared to the DESIGN LINE.
OvertakingConditions	getOvertakingConditions()
SortedMap<Double,List<SingleSensor>>	getSensorMap(GTUType gtuType, GTUDirectionality direction) Retrieve the list of Sensors of this Lane for the given GTUType.
List<SingleSensor>	getSensors() Retrieve the list of all Sensors of this Lane.
List<SingleSensor>	getSensors(GTUType gtuType, GTUDirectionality direction) Retrieve the list of Sensors of this Lane that are triggered by the given GTUType.
List<SingleSensor>	getSensors(Length minimumPosition, Length maximumPosition, GTUType gtuType, GTUDirectionality direction) Retrieve the list of Sensors of this Lane in the specified distance range for the given GTUType.
Speed	getSpeedLimit(GTUType gtuType) Get the speed limit of this lane, which can differ per GTU type.
protected double	getZ() Retrieve the Z offset (used to determine what covers what when drawing).
int	hashCode()
int	indexOfGtu(LaneBasedGTU gtu) Returns the index of the given GTU, or -1 if not present.
int	indexOfGtu(LaneBasedGTU gtu, Time time) Returns the index of the given GTU, or -1 if not present, at specified time.
Map<Lane,GTUDirectionality>	nextLanes(GTUType gtuType) NextLanes returns the successor lane(s) in the design line direction, if any exist. The next lane(s) are cached, as it is too expensive to make the calculation every time.
int	numberOfGtus() Returns the number of GTU's.
int	numberOfGtus(Time time) Returns the number of GTU's at specified time.
Length	position(double fraction) Transform a fraction on the lane to a relative length (can be less than zero or larger than the lane length).
double	positionSI(double fraction) Transform a fraction on the lane to a relative length in SI units (can be less than zero or larger than the lane length).
Map<Lane,GTUDirectionality>	prevLanes(GTUType gtuType) PrevLanes returns the predecessor lane(s) relative to the design line direction, if any exist. The previous lane(s) are cached, as it is too expensive to make the calculation every time.
void	removeGTU(LaneBasedGTU gtu, boolean removeFromParentLink, Length position) Remove a GTU from the GTU list of this lane.
void	removeLaneBasedObject(LaneBasedObject laneBasedObject) Remove a laneBasedObject from the laneBasedObject list of this Lane.
void	removeSensor(SingleSensor sensor) Remove a sensor from the sensor list of this Lane.
void	removeSpeedLimit(GTUType gtuType) Remove the set speed limit for a GTUType.
void	scheduleSensorTriggers(LaneBasedGTU gtu, double referenceStartSI, double referenceMoveSI) Schedule triggering of the sensors for a certain time step; from now until the nextEvaluationTime of the GTU.
void	setSpeedLimit(GTUType gtuType, Speed speedLimit) Set the speed limit of this lane, which can differ per GTU type.
String	toString()
Map<Lane,GTUDirectionality>	upstreamLanes(GTUDirectionality direction, GTUType gtuType) Returns the lanes that could precede in a given direction and for the given GTU type.

Methods inherited from class org.opentrafficsim.road.network.lane.CrossSectionElement

constructContour, getBeginWidth, getBounds, getCenterLine, getContour, getDesignLineOffsetAtBegin, getDesignLineOffsetAtEnd, getEndWidth, getFullId, getId, getLateralBoundaryPosition, getLateralBoundaryPosition, getLateralCenterPosition, getLateralCenterPosition, getLength, getLocation, getParentLink, getWidth, getWidth

Methods inherited from class nl.tudelft.simulation.event.EventProducer

addListener, addListener, addListener, addListener, fireEvent, fireEvent, fireEvent, fireEvent, fireEvent, fireEvent, fireEvent, fireEvent, fireEvent, fireEvent, fireTimedEvent, fireTimedEvent, fireTimedEvent, fireTimedEvent, fireTimedEvent, fireTimedEvent, fireTimedEvent, removeAllListeners, removeAllListeners, removeListener

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

GTU_ADD_EVENT

public static final EventType GTU_ADD_EVENT

The timed event type for pub/sub indicating the addition of a GTU to the lane.
Payload: Object[] {String gtuId, LaneBasedGTU gtu, int count_after_addition}

GTU_REMOVE_EVENT

public static final EventType GTU_REMOVE_EVENT

The timed event type for pub/sub indicating the removal of a GTU from the lane.
Payload: Object[] {String gtuId, LaneBasedGTU gtu, int count_after_removal, Length position}

SENSOR_ADD_EVENT

public static final EventType SENSOR_ADD_EVENT

The timed event type for pub/sub indicating the addition of a Sensor to the lane.
Payload: Object[] {String sensorId, Sensor sensor}

SENSOR_REMOVE_EVENT

public static final EventType SENSOR_REMOVE_EVENT

The timed event type for pub/sub indicating the removal of a Sensor from the lane.
Payload: Object[] {String sensorId, Sensor sensor}

OBJECT_ADD_EVENT

public static final EventType OBJECT_ADD_EVENT

The event type for pub/sub indicating the addition of a LaneBasedObject to the lane.
Payload: Object[] {LaneBasedObject laneBasedObject}

OBJECT_REMOVE_EVENT

public static final EventType OBJECT_REMOVE_EVENT

The event type for pub/sub indicating the removal of a LaneBasedObject from the lane.
Payload: Object[] {LaneBasedObject laneBasedObject}

MARGIN

public static final Length MARGIN

Lateral alignment margin for longitudinally connected Lanes.

Constructor Detail

Lane

public Lane(CrossSectionLink parentLink,
            String id,
            Length lateralOffsetAtStart,
            Length lateralOffsetAtEnd,
            Length beginWidth,
            Length endWidth,
            LaneType laneType,
            Map<GTUType,Speed> speedLimitMap,
            OvertakingConditions overtakingConditions)
     throws OTSGeometryException,
            NetworkException

Construct a new Lane.

Parameters:

parentLink - CrossSectionLink; the link to which the new Lane will belong (must be constructed first)

id - String; the id of this lane within the link; should be unique within the link.

lateralOffsetAtStart - Length; the lateral offset of the design line of the new CrossSectionLink with respect to the design line of the parent Link at the start of the parent Link

lateralOffsetAtEnd - Length; the lateral offset of the design line of the new CrossSectionLink with respect to the design line of the parent Link at the end of the parent Link

beginWidth - Length; start width, positioned symmetrically around the design line

endWidth - Length; end width, positioned symmetrically around the design line

laneType - LaneType; the type of lane to deduce compatibility with GTU types

speedLimitMap - Map<GTUType, Speed>; speed limit on this lane, specified per GTU Type

overtakingConditions - OvertakingConditions; the conditions for overtaking another GTU, viewed from this lane

Throws:

OTSGeometryException - when creation of the center line or contour geometry fails

NetworkException - when id equal to null or not unique

Lane

public Lane(CrossSectionLink parentLink,
            String id,
            Length lateralOffsetAtStart,
            Length lateralOffsetAtEnd,
            Length beginWidth,
            Length endWidth,
            LaneType laneType,
            Speed speedLimit,
            OvertakingConditions overtakingConditions)
     throws OTSGeometryException,
            NetworkException

Construct a new Lane.

Parameters:

parentLink - CrossSectionLink; the link to which the element will belong (must be constructed first)

id - String; the id of this lane within the link; should be unique within the link.

lateralOffsetAtStart - Length; the lateral offset of the design line of the new CrossSectionLink with respect to the design line of the parent Link at the start of the parent Link

lateralOffsetAtEnd - Length; the lateral offset of the design line of the new CrossSectionLink with respect to the design line of the parent Link at the end of the parent Link

beginWidth - Length; start width, positioned symmetrically around the design line

endWidth - Length; end width, positioned symmetrically around the design line

laneType - LaneType; the type of lane to deduce compatibility with GTU types

speedLimit - Speed; speed limit on this lane

overtakingConditions - OvertakingConditions; the conditions for overtaking another GTU, viewed from this lane

Throws:

OTSGeometryException - when creation of the center line or contour geometry fails

NetworkException - when id equal to null or not unique

Lane

public Lane(CrossSectionLink parentLink,
            String id,
            Length lateralOffset,
            Length width,
            LaneType laneType,
            Map<GTUType,Speed> speedLimitMap,
            OvertakingConditions overtakingConditions)
     throws OTSGeometryException,
            NetworkException

Construct a new Lane.

Parameters:

parentLink - CrossSectionLink; the link to which the element will belong (must be constructed first)

id - String; the id of this lane within the link; should be unique within the link.

lateralOffset - Length; the lateral offset of the design line of the new CrossSectionLink with respect to the design line of the parent Link

width - Length; width, positioned symmetrically around the design line

laneType - LaneType; type of lane to deduce compatibility with GTU types

speedLimitMap - Map<GTUType, Speed>; the speed limit on this lane, specified per GTU Type

overtakingConditions - OvertakingConditions; the conditions for overtaking another GTU, viewed from this lane

Throws:

OTSGeometryException - when creation of the center line or contour geometry fails

NetworkException - when id equal to null or not unique

Lane

public Lane(CrossSectionLink parentLink,
            String id,
            Length lateralOffset,
            Length width,
            LaneType laneType,
            Speed speedLimit,
            OvertakingConditions overtakingConditions)
     throws OTSGeometryException,
            NetworkException

Construct a new Lane.

Parameters:

parentLink - CrossSectionLink; the link to which the element belongs (must be constructed first)

id - String; the id of this lane within the link; should be unique within the link

lateralOffset - Length; the lateral offset of the design line of the new CrossSectionLink with respect to the design line of the parent Link

width - Length; width, positioned symmetrically around the design line

laneType - LaneType; the type of lane to deduce compatibility with GTU types

speedLimit - Speed; the speed limit on this lane

overtakingConditions - OvertakingConditions; the conditions for overtaking another GTU, viewed from this lane

Throws:

OTSGeometryException - when creation of the center line or contour geometry fails

NetworkException - when id equal to null or not unique

Lane

public Lane(CrossSectionLink parentLink,
            String id,
            List<CrossSectionSlice> crossSectionSlices,
            LaneType laneType,
            Map<GTUType,Speed> speedLimitMap,
            OvertakingConditions overtakingConditions)
     throws OTSGeometryException,
            NetworkException

Construct a new Lane.

Parameters:

parentLink - CrossSectionLink; the link to which the element belongs (must be constructed first)

id - String; the id of this lane within the link; should be unique within the link.

crossSectionSlices - List<CrossSectionSlice>; the offsets and widths at positions along the line, relative to the design line of the parent link. If there is just one with and offset, there should just be one element in the list with Length = 0. If there are more slices, the last one should be at the length of the design line. If not, a NetworkException is thrown.

laneType - LaneType; the type of lane to deduce compatibility with GTU types

speedLimitMap - Map<GTUType, Speed>; the speed limit on this lane, specified per GTU Type

overtakingConditions - OvertakingConditions; the conditions for overtaking another GTU, viewed from this lane

Throws:

OTSGeometryException - when creation of the center line or contour geometry fails

NetworkException - when id equal to null or not unique

Lane

public Lane(CrossSectionLink parentLink,
            String id,
            List<CrossSectionSlice> crossSectionSlices,
            LaneType laneType,
            Speed speedLimit,
            OvertakingConditions overtakingConditions)
     throws OTSGeometryException,
            NetworkException

Construct a new Lane.

Parameters:

parentLink - CrossSectionLink; the link to which the element belongs (must be constructed first)

id - String; the id of this lane within the link; should be unique within the link.

crossSectionSlices - List<CrossSectionSlice>; the offsets and widths at positions along the line, relative to the design line of the parent link. If there is just one with and offset, there should just be one element in the list with Length = 0. If there are more slices, the last one should be at the length of the design line. If not, a NetworkException is thrown.

laneType - LaneType; the type of lane to deduce compatibility with GTU types

speedLimit - Speed; the speed limit on this lane

overtakingConditions - OvertakingConditions; the conditions for overtaking another GTU, viewed from this lane

Throws:

OTSGeometryException - when creation of the center line or contour geometry fails

NetworkException - when id equal to null or not unique

Lane

protected Lane(CrossSectionLink newParentLink,
               SimulatorInterface.TimeDoubleUnit newSimulator,
               Lane cse)
        throws NetworkException

Clone a Lane for a new network.

Parameters:

newParentLink - CrossSectionLink; the new link to which the clone belongs

newSimulator - SimulatorInterface.TimeDoubleUnit; the new simulator for this network

cse - Lane; the element to clone from

Throws:

NetworkException - if link already exists in the network, if name of the link is not unique, or if the start node or the end node of the link are not registered in the network.

Method Detail

addSensor

public final void addSensor(SingleSensor sensor)
                     throws NetworkException

Insert a sensor at the right place in the sensor list of this Lane.

Parameters:

sensor - SingleSensor; the sensor to add

Throws:

NetworkException - when the position of the sensor is beyond (or before) the range of this Lane

removeSensor

public final void removeSensor(SingleSensor sensor)
                        throws NetworkException

Remove a sensor from the sensor list of this Lane.

Parameters:

sensor - SingleSensor; the sensor to remove.

Throws:

NetworkException - when the sensor was not found on this Lane

getSensors

public final List<SingleSensor> getSensors(Length minimumPosition,
                                           Length maximumPosition,
                                           GTUType gtuType,
                                           GTUDirectionality direction)

Retrieve the list of Sensors of this Lane in the specified distance range for the given GTUType. The resulting list is a defensive copy.

Parameters:

minimumPosition - Length; the minimum distance on the Lane (inclusive)

maximumPosition - Length; the maximum distance on the Lane (inclusive)

gtuType - GTUType; the GTU type to provide the sensors for

direction - GTUDirectionality; direction of movement of the GTU

Returns:

List<Sensor>; list of the sensor in the specified range. This is a defensive copy.

getSensors

public final List<SingleSensor> getSensors(GTUType gtuType,
                                           GTUDirectionality direction)

Retrieve the list of Sensors of this Lane that are triggered by the given GTUType. The resulting list is a defensive copy.

Parameters:

gtuType - GTUType; the GTU type to provide the sensors for

direction - GTUDirectionality; direction of movement of the GTU

Returns:

List<Sensor>; list of the sensors, in ascending order for the location on the Lane

getSensors

public final List<SingleSensor> getSensors()

Retrieve the list of all Sensors of this Lane. The resulting list is a defensive copy.

Returns:

List<Sensor>; list of the sensors, in ascending order for the location on the Lane

getSensorMap

public final SortedMap<Double,List<SingleSensor>> getSensorMap(GTUType gtuType,
                                                               GTUDirectionality direction)

Retrieve the list of Sensors of this Lane for the given GTUType. The resulting Map is a defensive copy.

Parameters:

gtuType - GTUType; the GTU type to provide the sensors for

direction - GTUDirectionality; direction of movement of the GTU

Returns:

SortedMap<Double, List<Sensor>>; all sensors on this lane for the given GTUType as a map per distance

scheduleSensorTriggers

public final void scheduleSensorTriggers(LaneBasedGTU gtu,
                                         double referenceStartSI,
                                         double referenceMoveSI)
                                  throws NetworkException,
                                         SimRuntimeException

Schedule triggering of the sensors for a certain time step; from now until the nextEvaluationTime of the GTU.

Parameters:

gtu - LaneBasedGTU; the lane based GTU for which to schedule triggering of the sensors.

referenceStartSI - double; the SI distance of the GTU reference point on the lane at the current time

referenceMoveSI - double; the SI distance traveled in the next time step.

Throws:

NetworkException - when GTU not on this lane.

SimRuntimeException - when method cannot be scheduled.

addLaneBasedObject

public final void addLaneBasedObject(LaneBasedObject laneBasedObject)
                              throws NetworkException

Insert a laneBasedObject at the right place in the laneBasedObject list of this Lane. Register it in the network WITH the Lane id.

Parameters:

laneBasedObject - LaneBasedObject; the laneBasedObject to add

Throws:

NetworkException - when the position of the laneBasedObject is beyond (or before) the range of this Lane

removeLaneBasedObject

public final void removeLaneBasedObject(LaneBasedObject laneBasedObject)
                                 throws NetworkException

Remove a laneBasedObject from the laneBasedObject list of this Lane.

Parameters:

laneBasedObject - LaneBasedObject; the laneBasedObject to remove.

Throws:

NetworkException - when the laneBasedObject was not found on this Lane

getLaneBasedObjects

public final List<LaneBasedObject> getLaneBasedObjects(Length minimumPosition,
                                                       Length maximumPosition)

Retrieve the list of LaneBasedObjects of this Lane in the specified distance range. The resulting list is a defensive copy.

Parameters:

minimumPosition - Length; the minimum distance on the Lane (inclusive)

maximumPosition - Length; the maximum distance on the Lane (inclusive)

Returns:

List<LaneBasedObject>; list of the laneBasedObject in the specified range. This is a defensive copy.

getLaneBasedObjects

public final List<LaneBasedObject> getLaneBasedObjects()

Retrieve the list of all LaneBasedObjects of this Lane. The resulting list is a defensive copy.

Returns:

List<LaneBasedObject>; list of the laneBasedObjects, in ascending order for the location on the Lane

getLaneBasedObjectMap

public final SortedMap<Double,List<LaneBasedObject>> getLaneBasedObjectMap()

Retrieve the list of LaneBasedObjects of this Lane. The resulting Map is a defensive copy.

Returns:

SortedMap<Double, List<LaneBasedObject>>; all laneBasedObjects on this lane

position

public final Length position(double fraction)

Transform a fraction on the lane to a relative length (can be less than zero or larger than the lane length).

Parameters:

fraction - double; fraction relative to the lane length.

Returns:

Length; the longitudinal length corresponding to the fraction.

positionSI

public final double positionSI(double fraction)

Transform a fraction on the lane to a relative length in SI units (can be less than zero or larger than the lane length).

Parameters:

fraction - double; fraction relative to the lane length.

Returns:

double; length corresponding to the fraction, in SI units.

fraction

public final double fraction(Length position)

Transform a position on the lane (can be less than zero or larger than the lane length) to a fraction.

Parameters:

position - Length; relative length on the lane (may be less than zero or larger than the lane length).

Returns:

fraction double; fraction relative to the lane length.

fractionSI

public final double fractionSI(double positionSI)

Transform a position on the lane in SI units (can be less than zero or larger than the lane length) to a fraction.

Parameters:

positionSI - double; relative length on the lane in SI units (may be less than zero or larger than the lane length).

Returns:

double; fraction relative to the lane length.

addGTU

public final int addGTU(LaneBasedGTU gtu,
                        double fractionalPosition)
                 throws GTUException

Add a LaneBasedGTU to the list of this Lane.

Parameters:

gtu - LaneBasedGTU; the GTU to add

fractionalPosition - double; the fractional position that the newly added GTU will have on this Lane

Returns:

int; the rank that the newly added GTU has on this Lane (should be 0, except when the GTU enters this Lane due to a lane change operation)

Throws:

GTUException - when the fractionalPosition is outside the range 0..1, or the GTU is already registered on this Lane

addGTU

public final int addGTU(LaneBasedGTU gtu,
                        Length longitudinalPosition)
                 throws GTUException

Add a LaneBasedGTU to the list of this Lane.

Parameters:

gtu - LaneBasedGTU; the GTU to add

longitudinalPosition - Length; the longitudinal position that the newly added GTU will have on this Lane

Returns:

int; the rank that the newly added GTU has on this Lane (should be 0, except when the GTU enters this Lane due to a lane change operation)

Throws:

GTUException - when longitudinalPosition is negative or exceeds the length of this Lane

removeGTU

public final void removeGTU(LaneBasedGTU gtu,
                            boolean removeFromParentLink,
                            Length position)

Remove a GTU from the GTU list of this lane.

Parameters:

gtu - LaneBasedGTU; the GTU to remove.

removeFromParentLink - boolean; when the GTU leaves the last lane of the parentLink of this Lane

position - Length; last position of the GTU

getLastGtu

public final LaneBasedGTU getLastGtu(GTUDirectionality direction)
                              throws GTUException

Get the last GTU on the lane, relative to a driving direction on this lane.

Parameters:

direction - GTUDirectionality; whether we are looking in the the design line direction or against the center line direction.

Returns:

LaneBasedGTU; the last GTU on this lane in the given direction, or null if no GTU could be found.

Throws:

GTUException - when there is a problem with the position of the GTUs on the lane.

getFirstGtu

public final LaneBasedGTU getFirstGtu(GTUDirectionality direction)
                               throws GTUException

Get the first GTU on the lane, relative to a driving direction on this lane.

Parameters:

direction - GTUDirectionality; whether we are looking in the the design line direction or against the center line direction.

Returns:

LaneBasedGTU; the first GTU on this lane in the given direction, or null if no GTU could be found.

Throws:

GTUException - when there is a problem with the position of the GTUs on the lane.

getGtuAhead

public final LaneBasedGTU getGtuAhead(Length position,
                                      GTUDirectionality direction,
                                      RelativePosition.TYPE relativePosition,
                                      Time when)
                               throws GTUException

Get the first GTU where the relativePosition is in front of another GTU on the lane, in a driving direction on this lane, compared to the DESIGN LINE.

Parameters:

position - Length; the position before which the relative position of a GTU will be searched.

direction - GTUDirectionality; whether we are looking in the the center line direction or against the center line direction.

relativePosition - RelativePosition.TYPE; the relative position we want to compare against

when - Time; the time for which to evaluate the positions.

Returns:

LaneBasedGTU; the first GTU before a position on this lane in the given direction, or null if no GTU could be found.

Throws:

GTUException - when there is a problem with the position of the GTUs on the lane.

getObjectAhead

public final List<LaneBasedObject> getObjectAhead(Length position,
                                                  GTUDirectionality direction)

Get the first object where the relativePosition is in front of a certain position on the lane, in a driving direction on this lane, compared to the DESIGN LINE. Perception should iterate over results from this method to see what is most limiting.

Parameters:

position - Length; the position after which the relative position of an object will be searched.

direction - GTUDirectionality; whether we are looking in the the center line direction or against the center line direction.

Returns:

List<LaneBasedObject>; the first object(s) before a position on this lane in the given direction, or null if no object could be found.

getObjectBehind

public final List<LaneBasedObject> getObjectBehind(Length position,
                                                   GTUDirectionality direction)

Get the first object where the relativePosition is behind of a certain position on the lane, in a driving direction on this lane, compared to the DESIGN LINE. Perception should iterate over results from this method to see what is most limiting.

Parameters:

position - Length; the position after which the relative position of an object will be searched.

direction - GTUDirectionality; whether we are looking in the the center line direction or against the center line direction.

Returns:

List<LaneBasedObject>; the first object(s) after a position on this lane in the given direction, or null if no object could be found.

getGtuBehind

public final LaneBasedGTU getGtuBehind(Length position,
                                       GTUDirectionality direction,
                                       RelativePosition.TYPE relativePosition,
                                       Time when)
                                throws GTUException

Get the first GTU where the relativePosition is behind a certain position on the lane, in a driving direction on this lane, compared to the DESIGN LINE.

Parameters:

position - Length; the position before which the relative position of a GTU will be searched.

direction - GTUDirectionality; whether we are looking in the the center line direction or against the center line direction.

relativePosition - RelativePosition.TYPE; the relative position of the GTU we are looking for.

when - Time; the time for which to evaluate the positions.

Returns:

LaneBasedGTU; the first GTU after a position on this lane in the given direction, or null if no GTU could be found.

Throws:

GTUException - when there is a problem with the position of the GTUs on the lane.

nextLanes

public final Map<Lane,GTUDirectionality> nextLanes(GTUType gtuType)

NextLanes returns the successor lane(s) in the design line direction, if any exist.
The next lane(s) are cached, as it is too expensive to make the calculation every time. There are several possibilities: (1) Returning an empty set when there is no successor lane in the design direction or there is no longitudinal transfer possible to a successor lane in the design direction. (2) Returning a set with just one lane if the lateral position of the successor lane matches the lateral position of this lane (based on an overlap of the lateral positions of the two joining lanes of more than a certain percentage). (3) Multiple lanes in case the Node where the underlying Link for this Lane has multiple "outgoing" Links, and there are multiple lanes that match the lateral position of this lane.
The next lanes can differ per GTU type. For instance, a lane where cars and buses are allowed can have a next lane where only buses are allowed, forcing the cars to leave that lane.

Parameters:

gtuType - the GTU type for which we return the next lanes, use null to return all next lanes and their design direction

Returns:

set of Lanes following this lane for the given GTU type.

prevLanes

public final Map<Lane,GTUDirectionality> prevLanes(GTUType gtuType)

PrevLanes returns the predecessor lane(s) relative to the design line direction, if any exist.
The previous lane(s) are cached, as it is too expensive to make the calculation every time. There are several possibilities: (1) Returning an empty set when there is no predecessor lane relative to the design direction or there is no longitudinal transfer possible to a predecessor lane relative to the design direction. (2) Returning a set with just one lane if the lateral position of the predecessor lane matches the lateral position of this lane (based on an overlap of the lateral positions of the two joining lanes of more than a certain percentage). (3) Multiple lanes in case the Node where the underlying Link for this Lane has multiple "incoming" Links, and there are multiple lanes that match the lateral position of this lane.
The previous lanes can differ per GTU type. For instance, a lane where cars and buses are allowed can be preceded by a lane where only buses are allowed.

Parameters:

gtuType - the GTU type for which we return the next lanes, use null to return all prev lanes and their design direction

Returns:

set of Lanes following this lane for the given GTU type.

downstreamLanes

public final Map<Lane,GTUDirectionality> downstreamLanes(GTUDirectionality direction,
                                                         GTUType gtuType)

Returns the lanes that could be followed in a given direction and for the given GTU type.

Parameters:

direction - GTUDirectionality; gtu direction

gtuType - GTUType; gtu type

Returns:

lanes that can be followed in a given direction and for the given GTU type

upstreamLanes

public final Map<Lane,GTUDirectionality> upstreamLanes(GTUDirectionality direction,
                                                       GTUType gtuType)

Returns the lanes that could precede in a given direction and for the given GTU type.

Parameters:

direction - GTUDirectionality; gtu direction

gtuType - GTUType; gtu type

Returns:

lanes that can be followed in a given direction and for the given GTU type

accessibleAdjacentLanesPhysical

public final Set<Lane> accessibleAdjacentLanesPhysical(LateralDirectionality lateralDirection,
                                                       GTUType gtuType,
                                                       GTUDirectionality drivingDirection)

Determine the set of lanes to the left or to the right of this lane, which are accessible from this lane, or an empty set if no lane could be found. The method ignores all legal restrictions such as allowable directions and stripes.
A lane is called adjacent to another lane if the lateral edges are not more than a delta distance apart. This means that a lane that overlaps with another lane is not returned as an adjacent lane.
Note: LEFT and RIGHT are seen from the direction of the GTU, in its forward driving direction.

Parameters:

lateralDirection - LateralDirectionality; LEFT or RIGHT.

gtuType - GTUType; the type of GTU for which to return the adjacent lanes.

drivingDirection - GTUDirectionality; the driving direction of the GTU on <code>this</code> Lane

Returns:

the set of lanes that are accessible, or null if there is no lane that is accessible with a matching driving direction.

accessibleAdjacentLanesLegal

public final Set<Lane> accessibleAdjacentLanesLegal(LateralDirectionality lateralDirection,
                                                    GTUType gtuType,
                                                    GTUDirectionality drivingDirection)

Determine the set of lanes to the left or to the right of this lane, which are accessible from this lane, or an empty set if no lane could be found. The method takes the LongitidinalDirectionality of the lane into account. In other words, if we drive in the DIR_PLUS direction and look for a lane on the LEFT, and there is a lane but the Directionality of that lane is not DIR_PLUS or DIR_BOTH, it will not be included.
A lane is called adjacent to another lane if the lateral edges are not more than a delta distance apart. This means that a lane that overlaps with another lane is not returned as an adjacent lane.
Note: LEFT and RIGHT are seen from the direction of the GTU, in its forward driving direction.

Parameters:

lateralDirection - LateralDirectionality; LEFT or RIGHT.

gtuType - GTUType; the type of GTU for which to return the adjacent lanes.

drivingDirection - GTUDirectionality; the driving direction of the GTU on <code>this</code> Lane

Returns:

the set of lanes that are accessible, or null if there is no lane that is accessible with a matching driving direction.

getSpeedLimit

public final Speed getSpeedLimit(GTUType gtuType)
                          throws NetworkException

Get the speed limit of this lane, which can differ per GTU type. E.g., cars might be allowed to drive 120 km/h and trucks 90 km/h.

Parameters:

gtuType - GTUType; the GTU type to provide the speed limit for

Returns:

the speedLimit.

Throws:

NetworkException - on network inconsistency

getLowestSpeedLimit

public final Speed getLowestSpeedLimit()
                                throws NetworkException

Get the lowest speed limit of this lane.

Returns:

the lowets speedLimit.

Throws:

NetworkException - on network inconsistency

getHighestSpeedLimit

public final Speed getHighestSpeedLimit()
                                 throws NetworkException

Get the highest speed limit of this lane.

Returns:

the highest speedLimit.

Throws:

NetworkException - on network inconsistency

setSpeedLimit

public final void setSpeedLimit(GTUType gtuType,
                                Speed speedLimit)

Set the speed limit of this lane, which can differ per GTU type. Cars might be allowed to drive 120 km/h and trucks 90 km/h. If the speed limit is the same for all GTU types, GTUType.ALL will be used. This means that the settings can be used additive, or subtractive.
In additive use, do not set the speed limit for GTUType.ALL. Now, one by one, the allowed maximum speeds for each of the GTU Types have be added. Do this when there are few GTU types or the speed limits per TU type are very different.
In subtractive use, set the speed limit for GTUType.ALL to the most common one. Override the speed limit for certain GTUTypes to a different value. An example is a lane on a highway where all vehicles, except truck (CAR, BUS, MOTORCYCLE, etc.), can drive 120 km/h, but trucks are allowed only 90 km/h. In that case, set the speed limit for GTUType.ALL to 120 km/h, and for TRUCK to 90 km/h.

Parameters:

gtuType - GTUType; the GTU type to provide the speed limit for

speedLimit - Speed; the speed limit for this gtu type

removeSpeedLimit

public final void removeSpeedLimit(GTUType gtuType)

Remove the set speed limit for a GTUType. If the speed limit for GTUType.ALL will be removed, there will not be a 'default' speed limit anymore. If the speed limit for a certain GTUType is removed, its speed limit will default to the speed limit of GTUType.ALL.
Note: if no speed limit is known for a GTUType, getSpeedLimit will throw a NetworkException when the speed limit is retrieved for that GTUType.

Parameters:

gtuType - GTUType; the GTU type to provide the speed limit for

getLaneType

public final LaneType getLaneType()

Returns:

laneType.

getGtuList

public final ImmutableList<LaneBasedGTU> getGtuList()

Returns:

gtuList.

getGtuList

public final List<LaneBasedGTU> getGtuList(Time time)

Returns the list of GTU's at the specified time.

Parameters:

time - Time; time

Returns:

list of GTU's at the specified times

numberOfGtus

public final int numberOfGtus()

Returns the number of GTU's.

Returns:

int; number of GTU's.

numberOfGtus

public final int numberOfGtus(Time time)

Returns the number of GTU's at specified time.

Parameters:

time - Time; time

Returns:

int; number of GTU's.

indexOfGtu

public final int indexOfGtu(LaneBasedGTU gtu)

Returns the index of the given GTU, or -1 if not present.

Parameters:

gtu - LaneBasedGTU; gtu to get the index of

Returns:

int; index of the given GTU, or -1 if not present

indexOfGtu

public final int indexOfGtu(LaneBasedGTU gtu,
                            Time time)

Returns the index of the given GTU, or -1 if not present, at specified time.

Parameters:

gtu - LaneBasedGTU; gtu to get the index of

time - Time; time

Returns:

int; index of the given GTU, or -1 if not present

getGtu

public final LaneBasedGTU getGtu(int index)

Returns the index'th GTU.

Parameters:

index - int; index of the GTU

Returns:

LaneBasedGTU; the index'th GTU

getGtu

public final LaneBasedGTU getGtu(int index,
                                 Time time)

Returns the index'th GTU at specified time.

Parameters:

index - int; index of the GTU

time - Time; time

Returns:

LaneBasedGTU; the index'th GTU

getZ

protected double getZ()

Retrieve the Z offset (used to determine what covers what when drawing).

Specified by:

getZ in class CrossSectionElement

Returns:

double; the Z-offset for drawing (what's on top, what's underneath).

getOvertakingConditions

public final OvertakingConditions getOvertakingConditions()

Returns:

overtakingConditions

toString

public final String toString()

Overrides:

toString in class CrossSectionElement

hashCode

public int hashCode()

Overrides:

hashCode in class CrossSectionElement

equals

public boolean equals(Object obj)

Overrides:

equals in class CrossSectionElement

clone

public Lane clone(CrossSectionLink newParentLink,
                  SimulatorInterface.TimeDoubleUnit newSimulator)
           throws NetworkException

Clone the CrossSectionElement for e.g., copying a network.

Specified by:

clone in class CrossSectionElement

Parameters:

newParentLink - CrossSectionLink; the new link to which the clone belongs

newSimulator - SimulatorInterface.TimeDoubleUnit; the new simulator for this network

Returns:

a clone of this object

Throws:

NetworkException - in case the cloning fails