DistanceToActorCondition

Specify Distance To Actor condition

Since R2025a

expand all in page

    Description

    A DistanceToActorCondition object represents a Distance To Actor condition in the RoadRunner scenario logic. The Distance To Actor condition specifies for the associated phase to end when the actor is a certain distance away from the reference actor. Specifying DistanceToActorCondition as the condition type when creating an end or fail condition in your scenario adds a Distance To Actor condition to the specified phase in the scenario logic. You can use the DistanceToActorCondition object to programmatically modify the attributes of the corresponding Distance To Actor condition by changing the property values of the object.

    Creation

    You can create a DistanceToActorCondition object in these ways:

    • The setEndCondition function creates and assigns a condition of the specified type to the end of a specified phase. Specify the conditionType argument as "DistanceToActorCondition" to create a DistanceToActorCondition object associated with the specified phase.

    • The setFailCondition function assigns a condition of the specified type to the Fail Conditions of the scenario root phase. Specify the conditionType argument as "DistanceToActorCondition" to create a DistanceToActorCondition object associated with the scenario Fail Conditions.

    Properties

    expand all

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

    Note

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

    Actor to compare against the condition, 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.

    RoadRunner Scenario calculates distance based on the position of Actor relative to ReferenceActor.

    Note

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

    Reference actor position to compare against 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.

    Rule for distance comparison, specified as one of these options:

    • "le" — The actor satisfies the condition when it is less than or equal to Distance meters from the reference actor.

    • "ge" — The actor satisfies the condition when it is greater than or equal to Distance meters from the reference actor.

    Distance, in meters, at which the actor satisfies the condition, specified as a positive scalar. RoadRunner Scenario uses the method specified by Rule to compare the distance between the actor and reference actor to the specified value of Distance.

    Data Types: double

    Examples

    collapse all

    Use a DistanceToActorCondition object to specify for the actor to change lanes when it reaches a distance less than or equal to 10 m from a reference actor.

    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.

    Design Scenario Using Distance To Actor Condition

    Use addPhaseInSerial to add a new actor action phase, srPhase, in serial after the initial phase. Then, use addAction to specify "ChangeLaneAction" as the action type of the new phase. srPhase represents the newly added actor action phase in the RoadRunner scenario logic, and chLn represents the Change Lane action type assigned to srPhase.

    srPhase = addPhaseInSerial(rrLogic,initPhase,"ActorActionPhase",Insertion="after");
chLn = addAction(srPhase,"ChangeLaneAction");

    Assign the actor to the new phase by specifying car as the value of the Actor property of the phase. Then, specify for the actor to change lanes to the right by setting the Direction property to "right".

    srPhase.Actor = car;
chLn.Direction = "right";

    Add a second actor, car2, to the scenario. Then, reposition car2 to 20 meters in front of car by specifying an initial forward offset of 20.

    car2 = addActor(scnro,mySedan,[0 0 0]);
car2Point = car2.InitialPoint;
anchorToPoint(car2Point,anchorPoint,PosePreservation="reset-pose")
car2.InitialPoint.ForwardOffset = 20;

    Use initialPhaseForActor to extract the object for the initial phase of the actor car2. Then, use the findActions function to extract the ChangeSpeedAction object from that phase and change the Speed property of the action to 10 m/s.

    car2Init = initialPhaseForActor(rrLogic,car2);
car2Speed = findActions(car2Init,"ChangeSpeedAction");
car2Speed.Speed = 10;

    Use setEndCondition to add a condition, rrCondition, to the initial phase initPhase and specify the condition type as "DistanceToActorCondition". 

    rrCondition = setEndCondition(initPhase,"DistanceToActorCondition");

    Specify for the condition rrCondition to compare the distance between the two actors by setting the Actor property to car and the ReferenceActor property to car2. Then, set the Distance property to 10. This specifies for the actor car to change lanes to the right when it reaches a distance within 10 meters of the reference actor car2.

    rrCondition.Actor = car;
rrCondition.ReferenceActor = car2;
rrCondition.Distance = 10;

    Run the simulation by using the simulateScenario function. 

    simulateScenario(rrApp)

    Version History

    Introduced in R2025a

    See Also

    | | | |