ChangeLongitudinalDistanceAction

Specify Change Longitudinal Distance action

Since R2025a

expand all in page

    Description

    The ChangeLongitudinalDistanceAction object represents a Change Longitudinal Distance action in the RoadRunner scenario logic. The Change Longitudinal Distance action specifies for the actor to change its forward distance relative to another actor using the specified properties. You can use this action to maintain a constant longitudinal distance gap between two actors during simulation. Specifying ChangeLongitudinalDistanceAction as the action type when adding an action to your scenario adds a Change Longitudinal Distance action to the specified phase in the scenario logic. You can use the ChangeLongitudinalDistanceAction object to programmatically modify the attributes of the corresponding Change Longitudinal Distance action by changing the property values of the object.

    Creation

    The addAction function adds an action of the specified type as a child to the specified phase. Specify the actionType argument as "ChangeLongitudinalDistanceAction" to create a ChangeLongitudinalDistanceAction object associated with the specified phase.

    Properties

    expand all

    Name of the action, specified as a string scalar or character vector.

    Note

    You can specify the Name property of ChangeLongitudinalDistanceAction in MATLAB®, but RoadRunner Scenario does not display the Name property of actions in the user interface.

    Phase containing the action, specified as an ActorActionPhase object.

    Reference actor against which to compare the longitudinal distance of the actor, specified as one of these objects:

    • Vehicle — Represents a vehicle actor in the RoadRunner scenario.

    • Character — Represents a character actor in the RoadRunner scenario.

    • MovableObject — Represents a movable object actor in the RoadRunner scenario.

    Note

    You must specify a nonempty value for this property before you can run the simulation.

    Relative position of the actor with respect to ReferenceActor, specified as one of these options:

    • "behind" — The actor is behind ReferenceActor.

    • "ahead" — The actor is ahead of ReferenceActor.

    • "either" — The actor is either ahead of or behind ReferenceActor.

    Longitudinal distance type, specified as one of these options:

    • "space" — RoadRunner Scenario measures the longitudinal distance in terms of the physical distance between the actor and ReferenceActor

    • "time" — RoadRunner Scenario measures the longitudinal distance in terms of the time interval between the actor and ReferenceActor.

    The DistanceType option you specify determines what the value of the DistanceOffset property represents.

    The relative longitudinal distance or time offset between the actor and ReferenceActor, specified as a positive integer.

    Method of measuring the longitudinal distance between the actor and ReferenceActor with respect to the vehicle boundaries, specified as one of these options:

    • "bounding-box" — Measures longitudinal distance between the bounding boxes of the two actors.

    • "origins" — Measures longitudinal distance between the origin points of the two actors.

    Sampling method used to achieve a longitudinal distance of the actor relative to ReferenceActor, specified as one of these options:

    • "action-start" — The actor achieves the target longitudinal distance gap relative to ReferenceActor while executing the action.

    • "continuous" — The actor achieves the target longitudinal distance gap relative to ReferenceActor continuously until ended by another action that controls longitudinal distance or the end of the simulation.

    Actor constraints for executing longitudinal distance change, specified as one of these constraint types:

    • "asset" — The actor must follow the constraints in its own list of attributes.

    • "custom" — The actor must comply with the vehicle acceleration or deceleration values specified by the MaxAcceleration, MaxDeceleration and MaxSpeed properties.

    • "none" — The actor has no constraints while achieving the target longitudinal distance.

    Maximum speed used to achieve the longitudinal distance change, specified as a numeric scalar. To set this property, you must set the value of the ConstraintType property to "custom".

    Data Types: double

    Maximum acceleration used to achieve the longitudinal distance change, specified as a numeric scalar. To set this property, you must set the value of the ConstraintType property to "custom".

    Data Types: double

    The maximum deceleration used to achieve the longitudinal distance change, specified as a numeric scalar. To set this property, you must set the value of the ConstraintType property to "custom".

    Data Types: double

    Examples

    collapse all

    Use a ChangeLongitudinalDistanceAction object to specify for an actor to change its longitudinal distance behind a reference actor to 5 meters during simulation.

    This example assumes that you have prior knowledge of working with RoadRunner in MATLAB. Before proceeding, follow the steps outlined in Set Up MATLAB Environment for RoadRunner Authoring Functions to set up your scenario using MATLAB functions for scenario authoring.

    Add Reference Actor

    Add a second vehicle actor to the scenario in the same lane as car. Set the ForwardOffset property of refCar to 20 to move it 20 meters ahead of car. The refCar object represents the reference actor for RoadRunner Scenario to use when calculating longitudinal distance from car.

    refCar = addActor(scnro,mySedan,[0 0 0]);
refCar.Name = "ReferenceCar";
refAnchor = findSceneAnchor(scnro,"ScenarioStart");
refCarPoint = refCar.InitialPoint;
anchorToPoint(refCarPoint,refAnchor,PosePreservation="reset-pose")
refCar.InitialPoint.ForwardOffset = 20;

    Add ChangeLongitudinalDistanceAction to Scenario Logic

    Use addPhaseInSerial to add a new actor action phase, srPhase, in serial after the initial phase. Then, use addAction to specify the action of the new phase as "ChangeLongitudinalDistanceAction". The srPhase object represents the newly created actor action phase in the scenario logic, and chLon represents the Change Longitudinal Distance action assigned to srPhase.

    srPhase = addPhaseInSerial(rrLogic,initPhase,"ActorActionPhase",Insertion="after");
chLon = addAction(srPhase,"ChangeLongitudinalDistanceAction");

    Assign car to the Actor property of the action phase srPhase. For the Change Longitudinal Distance action chLon, set the ReferenceActor property to refCar, the DistanceOffset property to 5, and the SamplingMode property to "Continuous". This instructs the assigned actor car to change its longitudinal distance behind refCar to 5 meters during simulation.

    srPhase.Actor = car;
chLon.ReferenceActor = refCar;
chLon.DistanceOffset = 5;
chLon.SamplingMode = "continuous";

    Run the simulation by using the simulateScenario function.

    simulateScenario(rrApp)

    Version History

    Introduced in R2025a

    See Also

    | | | |

    Topics