org.opentrafficsim.core.network.lane

Class Lane

java.lang.Object

org.opentrafficsim.core.network.lane.CrossSectionElement

org.opentrafficsim.core.network.lane.Lane

All Implemented Interfaces:

nl.tudelft.simulation.dsol.animation.LocatableInterface

Direct Known Subclasses:

NoTrafficLane, SinkLane, SourceLane

public class Lane
extends CrossSectionElement

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

Version:

Aug 19, 2014

Author:

Alexander Verbraeck, Peter Knoppers, Guus Tamminga

Constructor Summary

Constructors

Constructor and Description
Lane(CrossSectionLink<?,?> parentLink, DoubleScalar.Rel<LengthUnit> lateralOffsetAtStart, DoubleScalar.Rel<LengthUnit> lateralOffsetAtEnd, DoubleScalar.Rel<LengthUnit> beginWidth, DoubleScalar.Rel<LengthUnit> endWidth, LaneType<?> laneType, LongitudinalDirectionality directionality, DoubleScalar.Abs<FrequencyUnit> capacity)

Method Summary

Methods

Modifier and Type	Method and Description
Set<Lane>	accessibleAdjacentLanes(LateralDirectionality lateralDirection, GTUType<?> gtuType) 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.
void	addAccessibleAdjacentLane(Lane adjacentLane, LateralDirectionality direction) Indicate that a Lane is adjacent to this Lane.
int	addGTU(LaneBasedGTU<?> gtu, double fractionalPosition) Add a LaneBasedGTU<?> to the list of this Lane.
int	addGTU(LaneBasedGTU<?> gtu, DoubleScalar.Rel<LengthUnit> longitudinalPosition) Add a LaneBasedGTU<?> to the list of this Lane.
void	addSampler(LaneBasedGTUSampler sampler) Register a LaneBasedGTUSampler on this Lane.
void	addSensor(Sensor sensor) Insert the sensor at the right place in the sensor list of this lane.
Lane	bestAccessibleAdjacentLane(LateralDirectionality lateralDirection, DoubleScalar.Rel<LengthUnit> longitudinalPosition, GTUType<?> gtuType) Determine whether there is a lane to the left or to the right of this lane, which is accessible from this lane, or null if no lane could be found.
double	fraction(DoubleScalar.Rel<LengthUnit> 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.
DoubleScalar.Abs<FrequencyUnit>	getCapacity()
LongitudinalDirectionality	getDirectionality()
LaneBasedGTU<?>	getGtuAfter(DoubleScalar.Rel<LengthUnit> position, RelativePosition.TYPE relativePosition, DoubleScalar.Abs<TimeUnit> when)
LaneBasedGTU<?>	getGtuBefore(DoubleScalar.Rel<LengthUnit> position, RelativePosition.TYPE relativePosition, DoubleScalar.Abs<TimeUnit> when)
List<LaneBasedGTU<?>>	getGtuList()
LaneType<?>	getLaneType()
protected SortedMap<Double,List<Sensor>>	getSensors()
List<Sensor>	getSensors(DoubleScalar.Rel<LengthUnit> minimumPosition, DoubleScalar.Rel<LengthUnit> maximumPosition) Retrieve the list of Sensors of this Lane in the specified distance range.
protected double	getZ()
Set<Lane>	nextLanes() The next lane(s) are cached, as it is too expensive to make the calculation every time.
DoubleScalar.Rel<LengthUnit>	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).
Set<Lane>	prevLanes() The previous lane(s) are cached, as it is too expensive to make the calculation every time.
void	removeAccessibleAdjacentLane(Lane adjacentLane, LateralDirectionality direction) Indicate that a Lane is no longer adjacent to this Lane (may be useful for lanes that are sometimes closed, e.g.
void	removeGTU(LaneBasedGTU<?> gtu) Remove a GTU from the GTU list of this lane.
void	removeSampler(LaneBasedGTUSampler sampler) Unregister a LaneBasedGTUSampler from this Lane.
void	removeSensor(Sensor sensor) Remove a sensor from the sensor list of this lane.
void	sample(AbstractLaneBasedGTU<?> gtu) Add the movement of a GTU to all graphs that sample this Lane.
void	scheduleTriggers(LaneBasedGTU<?> gtu, double referenceStartSI, double referenceMoveSI) Trigger the sensors for a certain time step; from now until the nextEvaluationTime of the GTU.
void	setCapacity(DoubleScalar.Abs<FrequencyUnit> capacity)
String	toString()

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

getBounds, getCenterLine, getContour, getLateralBoundaryPosition, getLateralBoundaryPosition, getLateralCenterPosition, getLateralCenterPosition, getLength, getLocation, getParentLink, getWidth, getWidth, printCoordinate, printCoordinates, printCoordinates, printCoordinates, printCoordinates

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Lane

public Lane(CrossSectionLink<?,?> parentLink,
    DoubleScalar.Rel<LengthUnit> lateralOffsetAtStart,
    DoubleScalar.Rel<LengthUnit> lateralOffsetAtEnd,
    DoubleScalar.Rel<LengthUnit> beginWidth,
    DoubleScalar.Rel<LengthUnit> endWidth,
    LaneType<?> laneType,
    LongitudinalDirectionality directionality,
    DoubleScalar.Abs<FrequencyUnit> capacity)
     throws NetworkException

Parameters:

parentLink - Cross Section Link to which the element belongs.

lateralOffsetAtStart - DoubleScalar.Rel<LengthUnit>; 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 - DoubleScalar.Rel<LengthUnit>; 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 - DoubleScalar.Rel<LengthUnit>; start width, positioned symmetrically around the design line

endWidth - DoubleScalar.Rel<LengthUnit>; end width, positioned symmetrically around the design line

laneType - type of lane to deduce compatibility with GTU types

directionality - in direction of geometry, reverse, or both

capacity - Lane capacity in vehicles per time unit. This is a mutable property (e.g., blockage)

Throws:

NetworkException - when creation of the geometry fails

Method Detail

addAccessibleAdjacentLane

public final void addAccessibleAdjacentLane(Lane adjacentLane,
                             LateralDirectionality direction)

Indicate that a Lane is adjacent to this Lane.

Parameters:

adjacentLane - Lane; the adjacent Lane

direction - LateralDirectionality; the direction in which the Lane is adjacent to this Lane

removeAccessibleAdjacentLane

public final void removeAccessibleAdjacentLane(Lane adjacentLane,
                                LateralDirectionality direction)
                                        throws NetworkException

Indicate that a Lane is no longer adjacent to this Lane (may be useful for lanes that are sometimes closed, e.g. tidal flow lanes).

Parameters:

adjacentLane - Lane; the adjacent Lane that must be unregistered

direction - LateralDirectionality; the direction in which the Lane was adjacent to this Lane

Throws:

NetworkException - when the adjacentLane was not registered as adjacent in the indicated direction

addSensor

public final void addSensor(Sensor sensor)
                     throws NetworkException

Insert the sensor at the right place in the sensor list of this lane.

Parameters:

sensor - 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(Sensor sensor)
                        throws NetworkException

Remove a sensor from the sensor list of this lane.

Parameters:

sensor - the sensor to remove.

Throws:

NetworkException - when the sensor was not found on this Lane

getSensors

public final List<Sensor> getSensors(DoubleScalar.Rel<LengthUnit> minimumPosition,
                      DoubleScalar.Rel<LengthUnit> maximumPosition)

Retrieve the list of Sensors of this Lane in the specified distance range.

Parameters:

minimumPosition - DoubleScalar.Rel<LengthUnit>; the minimum distance on the Lane

maximumPosition - DoubleScalar.Rel<LengthUnit>; the maximum distance on the Lane

Returns:

List<Sensor>; list of the sensor in the specified range

getSensors

protected final SortedMap<Double,List<Sensor>> getSensors()

Returns:

sensors.

scheduleTriggers

public final void scheduleTriggers(LaneBasedGTU<?> gtu,
                    double referenceStartSI,
                    double referenceMoveSI)
                            throws RemoteException,
                                   NetworkException,
                                   nl.tudelft.simulation.dsol.SimRuntimeException

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

Parameters:

gtu - the LaneBasedGTU for which to trigger the sensors.

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

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

Throws:

RemoteException - when simulation time cannot be retrieved.

NetworkException - when GTU not on this lane.

nl.tudelft.simulation.dsol.SimRuntimeException - when method cannot be scheduled.

position

public final DoubleScalar.Rel<LengthUnit> 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 - fraction relative to the lane length.

Returns:

relative 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 - fraction relative to the lane length.

Returns:

relative length corresponding to the fraction, in SI units.

fraction

public final double fraction(DoubleScalar.Rel<LengthUnit> position)

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

Parameters:

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

Returns:

fraction 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 - relative length on the lane in SI units (may be less than zero or larger than the lane length).

Returns:

fraction fraction relative to the lane length.

addGTU

public final int addGTU(LaneBasedGTU<?> gtu,
         double fractionalPosition)
                 throws RemoteException,
                        NetworkException

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:

RemoteException - on communication failure

NetworkException - 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,
         DoubleScalar.Rel<LengthUnit> longitudinalPosition)
                 throws RemoteException,
                        NetworkException

Add a LaneBasedGTU<?> to the list of this Lane.

Parameters:

gtu - LaneBasedGTU<?>; the GTU to add

longitudinalPosition - DoubleScalar.Rel<LengthUnit>; 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:

RemoteException - on communication failure

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

removeGTU

public final void removeGTU(LaneBasedGTU<?> gtu)

Remove a GTU from the GTU list of this lane.

Parameters:

gtu - the GTU to remove.

getGtuAfter

public final LaneBasedGTU<?> getGtuAfter(DoubleScalar.Rel<LengthUnit> position,
                          RelativePosition.TYPE relativePosition,
                          DoubleScalar.Abs<TimeUnit> when)
                                  throws NetworkException

Parameters:

position - the front position after which the relative position of a GTU will be searched.

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

when - the time for which to evaluate the positions.

Returns:

the first GTU after a position on this lane, or null if no GTU could be found.

Throws:

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

getGtuBefore

public final LaneBasedGTU<?> getGtuBefore(DoubleScalar.Rel<LengthUnit> position,
                           RelativePosition.TYPE relativePosition,
                           DoubleScalar.Abs<TimeUnit> when)
                                   throws NetworkException

Parameters:

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

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

when - the time for which to evaluate the positions.

Returns:

the first GTU before a position on this lane, or null if no GTU could be found.

Throws:

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

nextLanes

public final Set<Lane> nextLanes()

The next lane(s) are cached, as it is too expensive to make the calculation every time. There are several possibilities: returning an empty set when the lane stops and there is no longitudinal transfer method to a next lane. Returning a set with just one lane if the lateral position of the next 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). 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.

Returns:

set of Lanes following this lane.

prevLanes

public final Set<Lane> prevLanes()

The previous lane(s) are cached, as it is too expensive to make the calculation every time. There are several possibilities: returning an empty set when the lane starts and there is no longitudinal transfer method from a previous lane. Returning a set with just one lane if the lateral position of the previous 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). 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.

Returns:

set of Lanes preceding this lane.

accessibleAdjacentLanes

public final Set<Lane> accessibleAdjacentLanes(LateralDirectionality lateralDirection,
                                GTUType<?> gtuType)

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 FORWARD and look for a lane on the LEFT, and there is a lane but the Directionality of that lane is not FORWARD or 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.
The algorithm also looks for RoadMarkerAcross elements between the lanes to determine the lateral permeability for a GTU. A RoadMarkerAcross is seen as being between two lanes if its center line is not more than delta distance from the relevant lateral edges of the two adjacent lanes.
Note: LEFT is seen as a positive lateral direction, RIGHT as a negative lateral direction.

Parameters:

lateralDirection - LEFT or RIGHT.

gtuType - the type of GTU for which this an adjacent lane.

Returns:

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

bestAccessibleAdjacentLane

public final Lane bestAccessibleAdjacentLane(LateralDirectionality lateralDirection,
                              DoubleScalar.Rel<LengthUnit> longitudinalPosition,
                              GTUType<?> gtuType)

Determine whether there is a lane to the left or to the right of this lane, which is accessible from this lane, or null if no lane could be found. The method takes the LongitidinalDirectionality of the lane into account. In other words, if we drive FORWARD and look for a lane on the LEFT, and there is a lane but the Directionality of that lane is not FORWARD or BOTH, null will be returned.
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.
The algorithm also looks for RoadMarkerAcross elements between the lanes to determine the lateral permeability for a GTU. A RoadMarkerAcross is seen as being between two lanes if its center line is not more than delta distance from the relevant lateral edges of the two adjacent lanes.
When there are multiple lanes that are adjacent, which could e.g. be the case if an overlapping tram lane and a car lane are adjacent to the current lane, the widest lane that best matches the GTU accessibility of the provided GTUType is returned.
Note: LEFT is seen as a positive lateral direction, RIGHT as a negative lateral direction.

Parameters:

lateralDirection - LEFT or RIGHT.

longitudinalPosition - DoubleScalar.Rel<LengthUnit>; the position of the GTU along this Lane

gtuType - the type of GTU for which this an adjacent lane.

Returns:

the lane if it is accessible, or null if there is no lane, it is not accessible, or the driving direction does not match.

addSampler

public final void addSampler(LaneBasedGTUSampler sampler)

Register a LaneBasedGTUSampler on this Lane.

Parameters:

sampler - LaneBasedGTUSampler; the sampler to register

removeSampler

public final void removeSampler(LaneBasedGTUSampler sampler)

Unregister a LaneBasedGTUSampler from this Lane.

Parameters:

sampler - LaneBasedGTUSampler; the sampler to unregister

sample

public final void sample(AbstractLaneBasedGTU<?> gtu)
                  throws RemoteException,
                         NetworkException

Add the movement of a GTU to all graphs that sample this Lane.

Parameters:

gtu - AbstractLaneBasedGTU<?>; the GTU to sample

Throws:

NetworkException - on network inconsistency

RemoteException - on communications failure

getCapacity

public final DoubleScalar.Abs<FrequencyUnit> getCapacity()

Returns:

capacity.

setCapacity

public final void setCapacity(DoubleScalar.Abs<FrequencyUnit> capacity)

Parameters:

capacity - set capacity.

getLaneType

public final LaneType<?> getLaneType()

Returns:

laneType.

getDirectionality

public final LongitudinalDirectionality getDirectionality()

Returns:

directionality.

getGtuList

public final List<LaneBasedGTU<?>> getGtuList()

Returns:

gtuList.

getZ

protected double getZ()

Specified by:

getZ in class CrossSectionElement

Returns:

the z-value to determine "stacking" for animation.

toString

public final String toString()

Overrides:

toString in class CrossSectionElement