Package org.opentrafficsim.road.gtu.lane

Interface LaneBasedGTU

    • Field Detail

      • LANEBASED_INIT_EVENT

        static final TimedEventType LANEBASED_INIT_EVENT
        The lane-based event type for pub/sub indicating the initialization of a new GTU.
        Payload: [String gtuId, PositionVector initialPosition, Direction initialDirection, Length length, Length width, String linkId, String laneId, Length positionOnReferenceLane, GTUDirectionality direction, GTUType gtuType]

      • LANEBASED_MOVE_EVENT

        static final TimedEventType 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, Link id of referenceLane, Lane id of referenceLane, Length positionOnReferenceLane, GTUDirectionality direction]

      • LANEBASED_DESTROY_EVENT

        static final TimedEventType 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, Link referenceLink, Lane referenceLane, Length positionOnReferenceLane, GTUDirectionality direction]

      • LANE_ENTER_EVENT

        static final EventType LANE_ENTER_EVENT
        The event type for pub/sub indicating that the GTU entered a new lane (with the FRONT position if driving forward; REAR if driving backward).
        Payload: [String gtuId, String link id, String lane id]

      • LANE_EXIT_EVENT

        static final EventType LANE_EXIT_EVENT
        The event type for pub/sub indicating that the GTU exited a lane (with the REAR position if driving forward; FRONT if driving backward).
        Payload: [String gtuId, String link id, String lane id]

      • LANE_CHANGE_EVENT

        static final TimedEventType LANE_CHANGE_EVENT
        The event type for pub/sub indicating that the GTU change lane.
        Payload: [String gtuId, LateralDirectionality direction, DirectedLanePosition from]

    • Method Detail

      • getNetwork

        RoadNetwork getNetwork()
        Returns:
        the road network to which the LaneBasedGTU belongs

      • changeLaneInstantaneously

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

      • initLaneChange

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

      • setFinalizeLaneChangeEvent

        void setFinalizeLaneChangeEvent​(SimEventInterface<Duration> event)
        Sets event to finalize lane change.
        Parameters:
        event - SimEventInterface<SimTimeDoubleUnit>; event

      • getProjectedLength

        default Length getProjectedLength​(Lane lane)
                           throws GTUException
        Get projected length on the lane.
        Parameters:
        lane - Lane; lane to project the vehicle on
        Returns:
        Length; the length on the lane, which is different from the actual length during deviative tactical plans
        Throws:
        GTUException - when the vehicle is not on the given lane

      • setInstantaneousLaneChange

        void setInstantaneousLaneChange​(boolean instantaneous)
        Sets whether the GTU perform lane changes instantaneously or not.
        Parameters:
        instantaneous - boolean; whether the GTU perform lane changes instantaneously or not

      • isInstantaneousLaneChange

        boolean isInstantaneousLaneChange()
        Returns whether the GTU perform lane changes instantaneously or not.
        Returns:
        boolean; whether the GTU perform lane changes instantaneously or not

      • positions

        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.
        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

        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.
        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

        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.
        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.

      • position

        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.
        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.

      • fractionalPositions

        Map<Lane,​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.
        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

        Map<Lane,​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.
        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

        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.
        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

        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.
        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.

      • getReferencePosition

        DirectedLanePosition getReferencePosition()
                                   throws GTUException
        Return the current Lane, position and directionality of the GTU.
        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

      • getDirection

        GTUDirectionality getDirection​(Lane lane)
                        throws GTUException
        Return the directionality of a lane on which the GTU is registered for its current operational plan.
        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

      • addTrigger

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

      • setNoLaneChangeDistance

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

      • laneChangeAllowed

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

      • getDesiredSpeed

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

      • getCarFollowingAcceleration

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

      • getVehicleModel

        default VehicleModel getVehicleModel()
        Returns the vehicle model.
        Returns:
        VehicleModel; vehicle model

      • isBrakingLightsOn

        default boolean isBrakingLightsOn()
        The default implementation returns true if the deceleration is larger than a speed-dependent threshold given by:

        c0 * g(v) + c1 + c3*v^2

        where c0 = 0.2, c1 = 0.15 and c3 = 0.00025 (with c2 = 0 implicit) are empirically derived averages, and g(v) is 0 below 25 km/h or 1 otherwise, representing that the engine is disengaged at low speeds.
        Returns:
        boolean; whether the braking lights are on

      • isBrakingLightsOn

        default boolean isBrakingLightsOn​(Time when)
        The default implementation returns true if the deceleration is larger than a speed-dependent threshold given by:

        c0 * g(v) + c1 + c3*v^2

        where c0 = 0.2, c1 = 0.15 and c3 = 0.00025 (with c2 = 0 implicit) are empirically derived averages, and g(v) is 0 below 25 km/h or 1 otherwise, representing that the engine is disengaged at low speeds.
        Parameters:
        when - Time; time
        Returns:
        boolean; whether the braking lights are on

      • getLateralPosition

        Length getLateralPosition​(Lane lane)
                   throws GTUException
        Returns the lateral position of the GTU relative to the lane center line. Negative values are towards the right.
        Parameters:
        lane - Lane; lane to consider (most important regarding left/right, not upstream downstream)
        Returns:
        Length; lateral position of the GTU relative to the lane center line
        Throws:
        GTUException - when the vehicle is not on the given lane.

      • getTurnIndicatorStatus

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

      • getTurnIndicatorStatus

        TurnIndicatorStatus getTurnIndicatorStatus​(Time time)
        Parameters:
        time - Time; time to obtain the turn indicator status at
        Returns:
        the status of the turn indicator at the given time

      • setTurnIndicatorStatus

        void setTurnIndicatorStatus​(TurnIndicatorStatus turnIndicatorStatus)
                     throws GTUException
        Set the status of the turn indicator.
        Parameters:
        turnIndicatorStatus - TurnIndicatorStatus; the new status of the turn indicator.
        Throws:
        GTUException - when GTUType does not have a turn indicator