getAction

Get actions associated with actor

Since R2022a

Syntax

action = getAction(actorSim,actionName)

action = getAction(actorSim,"UserDefinedAction",UserDefinedActionName)

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

Get Lateral Offset Action of Actor

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

`actorSim` — Actor
`ActorSimulation` object

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

`actionName` — Actor action
`"PathAction"` | `"SpeedAction"` | `"LaneChangeAction"` | `"LateralOffsetAction"` | `"ChangeParameterAction"` | `"LongitudinalDistanceAction"` | `"UserDefinedAction"`

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

"PathAction"
"SpeedAction"
"LaneChangeAction"
"LateralOffsetAction"
"ChangeParameterAction"
"LongitudinalDistanceAction"
"UserDefinedAction"

Data Types: string | char

`UserDefinedActionName` — Name of user-defined action
character vector | string scalar

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` — Action
`struct`

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

Value of `actionName`	Value 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 Name	Description
`ActorAction`	Information about the current action of specified actor, returned as a `struct`. The fields of the structure are described in `ActorAction` structure.
`PathTarget`	Actor target path, returned as a `struct`.

This table describes the PathTarget structure of the PathAction structure.

Field Name	Description
`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.
`NumPoints`	Total number of points in the target path, returned as a positive integer.
`HasTimings`	Indication of target path containing timing information, returned as a Boolean value.
`PathPointTiming`	Timing 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 Name	Description
`Time`	Time of arrival of the actor at this point, relative to the time at the starting point of the path. Returned in seconds.
`Speed`	Speed of actor at the time of arrival, returned in meters per second.
`WaitTime`	Waiting 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 Name	Description
`ActorAction`	Information about the current action of specified actor, returned as a `struct`. The fields of the structure are described in `ActorAction` structure.
`SpeedTarget`	Target speed after speed change, returned as a `struct`.
`TransitionDynamics`	Transition 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 Name	Description
`SpeedValue`	Target 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.
`RefActorID`	Identifier 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 Name	Description
`ActorAction`	Information about the current action of specified actor, returned as a `struct`. The fields of the structure are described in `ActorAction` structure.
`LaneChangeTarget`	Target lane after lane change, returned as a `struct`.
`TransitionDynamics`	Dynamics 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 Name Description

LaneValue Number of lanes to change before reaching the target lane, returned as an int32 value.

Field Name	Description
`LaneValue`	Number 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.
`RefActorID`	Identifier of reference actor, returned as a positive integer.

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.

RefActorID Identifier 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 Name	Description
`ActorAction`	Information about the current action of specified actor, returned as a `struct`. The fields of the structure are described in `ActorAction` structure.
`LateralOffsetTarget`	Lateral offset relative to the current path of specified actor, returned as a `struct`.
`TransitionDynamics`	Transition 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 Name	Description
`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 Name	Description
`ActorAction`	Information about the current action of specified actor, returned as a `struct`. The fields of the structure are described in `ActorAction` structure.
`Parameter`	Information about the changed user-specified behavior parameter, returned as a `struct`.

This table describes the Parameter structure of the ChangeParameterAction structure.

Field Name Description

Name Name of the changed user-specified behavior parameter, returned as a string.

Value New value of the user-specified behavior parameter, returned as a string.

Field Name	Description
`Name`	Name of the changed user-specified behavior parameter, returned as a string.
`Value`	New value of the user-specified behavior parameter, returned as a string.
`Type`	Type 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.

Type

Type 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 Name	Description
`ActorAction`	Information about the current action of the specified actor, returned as a `struct`. The fields of the structure are described in `ActorAction` structure.
`DistanceTarget`	Information 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.
`DynamicConstraints`	Dynamic constraints for the longitudinal distance change, returned as a `struct`.

This table describes the DistanceTarget structure of the LongitudinalDistanceAction structure.

Field Name	Description
`RefActorID`	Identifier 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
`Value`	Longitudinal 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 Name	Description
`UnlimitedDynamics`	Presence of dynamic constraints, returned as a Boolean value.
`MaxSpeed`	Maximum speed that an actor can attain while approaching target longitudinal distance to reference actor, returned as a `double`.
`MaxAcceleration`	Maximum acceleration that an actor can attain while approaching target longitudinal distance to reference actor, returned as a `double`.
`MaxDeceleration`	Maximum 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 Name	Description
`ActorAction`	Information about the current action of the specified actor, returned as a `struct`. The fields of the structure are described in `ActorAction` structure.
`Name`	Action name, returned as a string.
`Parameters`	Custom 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 Name Description

ActorID Identifier of actor performing the action, returned as a positive integer.

Field Name	Description
`ActorID`	Identifier 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.

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 Name Description

Field Name	Description
`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.
`Value`	Value of the chosen transition metric, returned as a `double`.

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.

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

Version History

Introduced in R2022a

getAction

Syntax

Description

Examples

Get Lateral Offset Action of Actor

Input Arguments

actorSim — Actor ActorSimulation object

actionName — Actor action "PathAction" | "SpeedAction" | "LaneChangeAction" | "LateralOffsetAction" | "ChangeParameterAction" | "LongitudinalDistanceAction" | "UserDefinedAction"

UserDefinedActionName — Name of user-defined action character vector | string scalar

Output Arguments

action — Action struct

More About

PathAction structure

SpeedAction structure

LaneChangeAction structure

LateralOffsetAction structure

ChangeParameterAction structure

LongitudinalDistanceAction structure

UserDefinedAction structure

ActorAction structure

TransitionDynamics structure

Version History

See Also

`actorSim` — Actor
`ActorSimulation` object

`actionName` — Actor action
`"PathAction"` | `"SpeedAction"` | `"LaneChangeAction"` | `"LateralOffsetAction"` | `"ChangeParameterAction"` | `"LongitudinalDistanceAction"` | `"UserDefinedAction"`

`UserDefinedActionName` — Name of user-defined action
character vector | string scalar

`action` — Action
`struct`

`PathAction` structure

`SpeedAction` structure

`LaneChangeAction` structure

`LateralOffsetAction` structure

`ChangeParameterAction` structure

`LongitudinalDistanceAction` structure

`UserDefinedAction` structure

`ActorAction` structure

`TransitionDynamics` structure