Package org.opentrafficsim.road.network

Class Lane

java.lang.Object
org.djutils.event.LocalEventProducer
org.opentrafficsim.road.network.CrossSectionElement
org.opentrafficsim.road.network.Lane
All Implemented Interfaces:
nl.tudelft.simulation.dsol.animation.Locatable, Identifiable, EventProducer, OtsShape, HierarchicallyTyped<LaneType,Lane>
Direct Known Subclasses:
Shoulder
public class Lane extends CrossSectionElement implements HierarchicallyTyped<LaneType,Lane>
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 detectors that can be triggered by passing GTUs. The Lane class also contains methods to determine to trigger the detectors 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). The GTU is only booked with its reference point on the lane, and is -- unless during a lane change -- only booked on one lane at a time.

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

Author:
Alexander Verbraeck, Peter Knoppers

  • Field Details

    • 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, int count_after_addition, String laneId, String linkId}

    • 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, String laneId, String linkId}

    • DETECTOR_ADD_EVENT

      public static final EventType DETECTOR_ADD_EVENT
      The timed event type for pub/sub indicating the addition of a Detector to the lane.
      Payload: Object[] {String detectorId, Detector detector}

    • DETECTOR_REMOVE_EVENT

      public static final EventType DETECTOR_REMOVE_EVENT
      The timed event type for pub/sub indicating the removal of a Detector from the lane.
      Payload: Object[] {String detectorId, Detector detector}

    • 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 org.djunits.value.vdouble.scalar.Length MARGIN
      Lateral alignment margin for longitudinally connected Lanes.

  • Constructor Details

    • Lane

      public Lane(CrossSectionLink link, String id, CrossSectionGeometry geometry, LaneType laneType, LaneSpeedLimits laneSpeedLimits)
      Constructor specifying geometry.
      Parameters:
      link - link
      id - the id of this lane within the link; should be unique within the link
      geometry - geometry
      laneType - lane type
      laneSpeedLimits - speed limits

  • Method Details

    • addDetector

      public void addDetector(LaneDetector detector) throws NetworkException
      Insert a detector at the right place in the detector list of this Lane.
      Parameters:
      detector - the detector to add
      Throws:
      NetworkException - when the position of the detector is beyond (or before) the range of this Lane

    • removeDetector

      public void removeDetector(LaneDetector detector) throws NetworkException
      Remove a detector from the detector list of this Lane.
      Parameters:
      detector - the detector to remove.
      Throws:
      NetworkException - when the detector was not found on this Lane

    • getDetectors

      public List<LaneDetector> getDetectors(org.djunits.value.vdouble.scalar.Length minimumPosition, org.djunits.value.vdouble.scalar.Length maximumPosition, GtuType gtuType)
      Retrieve the list of Detectors of this Lane in the specified distance range for the given GtuType. The resulting list is a defensive copy.
      Parameters:
      minimumPosition - the minimum distance on the Lane (inclusive)
      maximumPosition - the maximum distance on the Lane (inclusive)
      gtuType - the GTU type to provide the detectors for
      Returns:
      list of the detectors in the specified range. This is a defensive copy.

    • getDetectors

      public List<LaneDetector> getDetectors(GtuType gtuType)
      Retrieve the list of Detectors of this Lane that are triggered by the given GtuType. The resulting list is a defensive copy.
      Parameters:
      gtuType - the GTU type to provide the detectors for
      Returns:
      list of the detectors, in ascending order for the location on the Lane

    • getDetectors

      public List<LaneDetector> getDetectors()
      Retrieve the list of all Detectors of this Lane. The resulting list is a defensive copy.
      Returns:
      list of the detectors, in ascending order for the location on the Lane

    • getDetectorMap

      public SortedMap<Double,List<LaneDetector>> getDetectorMap(GtuType gtuType)
      Retrieve the list of Detectors of this Lane for the given GtuType. The resulting Map is a defensive copy.
      Parameters:
      gtuType - the GTU type to provide the detectors for
      Returns:
      all detectors on this lane for the given GtuType as a map per distance

    • addLaneBasedObject

      public 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 - the laneBasedObject to add
      Throws:
      NetworkException - when the position of the laneBasedObject is beyond (or before) the range of this Lane

    • removeLaneBasedObject

      public void removeLaneBasedObject(LaneBasedObject laneBasedObject) throws NetworkException
      Remove a laneBasedObject from the laneBasedObject list of this Lane.
      Parameters:
      laneBasedObject - the laneBasedObject to remove.
      Throws:
      NetworkException - when the laneBasedObject was not found on this Lane

    • getLaneBasedObjects

      public List<LaneBasedObject> getLaneBasedObjects(org.djunits.value.vdouble.scalar.Length minimumPosition, org.djunits.value.vdouble.scalar.Length maximumPosition)
      Retrieve the list of LaneBasedObjects of this Lane in the specified distance range. The resulting list is a defensive copy.
      Parameters:
      minimumPosition - the minimum distance on the Lane (inclusive)
      maximumPosition - the maximum distance on the Lane (inclusive)
      Returns:
      list of the laneBasedObject in the specified range. This is a defensive copy.

    • getLaneBasedObjects

      public List<LaneBasedObject> getLaneBasedObjects()
      Retrieve the list of all LaneBasedObjects of this Lane. The resulting list is a defensive copy.
      Returns:
      list of the laneBasedObjects, in ascending order for the location on the Lane

    • getLaneBasedObjectMap

      public SortedMap<Double,List<LaneBasedObject>> getLaneBasedObjectMap()
      Retrieve the list of LaneBasedObjects of this Lane. The resulting Map is a defensive copy.
      Returns:
      all laneBasedObjects on this lane

    • position

      public org.djunits.value.vdouble.scalar.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 - fraction relative to the lane length.
      Returns:
      the longitudinal length corresponding to the fraction.

    • positionSI

      public 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:
      length corresponding to the fraction, in SI units.

    • fraction

      public double fraction(org.djunits.value.vdouble.scalar.Length 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 relative to the lane length.

    • fractionSI

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

    • addGtu

      public int addGtu(LaneBasedGtu gtu, double fractionalPosition) throws GtuException
      Add a LaneBasedGtu to the list of this Lane.
      Parameters:
      gtu - the GTU to add
      fractionalPosition - the fractional position that the newly added GTU will have on this Lane
      Returns:
      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 GTU is already registered on this Lane

    • addGtu

      public int addGtu(LaneBasedGtu gtu, org.djunits.value.vdouble.scalar.Length longitudinalPosition) throws GtuException
      Add a LaneBasedGtu to the list of this Lane.
      Parameters:
      gtu - the GTU to add
      longitudinalPosition - the longitudinal position that the newly added GTU will have on this Lane
      Returns:
      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 void removeGtu(LaneBasedGtu gtu, boolean removeFromParentLink, org.djunits.value.vdouble.scalar.Length position)
      Remove a GTU from the GTU list of this lane.
      Parameters:
      gtu - the GTU to remove.
      removeFromParentLink - when the GTU leaves the last lane of the parentLink of this Lane
      position - last position of the GTU

    • getLastGtu

      public Optional<LaneBasedGtu> getLastGtu() throws GtuException
      Get the last GTU on the lane, relative to a driving direction on this lane.
      Returns:
      the last GTU on this lane in the given direction, empty if no GTU could be found.
      Throws:
      GtuException - when there is a problem with the position of the GTUs on the lane.

    • getFirstGtu

      public Optional<LaneBasedGtu> getFirstGtu() throws GtuException
      Get the first GTU on the lane, relative to a driving direction on this lane.
      Returns:
      the first GTU on this lane in the given direction, empty if no GTU could be found.
      Throws:
      GtuException - when there is a problem with the position of the GTUs on the lane.

    • getGtuAhead

      public Optional<LaneBasedGtu> getGtuAhead(org.djunits.value.vdouble.scalar.Length position, RelativePosition.Type relativePosition, org.djunits.value.vdouble.scalar.Duration 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.
      Parameters:
      position - the position before which the relative position of a GTU will be searched.
      relativePosition - RelativePosition.TYPE; the relative position we want to compare against
      when - the simulation time for which to evaluate the positions.
      Returns:
      the first GTU before a position on this lane in the given direction, empty if no GTU could be found.

    • getGtuBehind

      public Optional<LaneBasedGtu> getGtuBehind(org.djunits.value.vdouble.scalar.Length position, RelativePosition.Type relativePosition, org.djunits.value.vdouble.scalar.Duration 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.
      Parameters:
      position - the position before which the relative position of a GTU will be searched.
      relativePosition - RelativePosition.TYPE; 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 in the given direction, empty if no GTU could be found.

    • getObjectAhead

      public List<LaneBasedObject> getObjectAhead(org.djunits.value.vdouble.scalar.Length position)
      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 - the position after which the relative position of an object will be searched.
      Returns:
      the first object(s) before a position on this lane in the given direction, empty if no object could be found.

    • getObjectBehind

      public List<LaneBasedObject> getObjectBehind(org.djunits.value.vdouble.scalar.Length position)
      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 - the position after which the relative position of an object will be searched.
      Returns:
      the first object(s) after a position on this lane in the given direction, empty if no object could be found.

    • nextLanes

      public Set<Lane> 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.

    • forceNextLanes

      public void forceNextLanes(Set<Lane> lanes)
      Forces the next lanes to be as specified. For specific GTU types, a subset of these lanes is taken.
      Parameters:
      lanes - lanes to set as next lanes.

    • prevLanes

      public Set<Lane> 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.

    • forcePrevLanes

      public void forcePrevLanes(Set<Lane> lanes)
      Forces the previous lanes to be as specified. For specific GTU types, a subset of these lanes is taken.
      Parameters:
      lanes - lanes to set as previous lanes.

    • accessibleAdjacentLanesPhysical

      public Set<Lane> accessibleAdjacentLanesPhysical(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 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 - LEFT or RIGHT.
      gtuType - the type of GTU for which to return the adjacent lanes.
      Returns:
      the set of lanes that are accessible, empty if there is no lane that is accessible with a matching driving direction.

    • accessibleAdjacentLanesLegal

      public Set<Lane> accessibleAdjacentLanesLegal(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 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 - LEFT or RIGHT.
      gtuType - the type of GTU for which to return the adjacent lanes.
      Returns:
      the set of lanes that are accessible, empty if there is no lane that is accessible with a matching driving direction.

    • getLeft

      public Optional<Lane> getLeft(GtuType gtuType)
      Returns the left lane for given GTU type, regardless of legality.
      Parameters:
      gtuType - GTU type
      Returns:
      left lane for given GTU type, empty if none

    • getRight

      public Optional<Lane> getRight(GtuType gtuType)
      Returns the right lane for given GTU type, regardless of legality.
      Parameters:
      gtuType - GTU type
      Returns:
      right lane for given GTU type, empty if none

    • getAdjacentLane

      public Optional<Lane> getAdjacentLane(LateralDirectionality laneChangeDirection, GtuType gtuType)
      Returns one adjacent lane, regardless of legality.
      Parameters:
      laneChangeDirection - lane change direction
      gtuType - GTU type
      Returns:
      adjacent lane, empty if none

    • getSpeedLimits

      public SpeedLimits getSpeedLimits(GtuType gtuType)
      Get the speed limits of this lane at the current time-of-day, which can differ per GTU type. E.g., a vehicle type speed limit may apply to trucks.
      Parameters:
      gtuType - the GTU type to provide the speed limits for
      Returns:
      speed limits

    • getSpeedLimits

      public SpeedLimits getSpeedLimits(GtuType gtuType, org.djunits.value.vdouble.scalar.Duration timeOfDay)
      Get the speed limits of this lane, which can differ per GTU type. E.g., a vehicle type speed limit may apply to trucks.
      Parameters:
      gtuType - the GTU type to provide the speed limits for
      timeOfDay - time-of-day
      Returns:
      speed limits

    • getSpeedLimit

      public Optional<SpeedLimit> getSpeedLimit()
      Returns the speed limit at the current time-of-day.
      Returns:
      speed limit, empty if no speed limit given

    • getSpeedLimit

      public Optional<SpeedLimit> getSpeedLimit(org.djunits.value.vdouble.scalar.Duration timeOfDay)
      Returns the speed limit.
      Parameters:
      timeOfDay - time-of-day
      Returns:
      speed limit, empty if no speed limit given

    • getType

      public LaneType getType()
      Specified by:
      getType in interface HierarchicallyTyped<LaneType,Lane>

    • getGtuList

      public ImmutableList<LaneBasedGtu> getGtuList()
      Returns GTU list.
      Returns:
      gtuList.

    • getGtuList

      public List<LaneBasedGtu> getGtuList(org.djunits.value.vdouble.scalar.Duration time)
      Returns the list of GTU's at the specified time.
      Parameters:
      time - simulation time
      Returns:
      list of GTU's at the specified times

    • numberOfGtus

      public int numberOfGtus()
      Returns the number of GTU's.
      Returns:
      number of GTU's.

    • numberOfGtus

      public int numberOfGtus(org.djunits.value.vdouble.scalar.Duration time)
      Returns the number of GTU's at specified time.
      Parameters:
      time - simulation time
      Returns:
      number of GTU's.

    • indexOfGtu

      public int indexOfGtu(LaneBasedGtu gtu)
      Returns the index of the given GTU, or -1 if not present.
      Parameters:
      gtu - gtu to get the index of
      Returns:
      index of the given GTU, or -1 if not present

    • getGtu

      public LaneBasedGtu getGtu(int index)
      Returns the index'th GTU.
      Parameters:
      index - index of the GTU
      Returns:
      the index'th GTU

    • getGtu

      public LaneBasedGtu getGtu(int index, org.djunits.value.vdouble.scalar.Duration time)
      Returns the index'th GTU at specified time.
      Parameters:
      index - index of the GTU
      time - simulation time
      Returns:
      the index'th GTU

    • coveredDistance

      public org.djunits.value.vdouble.scalar.Length coveredDistance(double fraction)
      Returns the covered distance driven to the given fractional position.
      Parameters:
      fraction - fractional position
      Returns:
      covered distance driven to the given fractional position

    • remainingDistance

      public org.djunits.value.vdouble.scalar.Length remainingDistance(double fraction)
      Returns the remaining distance to be driven from the given fractional position.
      Parameters:
      fraction - fractional position
      Returns:
      remaining distance to be driven from the given fractional position

    • fractionAtCoveredDistance

      @Deprecated public double fractionAtCoveredDistance(org.djunits.value.vdouble.scalar.Length distance)
      Deprecated.
      Returns the fraction along the design line for having covered the given distance.
      Parameters:
      distance - covered distance
      Returns:
      fraction along the design line for having covered the given distance

    • toString

      public 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