Package org.opentrafficsim.road.gtu.lane

Class LaneBasedGtu

java.lang.Object
org.djutils.event.LocalEventProducer
org.opentrafficsim.core.gtu.Gtu
org.opentrafficsim.road.gtu.lane.LaneBasedGtu
All Implemented Interfaces:
nl.tudelft.simulation.dsol.animation.Locatable, Identifiable, EventProducer, OtsShape, HierarchicallyTyped<GtuType,Gtu>, LocatedObject, LaneBasedObject
public class LaneBasedGtu extends Gtu implements LaneBasedObject
This class contains most of the code that is needed to run a lane based GTU.
The starting point of a LaneBasedTU is that it can be in multiple lanes at the same time. This can be due to a lane change (lateral), or due to crossing a link (front of the GTU is on another Lane than rear of the GTU). If a Lane is shorter than the length of the GTU (e.g. when we do node expansion on a crossing, this is very well possible), a GTU could occupy dozens of Lanes at the same time.

When calculating a headway, the GTU has to look in successive lanes. When Lanes (or underlying CrossSectionLinks) diverge, the headway algorithms have to look at multiple Lanes and return the minimum headway in each of the Lanes. When the Lanes (or underlying CrossSectionLinks) converge, "parallel" traffic is not taken into account in the headway calculation. Instead, gap acceptance algorithms or their equivalent should guide the merging behavior.

To decide its movement, an AbstractLaneBasedGtu applies its car following algorithm and lane change algorithm to set the acceleration and any lane change operation to perform. It then schedules the triggers that will add it to subsequent lanes and remove it from current lanes as needed during the time step that is has committed to. Finally, it re-schedules its next movement evaluation with the simulator.

Copyright (c) 2013-2024 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, Wouter Schakel

  • Field Details

    • LANEBASED_MOVE_EVENT

      public static final EventType LANEBASED_MOVE_EVENT
      The lane-based event type for pub/sub indicating a move.
      Payload: [String gtuId, PositionVector currentPosition, Direction currentDirection, Speed speed, Acceleration acceleration, TurnIndicatorStatus turnIndicatorStatus, Length odometer, String linkId, String laneId, Length positionOnLane]

    • LANEBASED_DESTROY_EVENT

      public static final EventType LANEBASED_DESTROY_EVENT
      The lane-based event type for pub/sub indicating destruction of the GTU.
      Payload: [String gtuId, PositionVector finalPosition, Direction finalDirection, Length finalOdometer, String linkId, String laneId, Length positionOnLane]

    • LANE_ENTER_EVENT

      public static final EventType LANE_ENTER_EVENT
      The event type for pub/sub indicating that the GTU entered a lane in either the lateral or longitudinal direction.
      Payload: [String gtuId, String link id, String lane id]

    • LANE_EXIT_EVENT

      public static final EventType LANE_EXIT_EVENT
      The event type for pub/sub indicating that the GTU exited a lane in either the lateral or longitudinal direction.
      Payload: [String gtuId, String link id, String lane id]

    • LANE_CHANGE_EVENT

      public static final EventType LANE_CHANGE_EVENT
      The event type for pub/sub indicating that the GTU changed lane, laterally only.
      Payload: [String gtuId, LateralDirectionality direction, String linkId, String fromLaneId, Length position]

  • Constructor Details

    • LaneBasedGtu

      public LaneBasedGtu(String id, GtuType gtuType, Length length, Length width, Speed maximumSpeed, Length front, RoadNetwork network) throws GtuException
      Construct a Lane Based GTU.
      Parameters:
      id - the id of the GTU
      gtuType - the type of GTU, e.g. TruckType, CarType, BusType
      length - the maximum length of the GTU (parallel with driving direction)
      width - the maximum width of the GTU (perpendicular to driving direction)
      maximumSpeed - the maximum speed of the GTU (in the driving direction)
      front - front distance relative to the reference position
      network - the network that the GTU is initially registered in
      Throws:
      GtuException - when initial values are not correct

  • Method Details

    • init

      public void init(LaneBasedStrategicalPlanner strategicalPlanner, DirectedPoint2d initialLocation, Speed initialSpeed) throws NetworkException, nl.tudelft.simulation.dsol.SimRuntimeException, GtuException
      Initializes the GTU.
      Parameters:
      strategicalPlanner - the strategical planner (e.g., route determination) to use
      initialLocation - initial location
      initialSpeed - the initial speed of the car on the lane
      Throws:
      NetworkException - when the GTU cannot be placed on the given lane
      nl.tudelft.simulation.dsol.SimRuntimeException - when the move method cannot be scheduled
      GtuException - when initial values are not correct

    • setParent

      public void setParent(Gtu gtu) throws GtuException
      The lane the GTU is on will be left.
      Overrides:
      setParent in class Gtu
      Throws:
      GtuException

    • exitLane

      protected void exitLane()
      Removes the registration between this GTU and the lane.

    • enterLane

      protected void enterLane(Lane lane, double fraction)
      Enters a new lane, and removes the GTU from the previous lane.
      Parameters:
      lane - lane
      fraction - fractional position

    • isRoaming

      public boolean isRoaming()
      Returns whether the GTU is roaming (i.e. not on a lane). In this case all methods on lane and position should not be called as they will return null.
      Returns:
      whether the GTU is roaming

    • isRoaming

      public boolean isRoaming(Duration time)
      Returns whether the GTU is roaming (i.e. not on a lane). In this case all methods on lane and position should not be called as they will return null.
      Parameters:
      time - simulation time to get the lane for
      Returns:
      whether the GTU is roaming

    • getPositionOrRoaming

      public LanePosition getPositionOrRoaming()
      Returns the position when the GTU is on a lane, or the roaming position otherwise.
      Returns:
      position when the GTU is on a lane, or the roaming position otherwise

    • getLane

      public Lane getLane()
      Description copied from interface: LaneBasedObject
      Returns the lane.
      Specified by:
      getLane in interface LaneBasedObject
      Returns:
      lane

    • getLane

      public Lane getLane(Duration time)
      Returns the lane at the given time. This may be in the future during the plan, in which case it is a prospective lane.
      Parameters:
      time - simulation time to get the lane for
      Returns:
      lane at given time

    • getPosition

      public LanePosition getPosition()
      Returns the lane and reference position on the lane of the GTU.
      Returns:
      lane position at time

    • getPosition

      public LanePosition getPosition(Duration time)
      Returns the lane and reference position on the lane of the GTU.
      Parameters:
      time - simulation time to get the position for
      Returns:
      lane position at time

    • getPosition

      public LanePosition getPosition(RelativePosition relativePosition)
      Returns the lane and relative position on the lane of the GTU. The relative position is calculated by shifting the position of the reference by dx of the relative position.
      Parameters:
      relativePosition - relative position
      Returns:
      lane position

    • getPosition

      public LanePosition getPosition(RelativePosition relativePosition, Duration time)
      Returns the lane and relative position on the lane of the GTU. The relative position is calculated by shifting the position of the reference by dx of the relative position.
      Parameters:
      relativePosition - relative position
      time - simulation time to get the position for
      Returns:
      lane position at time

    • getPosition

      public Length getPosition(Lane lane)
      Returns the projected position of the GTU on the given lane, which should be on the same link.
      Parameters:
      lane - lane
      Returns:
      projected position of the GTU on the given lane
      Throws:
      IllegalStateException - when the GTU is not on a lane
      IllegalArgumentException - when the lane is not in the link the GTU is on

    • getPosition

      public Length getPosition(Lane lane, Duration time)
      Returns the projected position of the GTU on the given lane, which should be on the same link.
      Parameters:
      lane - lane
      time - simulation time
      Returns:
      projected position of the GTU on the given lane
      Throws:
      IllegalStateException - when the GTU is not on a lane
      IllegalArgumentException - when the lane is not in the link the GTU is on

    • getPosition

      public Length getPosition(Lane lane, RelativePosition relativePosition)
      Returns the projected position of the GTU on the given lane, which should be on the same link. The relative position is calculated by shifting the position of the reference by dx of the relative position.
      Parameters:
      lane - lane
      relativePosition - relative position
      Returns:
      projected position of the GTU on the given lane
      Throws:
      IllegalStateException - when the GTU is not on a lane
      IllegalArgumentException - when the lane is not in the link the GTU is on

    • getLongitudinalPosition

      public Length getLongitudinalPosition()
      Description copied from interface: LaneBasedObject
      Returns the longitudinal position.
      Specified by:
      getLongitudinalPosition in interface LaneBasedObject
      Returns:
      position (between 0.0 and the length of the lane)

    • getPosition

      public Length getPosition(Lane lane, RelativePosition relativePosition, Duration time)
      Returns the projected position of the GTU on the given lane, which should be on the same link. The relative position is calculated by shifting the position of the reference by dx of the relative position.
      Parameters:
      lane - lane
      relativePosition - relative position
      time - simulation time
      Returns:
      projected position of the GTU on the given lane
      Throws:
      IllegalStateException - when the GTU is not on a lane
      IllegalArgumentException - when the lane is not in the link the GTU is on

    • getRoamingPosition

      public LanePosition getRoamingPosition()
      Returns the nearest lane position on the route / network. It is not strictly guaranteed that the position is closest, as this method will only search on links where either of the nodes is the closest node.
      Returns:
      nearest lane position on the route / network

    • getRoamingPosition

      protected LanePosition getRoamingPosition(Point2d location)
      Returns the nearest lane position on the route / network. It is not strictly guaranteed that the position is closest, as this method will only search on links where either of the nodes is the closest node.
      Parameters:
      location - location to find the nearest lane position for
      Returns:
      nearest lane position on the route / network

    • getDeviation

      public Length getDeviation()
      Deviation from lane center. Positive values are left, negative values are right.
      Returns:
      deviation from lane center line, positive values are left, negative values are right

    • getDeviation

      public Length getDeviation(Duration time)
      Deviation from lane center at time. Positive values are left, negative values are right.
      Parameters:
      time - simulation time
      Returns:
      deviation from lane center line, positive values are left, negative values are right

    • getDeviation

      protected Length getDeviation(Lane lane, Point2d location)
      Returns the deviation from the center line of the given lane, using extension if the GTU is not on the lane. Positive values are left, negative values are right.
      Parameters:
      lane - lane
      location - location
      Returns:
      deviation from lane center line, positive values are left, negative values are right

    • changeLaneInstantaneously

      public void changeLaneInstantaneously(LateralDirectionality laneChangeDirection)
      Change lanes instantaneously.
      Parameters:
      laneChangeDirection - the direction to change to

    • move

      protected boolean move(DirectedPoint2d fromLocation) throws nl.tudelft.simulation.dsol.SimRuntimeException, GtuException, NetworkException, ParameterException
      Overrides:
      move in class Gtu
      Throws:
      nl.tudelft.simulation.dsol.SimRuntimeException
      GtuException
      NetworkException
      ParameterException

    • cancelAllEvents

      protected void cancelAllEvents()
      Cancels all future events.

    • scheduleLaneEvents

      protected void scheduleLaneEvents()
      Schedules when a lane is entered (and a previous one is left). Also schedules start of roaming (GTU not having a lane), or ends roaming if the GTU is on a lane.

    • getTimeOfLateralCrossing

      protected Duration getTimeOfLateralCrossing(Duration fromTime, Duration toTime, boolean roam)
      Estimates when the path crosses a lateral lane boundary assuming the GTU is within the boundary. This is estimated through linear interpolation between the start and end deviation values of a line segment of the path. The line segment is found through a binary search.
      Parameters:
      fromTime - first time to consider on the lane
      toTime - last time to consider on the lane
      roam - when true the full width of the GTU is considered, when false only the reference position
      Returns:
      when the path crosses a lateral lane boundary

    • endRoaming

      protected void endRoaming(LanePosition roamingPosition)
      Ends roaming if the roaming position is sufficiently close to enter the network.
      Parameters:
      roamingPosition - roaming position

    • findDetectorTriggers

      protected void findDetectorTriggers(boolean schedule)
      This method applies a detector finding algorithm that guarantees that detectors at the same location, triggered for different relative positions, are all always triggered in combination. As detectors might be triggered by the front, detectors beyond the current plan path may need to be triggered in the current plan duration. To achieve this, all detectors are found between the path start position + dx, up to the path end position + dx, where dx is the distance the front is before the reference point. Start and end position and dx are applied along the lane center lines. In case of a lane change dx is also applied on both lanes, meaning that all detectors overlapping the vehicle on the from lane are found, but at the target lane only detectors downstream of the front are found.

      This method stores all found detectors as detector triggers. This includes for each detector the odometer value of the reference point at which the detector should be triggered. The odometer value is adjusted for the relative position that should trigger the detector, along the lane center lines.

      Finally, this method schedules trigger events for all stored detector triggers when the reference point reaches the relevant odometer value in the current plan. This may include detector triggers that were stored in a previous time step as the front reached the detector, but no event was scheduled in a previous time step as the relevant relative position of the detector, e.g. the rear, did not reach the detector.

      Alternatively when schedule = false this method finds all detector triggers downstream of the current front location during the current plan using the same search algorithm, and removes them from the stored detector triggers. No events will be scheduled (nor removed by this method). Removing detector triggers is relevant when a plan is cancelled. Any downstream detectors may be found again and rescheduled depending on a new plan by a new move.
      Parameters:
      schedule - true adds downstream triggers and schedules them, false removes downstream triggers

    • triggerDetector

      protected void triggerDetector(LaneDetector detector)
      Trigger detector and remove it from detectors that need to be triggered.
      Parameters:
      detector - detector

    • laneLateralOvershoot

      protected Length laneLateralOvershoot(Duration time)
      Returns the lateral overshoot at give time. This is the lateral distance by which the reference point exceeds either the left or right edge of the lane. Negative values indicate the reference point is still on the lane.
      Parameters:
      time - simulation time
      Returns:
      lateral overshoot

    • getNextLaneForRoute

      public Optional<Lane> getNextLaneForRoute(Lane lane)
      Returns the next lane for a given lane to stay on the route.
      Parameters:
      lane - the lane for which we want to know the next Lane
      Returns:
      next lane, empty if none

    • setVehicleModel

      public void setVehicleModel(VehicleModel vehicleModel)
      Sets a vehicle model.
      Parameters:
      vehicleModel - vehicle model

    • getVehicleModel

      public VehicleModel getVehicleModel()
      Returns the vehicle model.
      Returns:
      vehicle model

    • getStrategicalPlanner

      public LaneBasedStrategicalPlanner getStrategicalPlanner()
      Overrides:
      getStrategicalPlanner in class Gtu

    • getStrategicalPlanner

      public LaneBasedStrategicalPlanner getStrategicalPlanner(Duration time)
      Overrides:
      getStrategicalPlanner in class Gtu

    • getNetwork

      public RoadNetwork getNetwork()
      Returns the network.
      Returns:
      the road network to which the LaneBasedGtu belongs

    • getDesiredSpeed

      public Speed getDesiredSpeed()
      This method returns the current desired speed of the GTU. This value is required often, so implementations can cache it.
      Returns:
      current desired speed

    • getCarFollowingAcceleration

      public Acceleration getCarFollowingAcceleration()
      This method returns the current car-following acceleration of the GTU. This value is required often, so implementations can cache it.
      Returns:
      current car-following acceleration

    • getTurnIndicatorStatus

      public TurnIndicatorStatus getTurnIndicatorStatus()
      Returns the turn indicator status.
      Returns:
      the status of the turn indicator

    • getTurnIndicatorStatus

      public TurnIndicatorStatus getTurnIndicatorStatus(Duration time)
      Returns the turn indicator status at time.
      Parameters:
      time - simulation time to obtain the turn indicator status at
      Returns:
      the status of the turn indicator at the given time

    • setTurnIndicatorStatus

      public void setTurnIndicatorStatus(TurnIndicatorStatus turnIndicatorStatus)
      Set the status of the turn indicator.
      Parameters:
      turnIndicatorStatus - the new status of the turn indicator.

    • getHeight

      public Length getHeight()
      Specified by:
      getHeight in interface LocatedObject

    • getFullId

      public String getFullId()
      Specified by:
      getFullId in interface LocatedObject

    • setBookkeeping

      public void setBookkeeping(LaneBookkeeping bookkeeping)
      Sets how lane bookkeeping at lane changes is done.
      Parameters:
      bookkeeping - how lane bookkeeping at lane changes is done

    • getBookkeeping

      public LaneBookkeeping getBookkeeping()
      Returns how lane bookkeeping at lane changes is done.
      Returns:
      how lane bookkeeping at lane changes is done

    • getTacticalPlanner

      public LaneBasedTacticalPlanner getTacticalPlanner()
      Overrides:
      getTacticalPlanner in class Gtu

    • getTacticalPlanner

      public LaneBasedTacticalPlanner getTacticalPlanner(Duration time)
      Overrides:
      getTacticalPlanner in class Gtu

    • setNoLaneChangeDistance

      public void setNoLaneChangeDistance(Length distance)
      Set distance over which the GTU should not change lane after being created.
      Parameters:
      distance - distance over which the GTU should not change lane after being created

    • laneChangeAllowed

      public boolean laneChangeAllowed()
      Returns whether a lane change is allowed.
      Returns:
      whether a lane change is allowed

    • setLaneChangeDirection

      public void setLaneChangeDirection(LateralDirectionality direction)
      Set lane change direction. This should only be set by a controller of the GTU, e.g. the tactical planner.
      Parameters:
      direction - lane change direction

    • getLaneChangeDirection

      public LateralDirectionality getLaneChangeDirection()
      Returns the lane change direction.
      Returns:
      lane change direction

    • getLaneChangeDirection

      public LateralDirectionality getLaneChangeDirection(Duration time)
      Returns the lane change direction at the given time.
      Parameters:
      time - simulation time
      Returns:
      lane change direction at the given time

    • isBrakingLightsOn

      public boolean isBrakingLightsOn()
      Returns whether the braking lights are on.
      Returns:
      whether the braking lights are on

    • isBrakingLightsOn

      public boolean isBrakingLightsOn(Duration time)
      Returns whether the braking lights are on.
      Parameters:
      time - simulation time
      Returns:
      whether the braking lights are on

    • getProjectedLength

      public Length getProjectedLength(Lane lane)
      Get projected length on the lane.
      Parameters:
      lane - lane to project the vehicle on
      Returns:
      the length on the lane, which is different from the actual length during deviative tactical plans

    • stop

      public void stop()
      Stops the GTU using a permanent stand-still operational plan.

    • destroy

      public void destroy()
      Overrides:
      destroy in class Gtu

    • toString

      public String toString()
      Overrides:
      toString in class Object