Main Content

getAction

Get actions associated with actor

Since R2022a

    Description

    action = getAction(actorSim,actionName) gets the specified action actionName, if present, for the actor represented by actorSim at the current simulation time step. If no action is configured at the current time step, an empty array is returned.

    example

    action = getAction(actorSim,"UserDefinedAction",UserDefinedActionName) gets the user-defined action named UserDefinedActionName for the actor represented by actorSim.

    Examples

    collapse all

    Create sim, a ScenarioSimulation object

    rrApp = roadrunner("C:\Project\TestHighwayRoute"); 
    openScenario(rrApp,"myScenario1"); 
    sim = createSimulation(rrApp);

    Start the simulation.

    set(sim,"SimulationCommand","Start");

    Pause the simulation.

    set(sim,"SimulationCommand","Pause");

    Retrieve all actors from the simulation.

    actorsim = get(sim,"ActorSimulation"); 
    

    Get the first actor from the list.

    actorOne = actorsim{1};
    

    Get the lateral offset action of the first actor at the current time step.

    loAction = getAction(actorOne,"LateralOffsetAction")

    Input Arguments

    collapse all

    Actor from which to return action, specified as an ActorSimulation object.

    Actor action to be returned, specified as one of these values:

    • "PathAction"

    • "SpeedAction"

    • "LaneChangeAction"

    • "LateralOffsetAction"

    • "ChangeParameterAction"

    • "LongitudinalDistanceAction"

    • "UserDefinedAction"

    Data Types: string | char

    Name of the user-defined action to be returned, specified as a character vector or string scalar.

    Data Types: string | char

    Output Arguments

    collapse all

    Action of specified actor at current time step, returned as a struct. The type of structure depends on the input argument actionName.

    Value of actionNameValue of action
    "PathAction"PathAction structure
    "SpeedAction"SpeedAction structure
    "LaneChangeAction"LaneChangeAction structure
    "LateralOffsetAction"LateralOffsetAction structure
    "ChangeParameterAction"ChangeParameterAction structure
    "LongitudinalDistanceAction"LongitudinalDistanceAction structure
    "UserDefinedAction"UserDefinedAction structure

    More About

    collapse all

    PathAction structure

    The PathAction structure contains information about a path change action, if any, for the specified actor at the current time step. This table describes the fields of the PathAction structure.

    Field NameDescription
    ActorActionInformation about the current action of specified actor, returned as a struct. The fields of the structure are described in ActorAction structure.
    PathTargetActor target path, returned as a struct.

    This table describes the PathTarget structure of the PathAction structure.

    Field NameDescription
    Path

    Set of 3-D coordinates representing the target path, returned as an N-by-3 array where N = NumPoints.

    Each column value in the first row is the x-, y- and z- coordinate, respectively, of the first point in the target path, and so on.

    NumPointsTotal number of points in the target path, returned as a positive integer.
    HasTimingsIndication of target path containing timing information, returned as a Boolean value.
    PathPointTimingTiming information for each point of the path, returned as an N-by-1 structure array where N = NumPoints.

    This table describes the fields of each structure in the PathPointTiming structure array of the PathTarget structure within the PathAction structure.

    Field NameDescription
    TimeTime of arrival of the actor at this point, relative to the time at the starting point of the path. Returned in seconds.
    SpeedSpeed of actor at the time of arrival, returned in meters per second.
    WaitTimeWaiting time period of actor at arrival, returned in seconds. If this value is non-zero, then the actor is at rest.

    SpeedAction structure

    The SpeedAction structure contains information about a speed change action, if any, for the specified actor at the current time step. This table describes the fields of the SpeedAction structure.

    Field NameDescription
    ActorActionInformation about the current action of specified actor, returned as a struct. The fields of the structure are described in ActorAction structure.
    SpeedTargetTarget speed after speed change, returned as a struct.
    TransitionDynamicsTransition dynamics for the speed change, specified as a struct. The fields of the structure are described in TransitionDynamics structure.

    This table describes the SpeedTarget structure of the SpeedAction structure.

    Field NameDescription
    SpeedValueTarget speed value, returned as a double.
    SpeedComparison

    Comparison type of current speed with the target speed, returned as an enumeration variable of the EnumSpeedComparison enumeration class.

    The value of EnumSpeedComparison variable can be:

    • Unspecified — Unknown speed comparison type.

    • Absolute — The target speed is absolute.

    • SameAs — The speed difference is zero relative to the speed of the reference actor.

    • FasterThan — The target speed must be higher than the speed of the reference actor.

    • SlowerThan — The target speed must be lower than the speed of the reference actor.

    • FromPath — The target speed must match the speeds specified in the PathPointTiming structure of the PathTarget structure (within PathAction structure) of the actor reference path.

    RefActorIDIdentifier of reference actor, if any, returned as a positive integer
    RefSamplingMode

    Speed sampling mode of reference actor, if any, returned as an enumeration variable of the EnumReferenceSamplingMode enumeration class.

    The value of EnumReferenceSamplingMode variable can be:

    • Unspecified — Target speed comparison to reference actor speed is unknown.

    • AtActionStart — Indicates that the target speed compares with point speed of reference actor at start of the phase.

    • Continuous — Indicates that the target speed compares with point speed of reference actor continuously through entire phase or until another action controlling target speed is activated.

    LaneChangeAction structure

    The LaneChangeAction structure contains information about a lane change action, if any, for the specified actor at the current time step. This table describes the fields of the LaneChangeAction structure.

    Field NameDescription
    ActorActionInformation about the current action of specified actor, returned as a struct. The fields of the structure are described in ActorAction structure.
    LaneChangeTargetTarget lane after lane change, returned as a struct.
    TransitionDynamicsDynamics of the transition to the lane change, returned as a struct. The fields of the structure are described in TransitionDynamics structure.

    This table describes the fields of the LaneChangeTarget structure of the LaneChangeAction structure.

    Field NameDescription
    LaneValueNumber of lanes to change before reaching the target lane, returned as an int32 value.
    LaneComparison

    Direction of the lane change, returned as an enumeration variable of the EnumLaneComparison enumeration class.

    The value of EnumLaneComparison variable can be:

    • Unspecified — Unknown lane change direction.

    • SameAs — Actor moves to the same lane as the reference actor.

    • LeftOf — Actor moves to the lane left of the reference actor.

    • RightOf — Actor moves to the lane right of the reference actor.

    RefActorIDIdentifier of reference actor, returned as a positive integer.

    LateralOffsetAction structure

    The LateralOffsetAction structure contains information about lateral offset, if any, of the specified actor at the current time step. This table describes the fields of the LateralOffsetAction structure.

    Field NameDescription
    ActorActionInformation about the current action of specified actor, returned as a struct. The fields of the structure are described in ActorAction structure.
    LateralOffsetTargetLateral offset relative to the current path of specified actor, returned as a struct.
    TransitionDynamicsTransition dynamics for the lateral offset change, specified as a struct. The fields of the structure are described in TransitionDynamics structure.

    This table describes the LateralOffsetTarget structure of the LateralOffsetAction structure.

    Field NameDescription
    OffsetValue

    Target lateral offset relative to the current path, returned as a scalar of data type double.

    • A positive value indicates an offset to the right of the current path

    • A negative value indicates an offset to the left of the current path

    ChangeParameterAction structure

    The ChangeParameterAction structure contains information about a change in the custom behavior parameters, if any, of the specified actor at the current time step. This table describes the fields of the ChangeParameterAction structure.

    Field NameDescription
    ActorActionInformation about the current action of specified actor, returned as a struct. The fields of the structure are described in ActorAction structure.
    ParameterInformation about the changed user-specified behavior parameter, returned as a struct.

    This table describes the Parameter structure of the ChangeParameterAction structure.

    Field NameDescription
    NameName of the changed user-specified behavior parameter, returned as a string.
    ValueNew value of the user-specified behavior parameter, returned as a string.
    TypeType of parameter, returned as an enumeration variable of the EnumParameterType enumeration class.

    The value of EnumParameterType variable can be:

    • Unspecified — The type of the behavior parameter is unknown.

    • BehaviorParameter — User-specified behavior parameter.

    LongitudinalDistanceAction structure

    The LongitudinalDistanceAction structure contains information about changes, if any, in the longitudinal distance of the specified actor at the current time step. The longitudinal distance between two actors can be measured either as a space distance or a time distance. This table describes the fields of the LongitudinalDistanceAction structure.

    Field NameDescription
    ActorActionInformation about the current action of the specified actor, returned as a struct. The fields of the structure are described in ActorAction structure.
    DistanceTargetInformation about the longitudinal distance to the reference actor, returned as a struct.
    ReferenceSamplingMode

    Phase interval at which the target longitudinal distance is achieved, returned as an enumeration variable of the EnumReferenceSamplingMode enumeration class.

    The value of EnumReferenceSamplingMode variable can be:

    • Unspecified — Target longitudinal distance gap to reference actor is unknown.

    • AtActionStart — Target longitudinal distance gap to reference actor is achieved at the start of the current phase.

    • Continuous — Target longitudinal distance gap to reference actor is achieved and maintained until another action controlling longitudinal distance is activated.

    DynamicConstraintsDynamic constraints for the longitudinal distance change, returned as a struct.

    This table describes the DistanceTarget structure of the LongitudinalDistanceAction structure.

    Field NameDescription
    RefActorIDIdentifier of reference actor, returned as a positive integer.
    DistanceDimensionType

    Type of distance to reference actor, returned as an enumeration variable of the EnumDistanceDimensionType enumeration class.

    The value of EnumDistanceDimensionType variable can be:

    • Unspecified — Type of distance to reference actor is unknown.

    • Longitudinal —Type of distance to the reference actor is longitudinal.

    • Lateral — Type of distance to the reference actor is lateral.

    • Euclidean — Type of distance to the reference actor is Euclidean.

    DistanceType

    Specification of longitudinal distance as either time distance or space distance, returned as an enumeration variable of the EnumDistanceType enumeration class.

    The value of EnumDistanceType variable can be:

    • Unspecified — Unknown longitudinal distance specification

    • Space — Space distance

    • Time — Time distance

    ActorCoordinateSystemType

    Coordinate system in which to measure required longitudinal distance, returned as an enumeration variable of the EnumActorCoordinateSystemType enumeration class.

    The value of EnumActorCoordinateSystemType variable can be:

    • Unspecified — Unknown coordinate system

    • Lane — Lane-based st coordinate system (s-axis is the lane center line of the lane on which the entity is located)

    • Pose — Cartesian coordinate system

    ValueLongitudinal distance, returned as a double.
    PositionComparison

    Relative position to reference actor, returned as an enumeration variable of the EnumPositionComparison enumeration class.

    The value of EnumPositionComparison variable can be:

    • Unspecified — Unknown relative position to reference actor

    • SameAs — Parallel to reference actor

    • AheadOf — Ahead of reference actor

    • Behind — Behind reference actor

    • Either — Ahead of or behind reference actor

    MeasureFrom

    Longitudinal distance is either measured between the closest points on two actors' bounding boxes or between the origin point of both actors. Returned as an enumeration variable of the EnumMeasureFrom enumeration class.

    The value of EnumMeasureFrom variable can be:

    • Unspecified — Unknown distance measurement type.

    • BoundingBoxes — Distance is measured as the gap between the rear end of the leading vehicle and the front end of the trailing vehicle.

    • Origins — Distance is measured as the gap between the origin of the leading vehicle and the origin of the trailing vehicle.

    This table describes the DynamicConstraints structure of the LongitudinalDistanceAction structure.

    Field NameDescription
    UnlimitedDynamicsPresence of dynamic constraints, returned as a Boolean value.
    MaxSpeedMaximum speed that an actor can attain while approaching target longitudinal distance to reference actor, returned as a double.
    MaxAccelerationMaximum acceleration that an actor can attain while approaching target longitudinal distance to reference actor, returned as a double.
    MaxDecelerationMaximum deceleration that an actor can attain while approaching target longitudinal distance to reference actor, returned as a double.

    UserDefinedAction structure

    The UserDefinedAction structure contains information about a user-defined action, if any, for the specified actor at the current time step. This table describes the fields of the UserDefinedAction structure.

    Field NameDescription
    ActorActionInformation about the current action of the specified actor, returned as a struct. The fields of the structure are described in ActorAction structure.
    NameAction name, returned as a string.
    ParametersCustom parameters of the user-defined action, returned as a struct. This structure contains the name and value of each custom parameter.

    ActorAction structure

    This table describes the fields of the ActorAction structure.

    Field NameDescription
    ActorIDIdentifier of actor performing the action, returned as a positive integer.
    PhaseInterval

    Phase interval to which the action is applied, returned as an enumeration variable of the EnumPhaseInterval enumeration class.

    The value of EnumPhaseInterval variable can be:

    • Unspecified — Unknown phase interval for the action.

    • AtStart — Specified action is completed at the start of the current phase.

    • AtEnd — Specified action is completed by the end of the current phase.

    • Invariant — Specified action objective is maintained during the current phase.

    ActionType

    Action type, returned as an enumeration variable of the EnumActionType enumeration class.

    The value of EnumActionType variable can be:

    • Unspecified — Unknown action type.

    • LaneChange — Lane change action.

    • Path — Path action.

    • Speed — Speed action.

    • LateralOffset — Lateral offset action.

    • ChangeParameter — Change parameter action.

    TransitionDynamics structure

    This table describes the fields of the TransitionDynamics structure.

    Field NameDescription
    Dimension

    Transition metric measuring the action change, returned as an enumeration variable of the EnumDynamicsDimension enumeration class.

    The value of EnumDynamicsDimension variable can be:

    • Unspecified — Unknown transition metric to measure specified change action.

    • Rate — The change action occurs within specified rate value.

    • Time — The change action occurs within specified time value (seconds).

    • Distance — The change action occurs within specified distance value (meters).

    Shape

    Shape of the transition curve, returned as an enumeration variable of the EnumDynamicsShape enumeration class.

    The value of EnumDynamicsShape variable can be:

    • Unspecified — The shape of the transition curve is unknown.

    • Linear — The transition curve is linear.

    • Cubic — The transition curve is cubic.

    • Step — The transition curve is step-shaped.

    ValueValue of the chosen transition metric, returned as a double.

    Version History

    Introduced in R2022a