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.

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

Examples

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

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

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

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