Package org.opentrafficsim.road.gtu.lane

Class AbstractLaneBasedGTU

java.lang.Object
org.djutils.event.EventProducer
org.opentrafficsim.core.gtu.AbstractGTU
org.opentrafficsim.road.gtu.lane.AbstractLaneBasedGTU
All Implemented Interfaces:
java.io.Serializable, Locatable, EventProducerInterface, Identifiable, Drawable, GTU, LaneBasedGTU
public abstract class AbstractLaneBasedGTU
extends AbstractGTU
implements LaneBasedGTU
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-2020 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
BSD-style license. See OpenTrafficSim License.

Version:
$Revision: 1408 $, $LastChangedDate: 2015-09-24 15:17:25 +0200 (Thu, 24 Sep 2015) $, by $Author: pknoppers $, initial version Oct 22, 2014
Author:
Alexander Verbraeck, Peter Knoppers
See Also:
Serialized Form

  • Field Details

    • initialLocationThresholdDifference

      public static Length initialLocationThresholdDifference
      The threshold distance for differences between initial locations of the GTU on different lanes.

    • CACHING

      public static boolean CACHING
      Caching on or off.

    • CACHED_POSITION

      public static int CACHED_POSITION
      cached position count.

    • NON_CACHED_POSITION

      public static int NON_CACHED_POSITION
      cached position count.

  • Constructor Details

    • AbstractLaneBasedGTU

      public AbstractLaneBasedGTU​(java.lang.String id, GTUType gtuType, OTSSimulatorInterface simulator, OTSRoadNetwork network) throws GTUException
      Construct a Lane Based GTU.
      Parameters:
      id - String; the id of the GTU
      gtuType - GTUType; the type of GTU, e.g. TruckType, CarType, BusType
      simulator - OTSSimulatorInterface; to initialize the move method and to get the current time
      network - OTSRoadNetwork; 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, java.util.Set<DirectedLanePosition> initialLongitudinalPositions, Speed initialSpeed) throws NetworkException, SimRuntimeException, GTUException, OTSGeometryException
      Parameters:
      strategicalPlanner - LaneBasedStrategicalPlanner; the strategical planner (e.g., route determination) to use
      initialLongitudinalPositions - Set<DirectedLanePosition>; the initial positions of the car on one or more lanes with their directions
      initialSpeed - Speed; the initial speed of the car on the lane
      Throws:
      NetworkException - when the GTU cannot be placed on the given lane
      SimRuntimeException - when the move method cannot be scheduled
      GTUException - when initial values are not correct
      OTSGeometryException - when the initial path is wrong

    • setParent

      public void setParent​(GTU gtu) throws GTUException
      All lanes the GTU is on will be left.
      Specified by:
      setParent in interface GTU
      Overrides:
      setParent in class AbstractGTU
      Throws:
      GTUException

    • reinit

      public void reinit​(java.util.Set<DirectedLanePosition> initialLongitudinalPositions) throws NetworkException, SimRuntimeException, GTUException, OTSGeometryException
      Reinitializes the GTU on the network using the existing strategical planner and zero speed.
      Parameters:
      initialLongitudinalPositions - Set<DirectedLanePosition>; initial position
      Throws:
      NetworkException - when the GTU cannot be placed on the given lane
      SimRuntimeException - when the move method cannot be scheduled
      GTUException - when initial values are not correct
      OTSGeometryException - when the initial path is wrong

    • isSafeToChange

      public final boolean isSafeToChange() throws GTUException
      Hack method. TODO remove and solve better
      Returns:
      safe to change
      Throws:
      GTUException - on error

    • enterLane

      public void enterLane​(Lane lane, Length position, GTUDirectionality gtuDirection) throws GTUException
      insert GTU at a certain position. This can happen at setup (first initialization), and after a lane change of the GTU. The relative position that will be registered is the referencePosition (dx, dy, dz) = (0, 0, 0). Front and rear positions are relative towards this position.
      Parameters:
      lane - Lane; the lane to add to the list of lanes on which the GTU is registered.
      gtuDirection - GTUDirectionality; the direction of the GTU on the lane (which can be bidirectional). If the GTU has a positive speed, it is moving in this direction.
      position - Length; the position on the lane.
      Throws:
      GTUException - when positioning the GTU on the lane causes a problem

    • addGtuToLane

      protected void addGtuToLane​(Lane lane, Length position) throws GTUException
      Part of 'enterLane' which registers the GTU with the lane so the lane can report its GTUs.
      Parameters:
      lane - Lane; lane
      position - Length; position
      Throws:
      GTUException - on exception

    • leaveLane

      public void leaveLane​(Lane lane) throws GTUException
      Unregister the GTU from a lane.
      Parameters:
      lane - Lane; the lane to remove from the list of lanes on which the GTU is registered.
      Throws:
      GTUException - when leaveLane should not be called

    • leaveLane

      public void leaveLane​(Lane lane, boolean beingDestroyed) throws GTUException
      Leave a lane but do not complain about having no lanes left when beingDestroyed is true.
      Parameters:
      lane - Lane; the lane to leave
      beingDestroyed - boolean; if true, no complaints about having no lanes left
      Throws:
      GTUException - in case leaveLane should not be called

    • changeLaneInstantaneously

      public void changeLaneInstantaneously​(LateralDirectionality laneChangeDirection) throws GTUException
      Change lanes instantaneously.
      Specified by:
      changeLaneInstantaneously in interface LaneBasedGTU
      Parameters:
      laneChangeDirection - LateralDirectionality; the direction to change to
      Throws:
      GTUException - in case lane change fails

    • initLaneChange

      public void initLaneChange​(LateralDirectionality laneChangeDirection) throws GTUException
      Register on lanes in target lane.
      Specified by:
      initLaneChange in interface LaneBasedGTU
      Parameters:
      laneChangeDirection - LateralDirectionality; direction of lane change
      Throws:
      GTUException - exception

    • finalizeLaneChange

      protected void finalizeLaneChange​(LateralDirectionality laneChangeDirection)
      Performs the finalization of a lane change by leaving the from lanes.
      Parameters:
      laneChangeDirection - LateralDirectionality; direction of lane change

    • setFinalizeLaneChangeEvent

      public void setFinalizeLaneChangeEvent​(SimEventInterface<SimTimeDoubleUnit> event)
      Sets event to finalize lane change.
      Specified by:
      setFinalizeLaneChangeEvent in interface LaneBasedGTU
      Parameters:
      event - SimEventInterface<SimTimeDoubleUnit>; event

    • getDirection

      public final GTUDirectionality getDirection​(Lane lane) throws GTUException
      Return the directionality of a lane on which the GTU is registered for its current operational plan.
      Specified by:
      getDirection in interface LaneBasedGTU
      Parameters:
      lane - Lane; the lane for which we want to know the direction
      Returns:
      GTUDirectionality; the direction on the given lane
      Throws:
      GTUException - in case the GTU is not registered on the Lane

    • move

      protected boolean move​(DirectedPoint fromLocation) throws SimRuntimeException, GTUException, OperationalPlanException, NetworkException, ParameterException
      Overrides:
      move in class AbstractGTU
      Throws:
      SimRuntimeException
      GTUException
      OperationalPlanException
      NetworkException
      ParameterException

    • positions

      public final java.util.Map<Lane,​Length> positions​(RelativePosition relativePosition) throws GTUException
      Return the longitudinal positions of a point relative to this GTU, relative to the center line of the Lanes in which the vehicle is registered.
      Note: If a GTU is registered in multiple parallel lanes, the lateralLaneChangeModel is used to determine the center line of the vehicle at this point in time. Otherwise, the average of the center positions of the lines will be taken.
      Specified by:
      positions in interface LaneBasedGTU
      Parameters:
      relativePosition - RelativePosition; the position on the vehicle relative to the reference point.
      Returns:
      the lanes and the position on the lanes where the GTU is currently registered, for the given position of the GTU.
      Throws:
      GTUException - when the vehicle is not on one of the lanes on which it is registered.

    • positions

      public final java.util.Map<Lane,​Length> positions​(RelativePosition relativePosition, Time when) throws GTUException
      Return the longitudinal positions of a point relative to this GTU, relative to the center line of the Lanes in which the vehicle is registered.
      Specified by:
      positions in interface LaneBasedGTU
      Parameters:
      relativePosition - RelativePosition; the position on the vehicle relative to the reference point.
      when - Time; the future time for which to calculate the positions.
      Returns:
      the lanes and the position on the lanes where the GTU will be registered at the time, for the given position of the GTU.
      Throws:
      GTUException - when the vehicle is not on one of the lanes on which it is registered.

    • position

      public final Length position​(Lane lane, RelativePosition relativePosition) throws GTUException
      Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane at the current simulation time.
      Specified by:
      position in interface LaneBasedGTU
      Parameters:
      lane - Lane; the position on this lane will be returned.
      relativePosition - RelativePosition; the position on the vehicle relative to the reference point.
      Returns:
      DoubleScalarAbs<LengthUnit>; the position, relative to the center line of the Lane.
      Throws:
      GTUException - when the vehicle is not on the given lane.

    • translatedPosition

      public Length translatedPosition​(Lane projectionLane, RelativePosition relativePosition, Time when) throws GTUException
      Return the longitudinal position that the indicated relative position of this GTU would have if it were to change to another Lane with a / the current CrossSectionLink. This point may be before the begin or after the end of the link of the projection lane of the GTU. This preserves the length of the GTU.
      Parameters:
      projectionLane - Lane; the lane onto which the position of this GTU must be projected
      relativePosition - RelativePosition; the point on this GTU that must be projected
      when - Time; the time for which to project the position of this GTU
      Returns:
      Length; the position of this GTU in the projectionLane
      Throws:
      GTUException - when projectionLane it not in any of the CrossSectionLink that the GTU is on

    • projectedPosition

      public Length projectedPosition​(Lane projectionLane, RelativePosition relativePosition, Time when) throws GTUException
      Return the longitudinal position on the projection lane that has the same fractional position on one of the current lanes of the indicated relative position. This preserves the fractional positions of all relative positions of the GTU.
      Parameters:
      projectionLane - Lane; the lane onto which the position of this GTU must be projected
      relativePosition - RelativePosition; the point on this GTU that must be projected
      when - Time; the time for which to project the position of this GTU
      Returns:
      Length; the position of this GTU in the projectionLane
      Throws:
      GTUException - when projectionLane it not in any of the CrossSectionLink that the GTU is on

    • position

      public Length position​(Lane lane, RelativePosition relativePosition, Time when) throws GTUException
      Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane.
      Specified by:
      position in interface LaneBasedGTU
      Parameters:
      lane - Lane; the position on this lane will be returned.
      relativePosition - RelativePosition; the position on the vehicle relative to the reference point.
      when - Time; the future time for which to calculate the positions.
      Returns:
      DoubleScalarAbs<LengthUnit>; the position, relative to the center line of the Lane.
      Throws:
      GTUException - when the vehicle is not on the given lane.

    • getReferencePosition

      public DirectedLanePosition getReferencePosition() throws GTUException
      Return the current Lane, position and directionality of the GTU.
      Specified by:
      getReferencePosition in interface LaneBasedGTU
      Returns:
      DirectedLanePosition; the current Lane, position and directionality of the GTU
      Throws:
      GTUException - in case the reference position of the GTU cannot be found on the lanes in its current path

    • scheduleEnterLeaveTriggers

      protected void scheduleEnterLeaveTriggers() throws NetworkException, SimRuntimeException, GTUException
      Schedule the triggers for this GTU that are going to happen until the next evaluation time. Also schedule the registration and deregistration of lanes when the vehicle enters or leaves them, at the exact right time.
      Note: when the GTU makes a lane change, the vehicle will be registered for both lanes during the entire maneuver.
      Throws:
      NetworkException - on network inconsistency
      SimRuntimeException - should never happen
      GTUException - when a branch is reached where the GTU does not know where to go next

    • fractionalPositions

      public final java.util.Map<Lane,​java.lang.Double> fractionalPositions​(RelativePosition relativePosition) throws GTUException
      Return the longitudinal positions of a point relative to this GTU, relative to the center line of the Lanes in which the vehicle is registered, as fractions of the length of the lane. This is important when we want to see if two vehicles are next to each other and we compare an 'inner' and 'outer' curve.
      Specified by:
      fractionalPositions in interface LaneBasedGTU
      Parameters:
      relativePosition - RelativePosition; the position on the vehicle relative to the reference point.
      Returns:
      the lanes and the position on the lanes where the GTU is currently registered, for the given position of the GTU.
      Throws:
      GTUException - when the vehicle is not on one of the lanes on which it is registered.

    • fractionalPositions

      public final java.util.Map<Lane,​java.lang.Double> fractionalPositions​(RelativePosition relativePosition, Time when) throws GTUException
      Return the longitudinal positions of a point relative to this GTU, relative to the center line of the Lanes in which the vehicle is registered, as fractions of the length of the lane. This is important when we want to see if two vehicles are next to each other and we compare an 'inner' and 'outer' curve.
      Specified by:
      fractionalPositions in interface LaneBasedGTU
      Parameters:
      relativePosition - RelativePosition; the position on the vehicle relative to the reference point.
      when - Time; the future time for which to calculate the positions.
      Returns:
      the lanes and the position on the lanes where the GTU will be registered at the time, for the given position of the GTU.
      Throws:
      GTUException - when the vehicle is not on one of the lanes on which it is registered.

    • fractionalPosition

      public final double fractionalPosition​(Lane lane, RelativePosition relativePosition, Time when) throws GTUException
      Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane, as a fraction of the length of the lane. This is important when we want to see if two vehicles are next to each other and we compare an 'inner' and 'outer' curve.
      Specified by:
      fractionalPosition in interface LaneBasedGTU
      Parameters:
      lane - Lane; the position on this lane will be returned.
      relativePosition - RelativePosition; the position on the vehicle relative to the reference point.
      when - Time; the future time for which to calculate the positions.
      Returns:
      the fractional relative position on the lane at the given time.
      Throws:
      GTUException - when the vehicle is not on the given lane.

    • fractionalPosition

      public final double fractionalPosition​(Lane lane, RelativePosition relativePosition) throws GTUException
      Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane, as a fraction of the length of the lane. This is important when we want to see if two vehicles are next to each other and we compare an 'inner' and 'outer' curve.
      Specified by:
      fractionalPosition in interface LaneBasedGTU
      Parameters:
      lane - Lane; the position on this lane will be returned.
      relativePosition - RelativePosition; the position on the vehicle relative to the reference point.
      Returns:
      the fractional relative position on the lane at the given time.
      Throws:
      GTUException - when the vehicle is not on the given lane.

    • addTrigger

      public final void addTrigger​(Lane lane, SimEventInterface<SimTimeDoubleUnit> event)
      Add an event to the list of lane triggers scheduled for this GTU.
      Specified by:
      addTrigger in interface LaneBasedGTU
      Parameters:
      lane - Lane; the lane on which the event occurs
      event - SimEventInterface<SimTimeDoubleUnit>; SimeEvent<SimTimeDoubleUnit> the event

    • setVehicleModel

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

    • getVehicleModel

      public VehicleModel getVehicleModel()
      Returns the vehicle model.
      Specified by:
      getVehicleModel in interface LaneBasedGTU
      Returns:
      VehicleModel; vehicle model

    • destroy

      public void destroy()
      Specified by:
      destroy in interface GTU
      Overrides:
      destroy in class AbstractGTU

    • getBounds

      public final javax.media.j3d.Bounds getBounds()
      Specified by:
      getBounds in interface Locatable

    • getStrategicalPlanner

      public final LaneBasedStrategicalPlanner getStrategicalPlanner()
      Specified by:
      getStrategicalPlanner in interface GTU
      Specified by:
      getStrategicalPlanner in interface LaneBasedGTU
      Overrides:
      getStrategicalPlanner in class AbstractGTU

    • getStrategicalPlanner

      public final LaneBasedStrategicalPlanner getStrategicalPlanner​(Time time)
      Specified by:
      getStrategicalPlanner in interface GTU
      Specified by:
      getStrategicalPlanner in interface LaneBasedGTU
      Overrides:
      getStrategicalPlanner in class AbstractGTU

    • getNetwork

      public RoadNetwork getNetwork()
      Specified by:
      getNetwork in interface LaneBasedGTU
      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.
      Specified by:
      getDesiredSpeed in interface LaneBasedGTU
      Returns:
      Speed; 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.
      Specified by:
      getCarFollowingAcceleration in interface LaneBasedGTU
      Returns:
      Acceleration; current car-following acceleration

    • getTurnIndicatorStatus

      public final TurnIndicatorStatus getTurnIndicatorStatus()
      Specified by:
      getTurnIndicatorStatus in interface LaneBasedGTU
      Returns:
      the status of the turn indicator

    • getTurnIndicatorStatus

      public final TurnIndicatorStatus getTurnIndicatorStatus​(Time time)
      Specified by:
      getTurnIndicatorStatus in interface LaneBasedGTU
      Parameters:
      time - Time; time to obtain the turn indicator status at
      Returns:
      the status of the turn indicator at the given time

    • setTurnIndicatorStatus

      public final void setTurnIndicatorStatus​(TurnIndicatorStatus turnIndicatorStatus)
      Set the status of the turn indicator.
      Specified by:
      setTurnIndicatorStatus in interface LaneBasedGTU
      Parameters:
      turnIndicatorStatus - TurnIndicatorStatus; the new status of the turn indicator.

    • toString

      public java.lang.String toString()
      Overrides:
      toString in class java.lang.Object