getAttribute

Get run-time attribute of actor

Since R2022a

Syntax

runtimeAttr = getAttribute(actorSim,runtimeAttrName)

Description

runtimeAttr = getAttribute(actorSim,runtimeAttrName) returns the specified run-time attribute of the ActorSimulation object actorSim. When you use this function inside the stepImpl method of MATLAB^® System object™, the function returns the states from the previous time step, except the actor ID.

Examples

Get Run-time Attributes of Actor

Create a ScenarioSimulation object by using the roadrunner and createSimulation functions.

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");

Get all the ActorSimulation objects from the simulation.

actorSims = get(sim,"ActorSimulation"); 

Get the first and second ActorSimulation objects.

actorOne = actorSims{1};
actorTwo = actorSims{2};

Get the ID of actorOne.

id = getAttribute(actorOne,"ID")

id =

  uint64

   1

Get the actor type of actorOne. The actor type is returned as a uint8 row vector.

actortype_uint8 = getAttribute(actorOne,"ActorType")

actortype_uint8 =

  1×5 uint8 row vector

    87   111   114   108   100

Convert the uint8 row vector into a character array to obtain a readable word.

actortype_char = char(actortype_uint8)

ans =

    'World'

Get the pose of actorOne. For more information about actor poses, see What Is a RoadRunner Pose Matrix?

pose = getAttribute(actorOne,"Pose")

pose =

    0.1096    0.9940   -0.0000  -28.1452
   -0.9940    0.1096    0.0000   -3.2291
    0.0000    0.0000    1.0000   -0.0000
         0         0         0    1.0000

Get the velocity of actorTwo.

velocity = getAttribute(actorTwo,"Velocity")

velocity =

    6.9507    2.8702    0.0000

Get the angular velocity of actorOne.

angvelocity = getAttribute(actorTwo,"AngularVelocity") 

angvelocity =

     0     0.23     0

Get the wheel poses of actorTwo.

wheelposes = getAttribute(actorTwo,"WheelPoses")

wheelposes(:,:,1) =

    0.9972   -0.0671   -0.0330   -0.5672
   -0.0747   -0.8946   -0.4405    1.3838
         0    0.4417   -0.8971    0.3441
         0         0         0    1.0000


wheelposes(:,:,2) =

    0.9974   -0.0650   -0.0320    0.5672
   -0.0725   -0.8948   -0.4406    1.3838
         0    0.4417   -0.8971    0.3441
         0         0         0    1.0000


wheelposes(:,:,3) =

    1.0000         0         0   -0.5672
         0   -0.8971   -0.4417   -1.3295
         0    0.4417   -0.8971    0.3441
         0         0         0    1.0000


wheelposes(:,:,4) =

    1.0000         0         0    0.5672
         0   -0.8971   -0.4417   -1.3295
         0    0.4417   -0.8971    0.3441
         0         0         0    1.0000

Get the map location of actorOne.

ml = getAttribute(actorOne,"LaneLocation")

ml = 

  struct with fields:

          IsOnLane: 1
    LocationOnLane: [1×1 struct]

Check whether the actor is on its lane.

ml.IsOnLane

ans =

  logical

   1

Get information about the lane the actor is on.

ml.LocationOnLane

ans = 

  struct with fields:

      LaneID: '{7c2e895c-6b90-4892-aa6e-9ed116db53b5}'
    Position: 0.5359
       Angle: 0.0014

Input Arguments

actorSim — Actor

ActorSimulation object

Actor to return run-time attributes from, specified as an ActorSimulation object.

runtimeAttrName — Name of run-time attribute

"ID" | "Pose" | "Velocity" | "AngularVelocity" | "WheelPoses" | "LaneLocation" | "Children" | "Parent" | "PhaseStatus" | "ActorType" | "TrafficSignalRuntime" | "TrafficSignalControllerRuntime"

Name of run-time attribute to be retrieved, specified as one of these values:

• "ID"

• "Pose"

• "Velocity"

• "AngularVelocity"

• "WheelPoses"

• "LaneLocation"

• "Children"

• "Parent"

• "PhaseStatus"

• "ActorType"

• "TrafficSignalRuntime"

• "TrafficSignalControllerRuntime"

Data Types: string | char

Output Arguments

runtimeAttr — Run-time attribute of actor

scalar | array | structure

Run-time attribute of actor, returned as a scalar, array, structure, or object, depending on the input argument runtimeAttrName.

runtimeAttrName	Description
"ID"	Actor identifier, returned as a scalar of data type uint64.
"Pose"	Position and orientation of actor in the RoadRunner Scenario coordinate system, returned as a 4-by-4 array. See What Is a RoadRunner Pose Matrix? for more information.
"Velocity"	Velocity of actor in the x, y, and z directions, returned as a 1-by-3 vector. Units are in meters per second.
"AngularVelocity"	Angular velocity of actor in the x, y, and z directions, returned as a 1-by-3 vector. Units are in radians per second.
"WheelPoses"	Run-time pose of each wheel of vehicle-type actor, returned as a 4-by-4-by-N array. N is the number of wheels of the vehicle-type actor. WheelPoses is returned for wheels starting on the leftmost side of the front axle, and moving to the right. After the first axle is complete, the leftmost wheel on the second axle is taken into consideration before moving to the right, and so on.
"LaneLocation"	Location of actor with respect to its mapped lane, returned as a structure of type LaneLocation.
"Children"	Immediate children of specified actor, if any, returned as a cell array of ActorSimulation objects. If the specified actor does not have any child actors, then an empty cell array is returned.
"Parent"	Immediate parent of specified actor, returned as an ActorSimulation object. If the specified actor itself is a parent, then the ActorSimulation object corresponding to the world actor is returned.
"PhaseStatus"	Information about all the phases of a particular actor, returned as a structure of type PhaseStatus.
"ActorType"	Type of actor in a scenario, returned as a uint8 row vector. Note To obtain a readable word, you must convert the uint8 row vector into a character array by using the char function. These are the possible outputs: "World" — World actor "Vehicle" — Vehicle actor "Character" — Character actor, such as a pedestrian "TrafficSignal" — Traffic signal actor "TrafficSignalController" — Traffic signal controller "Unspecified" — Unknown actor type
"TrafficSignalRuntime"	Run-time information about a traffic signal, returned as a structure of type TrafficSignalRuntime. For more information about cosimulation of RoadRunner Scenario with traffic signal actors in MATLAB, see Simulate RoadRunner Scenarios with Traffic Signals in MATLAB.
"TrafficSignalControllerRuntime"	Run-time information about a traffic signal controller, returned as a structure of type TrafficSignalControllerRuntime. For more information about cosimulation of RoadRunner Scenario with traffic signal controllers in MATLAB, see Simulate RoadRunner Scenarios with Traffic Signals in MATLAB.

More About

LaneLocation Structure

This table describes the fields of the LaneLocation structure:

Field Name	Description
IsOnLane	Boolean value indicating if the actor is located on a lane. An actor is considered to be on a certain lane if its model origin lies in between the left and right boundaries of this lane.
LocationOnLane	Current lane of actor, returned as a structure of type LocationOnLane. If an actor straddles several lanes, the most aligned lane is returned.

This table describes the fields of the LocationOnLane structure of the LaneLocation structure:

Field Name	Description
LaneID	Universal unique identifiers (UUID) of the most aligned lane, returned as a string.
Position	Position of the actor on the lane-center polyline (in s-value). The s-value is a double value within [0, 1] that indicates a position on a 3-D polyline with 0 at the start and 1 at the end of the polyline.
Angle	Angle between the actor travel direction and tangent at the lane position. Units are in radians.

PhaseStatus Structure

This table describes the fields of the PhaseStatus structure:

Field Name	Description
PhaseID	Identifier of the phase, returned as a string.
PhaseName	Name of phase, returned as a string.
ActorID	Actor identifier, returned as a uint64 scalar.
StartConditionStatus	Status of the start condition, returned as a structure of type StartConditionStatus.
EndConditionStatus	Status of the end condition, returned as a structure, returned as a structure of type EndConditionStatus
ActionType	Action type, returned as an enumeration variable. The value of the variable can be: LaneChange — Lane change action Path — Path action Speed — Speed action LateralOffset — Lateral offset action Position — Position action
PhaseState	Run-time state of a phase, returned as an enumeration variable. The value of the variable can be: Unspecified — The phase has not yet been initialized. Idle — The phase is not running currently, and its start conditions are not being evaluated yet. Start — The start conditions of a phase are being evaluated, but are not yet satisfied. Run — The start conditions are satisfied and the phase is running. End — Phase execution has ended or was skipped.
ActionEventStatus	Action event dispatch status, returned as an enumeration variable. The value of the variable can be: Unspecified — Action event is not yet initialized. Dispatched — Action event has been dispatched. Interrupted — Action event has been interrupted or cancelled after dispatch. Skipped — Action event has been skipped or preempted by another conflicting action. Done — Action event is completed.

This table describes the fields of the StartConditionStatus structure:

Field Name	Description
ConditionStatusID	Start condition status identifier, returned as a string.
ConditionState	Run-time state of a start condition, returned as an enumeration variable of the EnumConditionState enumeration class. The value of EnumConditionState variable can be: Unspecified — The condition is not initialized. Not_Yet_Evaluated — The condition is initialized but has not been evaluated. Unsatisfied — The condition is evaluated but not satisfied. Satisfied — The condition is evaluated and satisfied.
ConditionType	Type of condition, returned as an enumeration variable of the EnumConditionType enumeration class. The value of EnumConditionType variable can be: duration — Run-time status of a duration condition simulation_time — Run-time status of a simulation time condition distance — Run-time status of a distance condition actor_speed — Run-time status of an actor speed condition collisions — Run-time status of a collision condition actor_lane — Run-time status of an actor lane condition and_condition — Run-time status of an and condition or_condition — Run-time status of an or condition lateral_offset — Run-time status of a lateral offset condition phase_state — Run-time status of a phase state condition event_condition — Run-time status of an event condition status
ConditionData	Data associated with a specific condition type, returned as a structure.

This table describes the fields of the EndConditionStatus structure:

Field Name	Description
ConditionStatusID	End condition status identifier, returned as a string.
ConditionState	Run-time state of an end condition, returned as an enumeration variable of the EnumConditionState enumeration class. The value of EnumConditionState variable can be: Unspecified — The condition is not initialized. Not_Yet_Evaluated — The condition is initialized but has not been evaluated. Unsatisfied — The condition is evaluated but not satisfied. Satisfied — The condition is evaluated and satisfied.
ConditionType	Type of condition, returned as an enumeration variable of the EnumConditionType enumeration class. The value of EnumConditionType variable can be: duration — Run-time status of a duration condition simulation_time — Run-time status of a simulation time condition distance — Run-time status of a distance condition actor_speed — Run-time status of an actor speed condition collisions — Run-time status of a collision condition actor_lane — Run-time status of an actor lane condition and_condition — Run-time status of an and condition or_condition — Run-time status of an or condition lateral_offset — Run-time status of a lateral offset condition phase_state — Run-time status of a phase state condition event_condition — Run-time status of an event condition status
ConditionData	Data associated with a specific condition type, returned as a structure.

TrafficSignalRuntime Structure

This table describes the fields of the TrafficSignalRuntime structure:

Field Name	Description
SignalHead	Signal head specifications, returned as a structure of type SignalHead.
SignalConfiguration	Information about the current configuration of the specified traffic signal, returned as a structure of type SignalConfiguration.

This table describes the fields of the SignalHead structure:

Field Name	Description
SignalID	UUID of traffic signal, returned first as a uint8 row vector. To convert the row vector into its alphanumeric form, use the char function, which returns the UUID as a character array.
ControllerID	UUID of traffic signal controller, returned first as a uint8 row vector. To convert the row vector into its alphanumeric form, use the char function, which returns the UUID as a character array.

This table describes the fields of the SignalConfiguration structure:

Field Name	Description
ConfigurationIndex	Current configuration index of the specified traffic signal, returned as a uint32 scalar. Configuration index indicates the overall configuration of a traffic signal. For example, if the red bulb of a traffic signal is in the "On" state, and the green and yellow bulbs are "Off", then the traffic signal is red. A certain configuration index is assigned to every such possible configuration.
NumBulbConfiguration	Number of bulb configurations for the specified signal, returned as a uint32 scalar.
BulbConfiguration	Bulb name and state for all bulbs of the specified traffic signal, returned as a structure array of type BulbConfiguration.
NumTurnConfiguration	Number of turn configurations for the specified traffic signal, returned as a uint32 scalar.
TurnConfiguration	Turn configuration information for the specified traffic signal, returned as a structure array of type TurnConfiguration.

This table describes the fields of the BulbConfiguration structure array:

Field Name	Description
BulbName	Name of the bulb, returned first as a uint8 row vector. This field corresponds to the Node Name of the bulb as seen in the RoadRunner application. To obtain a readable word, you must convert the uint8 row vector into a character array by using the char function.
BulbState	State of signal bulb, returned as an enumeration variable. Possible values of the variable are: On — The bulb is switched on. Off — The bulb is switched off. Blinking — The bulb is blinking on and off, repeatedly.

This table describes the fields of the TurnConfiguration structure array:

Field Name	Description
TimeLeft	Time remaining for the completion of the current turn type, returned as a double.
TurnType	Possible turn types: Straight — Drive straight Left — Left turn Right — Right turn UTurnLeft — Left U-turn UTurnRight — Right U-Turn Custom — Custom turn Every turn type has a corresponding configuration type (maneuver signalization); together, this information (called turn state) determines the allowed turns at a traffic signal.
ConfigurationType	Maneuver signalization at specified traffic signal, returned as an enumeration variable. The value of the variable can be: Green — Go. Corresponds to the Go always maneuver signalization. Yellow — Go slow. Corresponds to the Yield maneuver signalization. Red — Stop. Corresponds to the Stop maneuver signalization. Permitted — Stop. Then, start and yield right of way. Corresponds to the Stop/Yield maneuver signalization. Ready — Prepare to go. Custom — Custom movement. A configuration type (maneuver signalization) is assigned to every turn type; together, this information (turn state) determines the allowed turns at a traffic signal.

TrafficSignalControllerRuntime Structure

This table describes the fields of the TrafficSignalControllerRuntime structure:

Field Name	Description
ControllerID	UUID of traffic signal controller, returned first as a uint8 row vector. To convert the row vector into its alphanumeric form, use the char function, which returns the UUID as a character array.
SignalPhase	Information about current signal phase, returned as a structure of type SignalPhase.
SignalInterval	Information about the current signal phase interval, returned as a structure of type SignalInterval.
PhaseTime	Information about phase timings, returned as a structure of type PhaseTime.
CycleTime	Information about cycle timings, returned as a structure of type CycleTime. A cycle comprises of all signal phases, taken together.
ControllerStatus	Status of traffic signal controller, returned as an enumeration variable. Possible values of the variable are: Normal — Traffic signal controller is functional. Fail — Traffic signal controller has failed, and the connected traffic signal actors are inactive. Standby — Traffic signal controller is partially switched off.

This table describes the fields of the SignalPhase structure:

Field Name	Description
PhaseName	Name of the current phase, returned first as a uint8 row vector. To obtain a readable word, you must convert the uint8 row vector into a character array by using the char function.
PhaseNumber	Number assigned to current signal phase based on its order, returned as a uint32 scalar.

This table describes the fields of the SignalInterval structure:

Field Name	Description
IntervalName	Name of the current interval within a signal phase, returned first as a uint8 row vector. To obtain a readable word, you must convert the uint8 row vector into a character array by using the char function.
IntervalType	Interval type, informing about allowed turn types at a junction, returned as an enumeration variable. The value of the variable can be: Green — Green interval of a phase, where certain road maneuvers in a junction are highlighted in green signalization. Yellow — Yellow interval of a phase, where certain road maneuvers in a junction are highlighted in yellow signalization. Red — Red interval of a phase, where certain road maneuvers in a junction are highlighted in red signalization. Custom — Custom road maneuver configuration. This field corresponds to the Interval Type of a phase interval, as seen in the RoadRunner application.

This table describes the fields of the PhaseTime structure:

Field Name	Description
Duration	Total time spent in a signal phase, returned as a double.
TimeLeft	Time left in a signal phase, returned as a double.

This table describes the fields of the CycleTime structure:

Field Name	Description
Duration	Total time spent in a cycle, returned as a double.
TimeLeft	Time left in a cycle, returned as a double.

Version History

Introduced in R2022a

R2024b: Retrieve run-time attributes of traffic signal and traffic signal controller

Get run-time attributes of traffic signals and the parent traffic signal controller at a junction during cosimulation with RoadRunner Scenario.

R2024b: Retrieve actor type

Retrieve the type of an actor, such as vehicle or traffic signal.

R2024a: Retrieve information about action phases for an actor

Get information, such as phase name, phase status and condition state about all action phases associated with a particular actor.