org.opentrafficsim.road.gtu.lane

Interface LaneBasedGTU

All Superinterfaces:

org.opentrafficsim.core.gtu.GTU, nl.tudelft.simulation.dsol.animation.LocatableInterface, Serializable

All Known Implementing Classes:

AbstractLaneBasedGTU, AbstractLaneBasedIndividualGTU, AbstractLaneBasedTemplateGTU, AbstractTrafficLight, LaneBasedIndividualCar, LaneBasedTemplateCar, LaneBlock, LaneBlockOnOff

public interface LaneBasedGTU
extends org.opentrafficsim.core.gtu.GTU

This interface defines a lane based GTU.

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

Version:

$Revision: 1401 $, $LastChangedDate: 2015-09-14 01:33:02 +0200 (Mon, 14 Sep 2015) $, by $Author: averbraeck $, initial version Oct 22, 2014

Author:

Alexander Verbraeck, Peter Knoppers

Method Summary

Modifier and Type	Method and Description
Lane	bestAccessibleAdjacentLane(Lane currentLane, org.opentrafficsim.core.network.LateralDirectionality lateralDirection, org.djunits.value.vdouble.scalar.Length.Rel longitudinalPosition) 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.
org.djunits.value.vdouble.scalar.Time.Rel	deltaTimeForDistance(org.djunits.value.vdouble.scalar.Length.Rel distance) Determine the time since last evaluation when this GTU has covered the specified distance from the position of the last evaluation time.
void	enterLane(Lane lane, org.djunits.value.vdouble.scalar.Length.Rel position) insert GTU at a certain position.
double	fractionalPosition(Lane lane, org.opentrafficsim.core.gtu.RelativePosition relativePosition) 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.
double	fractionalPosition(Lane lane, org.opentrafficsim.core.gtu.RelativePosition relativePosition, org.djunits.value.vdouble.scalar.Time.Abs when) 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.
Map<Lane,Double>	fractionalPositions(org.opentrafficsim.core.gtu.RelativePosition relativePosition) 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.
Map<Lane,Double>	fractionalPositions(org.opentrafficsim.core.gtu.RelativePosition relativePosition, org.djunits.value.vdouble.scalar.Time.Abs when) 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.
org.djunits.value.vdouble.scalar.Acceleration	getAcceleration()
org.djunits.value.vdouble.scalar.Acceleration	getAcceleration(org.djunits.value.vdouble.scalar.Time.Abs when)
GTUFollowingModel	getGTUFollowingModel() Retrieve the GTU following model of this LaneBasedGTU.
LaneChangeUrgeGTUColorer.LaneChangeDistanceAndDirection	getLaneChangeDistanceAndDirection() Return the distance available for the next needed lane change and the lateral direction of that lane change.
org.djunits.value.vdouble.scalar.Time.Abs	getLastEvaluationTime()
org.djunits.value.vdouble.scalar.Speed	getLateralVelocity()
org.djunits.value.vdouble.scalar.Speed	getLongitudinalVelocity() v(t) = v0 + (t - t0) * a.
org.djunits.value.vdouble.scalar.Speed	getLongitudinalVelocity(org.djunits.value.vdouble.scalar.Time.Abs when) Return the speed of this GTU at the specified time.
org.djunits.value.vdouble.scalar.Time.Abs	getNextEvaluationTime()
HeadwayGTU	headway(Lane lane, org.djunits.value.vdouble.scalar.Length.Rel maxDistance) Determine by what distance the front of this GTU is behind the rear an other GTU, or the rear of this GTU is ahead of the front of an other GTU.
HeadwayGTU	headway(org.djunits.value.vdouble.scalar.Length.Rel maxDistance) Determine which GTU in front of this GTU, or behind this GTU.
void	leaveLane(Lane lane) Unregister the GTU from a lane.
Set<LaneBasedGTU>	parallel(Lane lane, org.djunits.value.vdouble.scalar.Time.Abs when) Determine which GTUs are parallel with us on another lane, based on fractional positions.
Set<LaneBasedGTU>	parallel(org.opentrafficsim.core.network.LateralDirectionality lateralDirection, org.djunits.value.vdouble.scalar.Time.Abs when) Determine which GTUs are parallel with us in a certain lateral direction, based on fractional positions.
org.djunits.value.vdouble.scalar.Length.Rel	position(Lane lane, org.opentrafficsim.core.gtu.RelativePosition relativePosition) Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane at the current simulation time.
org.djunits.value.vdouble.scalar.Length.Rel	position(Lane lane, org.opentrafficsim.core.gtu.RelativePosition relativePosition, org.djunits.value.vdouble.scalar.Time.Abs when) Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane.
Map<Lane,org.djunits.value.vdouble.scalar.Length.Rel>	positions(org.opentrafficsim.core.gtu.RelativePosition relativePosition) 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.
Map<Lane,org.djunits.value.vdouble.scalar.Length.Rel>	positions(org.opentrafficsim.core.gtu.RelativePosition relativePosition, org.djunits.value.vdouble.scalar.Time.Abs when) 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.
org.djunits.value.vdouble.scalar.Length.Rel	projectedPosition(Lane projectionLane, org.opentrafficsim.core.gtu.RelativePosition relativePosition, org.djunits.value.vdouble.scalar.Time.Abs when) Return the longitudinal position that this GTU would have if it were to change to another Lane with a/the current CrossSectionLink.
org.djunits.value.vdouble.scalar.Time.Abs	timeAtDistance(org.djunits.value.vdouble.scalar.Length.Rel distance) Determine the time when this GTU will have covered the specified distance from the position of the last evaluation time.

Methods inherited from interface org.opentrafficsim.core.gtu.GTU

destroy, getBounds, getFront, getGTUType, getId, getLength, getLocation, getMaximumVelocity, getOdometer, getRear, getReference, getRelativePositions, getSimulator, getVelocity, getWidth

Method Detail

getLongitudinalVelocity

org.djunits.value.vdouble.scalar.Speed getLongitudinalVelocity()

v(t) = v0 + (t - t0) * a.

Returns:

the velocity of the GTU, in the direction of the lane

getLongitudinalVelocity

org.djunits.value.vdouble.scalar.Speed getLongitudinalVelocity(org.djunits.value.vdouble.scalar.Time.Abs when)

Return the speed of this GTU at the specified time.
v(t) = v0 + (t - t0) * a

Parameters:

when - time for which the speed must be returned

Returns:

DoubleScalarAbs<SpeedUnit>; the speed at the specified time

getAcceleration

org.djunits.value.vdouble.scalar.Acceleration getAcceleration()

Specified by:

getAcceleration in interface org.opentrafficsim.core.gtu.GTU

Returns:

the acceleration (or deceleration) of the GTU, in the direction of the lane

getAcceleration

org.djunits.value.vdouble.scalar.Acceleration getAcceleration(org.djunits.value.vdouble.scalar.Time.Abs when)

Parameters:

when - time for which the speed must be returned

Returns:

the acceleration (or deceleration) of the GTU, in the direction of the lane.

getLateralVelocity

org.djunits.value.vdouble.scalar.Speed getLateralVelocity()

Returns:

the velocity of the GTU, perpendicular to the direction of the lane. Positive lateral velocity is "left" compared to the driving direction.

getLastEvaluationTime

org.djunits.value.vdouble.scalar.Time.Abs getLastEvaluationTime()

Returns:

DoubleScalarAbs<TimeUnit>; the time of last evaluation.

getNextEvaluationTime

org.djunits.value.vdouble.scalar.Time.Abs getNextEvaluationTime()

Returns:

DoubleScalarAbs<TimeUnit>; the time of next evaluation.

enterLane

void enterLane(Lane lane,
               org.djunits.value.vdouble.scalar.Length.Rel position)
        throws org.opentrafficsim.core.network.NetworkException

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 - the lane to add to the list of lanes on which the GTU is registered.

position - the position on the lane.

Throws:

org.opentrafficsim.core.network.NetworkException - on network inconsistency

leaveLane

void leaveLane(Lane lane)

Unregister the GTU from a lane.

Parameters:

lane - the lane to remove from the list of lanes on which the GTU is registered.

positions

Map<Lane,org.djunits.value.vdouble.scalar.Length.Rel> positions(org.opentrafficsim.core.gtu.RelativePosition relativePosition)
                                                         throws org.opentrafficsim.core.network.NetworkException

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.

Parameters:

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:

org.opentrafficsim.core.network.NetworkException - when the vehicle is not on one of the lanes on which it is registered.

positions

Map<Lane,org.djunits.value.vdouble.scalar.Length.Rel> positions(org.opentrafficsim.core.gtu.RelativePosition relativePosition,
                                                                org.djunits.value.vdouble.scalar.Time.Abs when)
                                                         throws org.opentrafficsim.core.network.NetworkException

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.

Parameters:

relativePosition - the position on the vehicle relative to the reference point.

when - 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:

org.opentrafficsim.core.network.NetworkException - when the vehicle is not on one of the lanes on which it is registered.

position

org.djunits.value.vdouble.scalar.Length.Rel position(Lane lane,
                                                     org.opentrafficsim.core.gtu.RelativePosition relativePosition)
                                              throws org.opentrafficsim.core.network.NetworkException

Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane at the current simulation time.

Parameters:

lane - the position on this lane will be returned.

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:

org.opentrafficsim.core.network.NetworkException - when the vehicle is not on the given lane.

position

org.djunits.value.vdouble.scalar.Length.Rel position(Lane lane,
                                                     org.opentrafficsim.core.gtu.RelativePosition relativePosition,
                                                     org.djunits.value.vdouble.scalar.Time.Abs when)
                                              throws org.opentrafficsim.core.network.NetworkException

Return the longitudinal position of a point relative to this GTU, relative to the center line of the Lane.

Parameters:

lane - the position on this lane will be returned.

relativePosition - the position on the vehicle relative to the reference point.

when - the future time for which to calculate the positions.

Returns:

DoubleScalarAbs<LengthUnit>; the position, relative to the center line of the Lane.

Throws:

org.opentrafficsim.core.network.NetworkException - when the vehicle is not on the given lane.

fractionalPositions

Map<Lane,Double> fractionalPositions(org.opentrafficsim.core.gtu.RelativePosition relativePosition)
                              throws org.opentrafficsim.core.network.NetworkException

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.

Parameters:

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:

org.opentrafficsim.core.network.NetworkException - when the vehicle is not on one of the lanes on which it is registered.

fractionalPositions

Map<Lane,Double> fractionalPositions(org.opentrafficsim.core.gtu.RelativePosition relativePosition,
                                     org.djunits.value.vdouble.scalar.Time.Abs when)
                              throws org.opentrafficsim.core.network.NetworkException

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.

Parameters:

relativePosition - the position on the vehicle relative to the reference point.

when - 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:

org.opentrafficsim.core.network.NetworkException - when the vehicle is not on one of the lanes on which it is registered.

fractionalPosition

double fractionalPosition(Lane lane,
                          org.opentrafficsim.core.gtu.RelativePosition relativePosition,
                          org.djunits.value.vdouble.scalar.Time.Abs when)
                   throws org.opentrafficsim.core.network.NetworkException

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.

Parameters:

lane - the position on this lane will be returned.

relativePosition - the position on the vehicle relative to the reference point.

when - the future time for which to calculate the positions.

Returns:

the fractional relative position on the lane at the given time.

Throws:

org.opentrafficsim.core.network.NetworkException - when the vehicle is not on the given lane.

fractionalPosition

double fractionalPosition(Lane lane,
                          org.opentrafficsim.core.gtu.RelativePosition relativePosition)
                   throws org.opentrafficsim.core.network.NetworkException

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.

Parameters:

lane - the position on this lane will be returned.

relativePosition - the position on the vehicle relative to the reference point.

Returns:

the fractional relative position on the lane at the given time.

Throws:

org.opentrafficsim.core.network.NetworkException - when the vehicle is not on the given lane.

projectedPosition

org.djunits.value.vdouble.scalar.Length.Rel projectedPosition(Lane projectionLane,
                                                              org.opentrafficsim.core.gtu.RelativePosition relativePosition,
                                                              org.djunits.value.vdouble.scalar.Time.Abs when)
                                                       throws org.opentrafficsim.core.network.NetworkException

Return the longitudinal position that this GTU would have if it were to change to another Lane with a/the current CrossSectionLink.

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 - DoubleScalar.Abs<TimeUnit>; the time for which to project the position of this GTU

Returns:

DoubleScalar.Rel<LengthUnit>; the position of this GTU in the projectionLane

Throws:

org.opentrafficsim.core.network.NetworkException - when projectionLane it not in any of the CrossSectionLink that the GTU is on

headway

HeadwayGTU headway(org.djunits.value.vdouble.scalar.Length.Rel maxDistance)
            throws org.opentrafficsim.core.network.NetworkException

Determine which GTU in front of this GTU, or behind this GTU. This method looks in all lanes where this GTU is registered, and not further than the absolute value of the given maxDistance. The minimum headway is returned of all Lanes where the GTU is registered. When no GTU is found within the given maxDistance, null is returned. The search will extend into successive lanes if the maxDistance is larger than the remaining length on the lane. 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.
Note: Headway is the net headway and calculated on a front-to-back basis.

Parameters:

maxDistance - the maximum distance to look for the nearest GTU; positive values search forwards; negative values search backwards

Returns:

HeadwayGTU; the headway and the GTU

Throws:

org.opentrafficsim.core.network.NetworkException - when there is an error with the next lanes in the network.

headway

HeadwayGTU headway(Lane lane,
                   org.djunits.value.vdouble.scalar.Length.Rel maxDistance)
            throws org.opentrafficsim.core.network.NetworkException

Determine by what distance the front of this GTU is behind the rear an other GTU, or the rear of this GTU is ahead of the front of an other GTU. Only positive values are returned. This method only looks in the given lane, and not further than the given maxDistance. When no vehicle is found within the given maxDistance, new DoubleScalar.Rel<LengthUnit>(Double.MAX_VALUE, METER) is returned. The search will extend into successive lanes if the maxDistance is larger than the length of the lane.
Note: Headway is the net headway and calculated on a front-to-back basis.

Parameters:

lane - the lane to look for another GTU

maxDistance - the maximum distance to look for; if positive, the search is forwards; if negative, the search is backwards

Returns:

HeadwayGTU; the headway and the GTU

Throws:

org.opentrafficsim.core.network.NetworkException - when the vehicle's route is inconclusive or vehicles are not registered correctly on their lanes

parallel

Set<LaneBasedGTU> parallel(Lane lane,
                           org.djunits.value.vdouble.scalar.Time.Abs when)
                    throws org.opentrafficsim.core.network.NetworkException

Determine which GTUs are parallel with us on another lane, based on fractional positions.
Note: When the GTU that calls the method is also registered on the given lane, it is excluded from the return set.

Parameters:

lane - the lane to look for parallel (partial or full overlapping) GTUs.

when - the future time for which to calculate the headway

Returns:

the set of GTUs parallel to us on the other lane (partial overlap counts as parallel), based on fractional positions, or an empty set when no GTUs were found.

Throws:

org.opentrafficsim.core.network.NetworkException - when the vehicle's route is inconclusive, when vehicles are not registered correctly on their lanes, or when the given lane is not parallel to one of the lanes where we are registered.

parallel

Set<LaneBasedGTU> parallel(org.opentrafficsim.core.network.LateralDirectionality lateralDirection,
                           org.djunits.value.vdouble.scalar.Time.Abs when)
                    throws org.opentrafficsim.core.network.NetworkException

Determine which GTUs are parallel with us in a certain lateral direction, based on fractional positions.
Note 1: This method will look to the adjacent lanes of all lanes where the vehicle has been registered.
Note 2: When the GTU that calls the method is also registered on the given lane, it is excluded from the return set.

Parameters:

lateralDirection - the direction of the adjacent lane(s) to look for parallel (partial or full overlapping) GTUs.

when - the future time for which to calculate the headway

Returns:

the set of GTUs parallel to us on other lane(s) in the given direction (partial overlap counts as parallel), based on fractional positions, or an empty set when no GTUs were found.

Throws:

org.opentrafficsim.core.network.NetworkException - when the vehicle's route is inconclusive, when vehicles are not registered correctly on their lanes, or when there are no lanes parallel to one of the lanes where we are registered in the given direction.

bestAccessibleAdjacentLane

Lane bestAccessibleAdjacentLane(Lane currentLane,
                                org.opentrafficsim.core.network.LateralDirectionality lateralDirection,
                                org.djunits.value.vdouble.scalar.Length.Rel longitudinalPosition)

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 negative lateral direction, RIGHT as a positive lateral direction.

Parameters:

currentLane - the lane to look for the best accessible adjacent lane

lateralDirection - the direction (LEFT, RIGHT) to look at

longitudinalPosition - DoubleScalar.Rel<LengthUnit>; the position of the GTU along this 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.

timeAtDistance

org.djunits.value.vdouble.scalar.Time.Abs timeAtDistance(org.djunits.value.vdouble.scalar.Length.Rel distance)

Determine the time when this GTU will have covered the specified distance from the position of the last evaluation time.

Parameters:

distance - DoubleScalar.Rel<LengthUnit>; the distance

Returns:

DoubleScalar.Rel<TimeUnit>; the time, or null if this GTU stops before covering the specified distance

deltaTimeForDistance

org.djunits.value.vdouble.scalar.Time.Rel deltaTimeForDistance(org.djunits.value.vdouble.scalar.Length.Rel distance)

Determine the time since last evaluation when this GTU has covered the specified distance from the position of the last evaluation time.

Parameters:

distance - DoubleScalar.Rel<LengthUnit>; the distance

Returns:

DoubleScalar.Rel<TimeUnit>; the time difference from last evaluation or null if this GTU stops before covering the specified distance

getGTUFollowingModel

GTUFollowingModel getGTUFollowingModel()

Retrieve the GTU following model of this LaneBasedGTU.

Returns:

GTUFollowingModel

getLaneChangeDistanceAndDirection

LaneChangeUrgeGTUColorer.LaneChangeDistanceAndDirection getLaneChangeDistanceAndDirection()

Return the distance available for the next needed lane change and the lateral direction of that lane change.

Returns:

LaneChangeAndDirection; the available distance and lateral direction for the next required lane change