actorprops

Generate actor properties from track list

Since R2022b

Syntax

actorInfo = actorprops(tracklist,egoTrajectory)

[actorInfo,writeLoc] = actorprops(tracklist,egoTrajectory)

[___] = actorprops(___,Name=Value)

Description

actorInfo = actorprops(tracklist,egoTrajectory) generates a table containing actor properties based on the input track list tracklist and ego trajectory data egoTrajectory.

[actorInfo,writeLoc] = actorprops(tracklist,egoTrajectory) returns the location on disk writeLoc where the actorprops function stores the actor trajectory information.

[___] = actorprops(___,Name=Value) specifies options using name-value arguments in addition to the arguments from the previous syntaxes. For example, AgeThreshold=2 excludes actors with age less than the specified age threshold of 2.

Note

This function requires the Scenario Builder for Automated Driving Toolbox™ support package and Sensor Fusion and Tracking Toolbox™. You can install the Scenario Builder for Automated Driving Toolbox support package from the Add-On Explorer. For more information about installing add-ons, see Get and Manage Add-Ons.

Examples

Generate Actor Properties from Non-Ego Actor Track List

Load a non-ego actor tracklist, waypoints, and time of arrival for the ego vehicle into the workspace.

data = load("recordedSensorData");

Create a waypointTrajectory object for the ego vehicle.

egoTrajectory = waypointTrajectory(data.egoWaypoints, ...
    data.egoTimeOfArrival,ReferenceFrame="ENU");

Generate and display the actor properties table.

actorInfo = actorprops(data.actorTracklistData,egoTrajectory)

actorInfo=18×13 table
    Age    TrackID    ClassID    EntryTime    ExitTime             Mesh                  Time           Waypoints           Speed              Roll             Pitch              Yaw          IsStationary
    ___    _______    _______    _________    ________    ______________________    ______________    ______________    ______________    ______________    ______________    ______________    ____________

    138       4          1       0.000383      6.8497     1×1 extendedObjectMesh    {138×1 double}    {138×3 double}    {138×1 double}    {138×1 double}    {138×1 double}    {138×1 double}       false    
    261      13          1       0.000383      13.001     1×1 extendedObjectMesh    {261×1 double}    {261×3 double}    {261×1 double}    {261×1 double}    {261×1 double}    {261×1 double}       false    
     51      22          1       0.000383      2.5007     1×1 extendedObjectMesh    { 51×1 double}    { 51×3 double}    { 51×1 double}    { 51×1 double}    { 51×1 double}    { 51×1 double}       false    
     59      23          1         1.9999      4.8997     1×1 extendedObjectMesh    { 59×1 double}    { 59×3 double}    { 59×1 double}    { 59×1 double}    { 59×1 double}    { 59×1 double}       false    
      6      24          1         3.0507      3.3003     1×1 extendedObjectMesh    {  6×1 double}    {  6×3 double}    {  6×1 double}    {  6×1 double}    {  6×1 double}    {  6×1 double}       true     
     12      25          1         4.6997      5.2497     1×1 extendedObjectMesh    { 12×1 double}    { 12×3 double}    { 12×1 double}    { 12×1 double}    { 12×1 double}    { 12×1 double}       false    
    167      26          1         5.1495      13.451     1×1 extendedObjectMesh    {167×1 double}    {167×3 double}    {167×1 double}    {167×1 double}    {167×1 double}    {167×1 double}       false    
     65      28          1         6.5994      9.7999     1×1 extendedObjectMesh    { 65×1 double}    { 65×3 double}    { 65×1 double}    { 65×1 double}    { 65×1 double}    { 65×1 double}       false    
     31      31          1         9.4507      10.951     1×1 extendedObjectMesh    { 31×1 double}    { 31×3 double}    { 31×1 double}    { 31×1 double}    { 31×1 double}    { 31×1 double}       false    
    377      32          1         11.151      29.951     1×1 extendedObjectMesh    {377×1 double}    {377×3 double}    {377×1 double}    {377×1 double}    {377×1 double}    {377×1 double}       false    
      5      33          1         12.002        12.2     1×1 extendedObjectMesh    {  5×1 double}    {  5×3 double}    {  5×1 double}    {  5×1 double}    {  5×1 double}    {  5×1 double}       true     
    240      37          1         14.049          26     1×1 extendedObjectMesh    {240×1 double}    {240×3 double}    {240×1 double}    {240×1 double}    {240×1 double}    {240×1 double}       false    
      5      38          1           14.3        14.5     1×1 extendedObjectMesh    {  5×1 double}    {  5×3 double}    {  5×1 double}    {  5×1 double}    {  5×1 double}    {  5×1 double}       true     
      5      39          1           14.5        14.7     1×1 extendedObjectMesh    {  5×1 double}    {  5×3 double}    {  5×1 double}    {  5×1 double}    {  5×1 double}    {  5×1 double}       true     
      8      40          1           26.2       26.55     1×1 extendedObjectMesh    {  8×1 double}    {  8×3 double}    {  8×1 double}    {  8×1 double}    {  8×1 double}    {  8×1 double}       false    
     16      42          1         27.101       27.85     1×1 extendedObjectMesh    { 16×1 double}    { 16×3 double}    { 16×1 double}    { 16×1 double}    { 16×1 double}    { 16×1 double}       false    
      ⋮

Extract Actor Properties with Specified Actor Age Threshold

Load a non-ego actor tracklist, waypoints, and time of arrival for the ego vehicle into the workspace.

data = load("recordedSensorData");

Create a waypointTrajectory object for the ego vehicle.

egoTrajectory = waypointTrajectory(data.egoWaypoints, ...
    data.egoTimeOfArrival,ReferenceFrame="ENU");

Generate the actor properties table without specifying an age threshold.

actorInfo1 = actorprops(data.actorTracklistData,egoTrajectory);

Generate an actor properties table with a specified age threshold.

actorInfo2 = actorprops(data.actorTracklistData,egoTrajectory, ...
    AgeThreshold=20);

Display the number of actors in each property table. The number of actors in actorInfo2 is less as compared to the number of actors in actorInfo1.

numActorsInActorInfo1 = numel(actorInfo1.TrackID)

numActorsInActorInfo1 = 
18

numActorsInActorInfo2 = numel(actorInfo2.TrackID)

numActorsInActorInfo2 = 
10

Generate Actor Properties with Smoothing Waypoints

Load a non-ego actor track list, waypoints, and time of arrival for the ego vehicle into the workspace.

data = load("recordedSensorData");

Create a waypointTrajectory object for the ego vehicle.

egoTrajectory = waypointTrajectory(data.egoWaypoints, ...
    data.egoTimeOfArrival,ReferenceFrame="ENU");

Generate the actor properties table without smoothing waypoints.

actorInfo1 = actorprops(data.actorTracklistData,egoTrajectory);

Smooth actor waypoints by using the helperSmoothFcn function and generate the actor properties table.

actorInfo2 = actorprops(data.actorTracklistData,egoTrajectory,SmoothWaypoints=@helperSmoothFcn);

Display some sample of actor waypoints without smoothing and with smoothing.

figure
plot(actorInfo1.Waypoints{10,1}(1:50,1),actorInfo1.Waypoints{10,1}(1:50,2),LineWidth=2)
hold on
plot(actorInfo2.Waypoints{10,1}(1:50,1),actorInfo2.Waypoints{10,1}(1:50,2),LineWidth=2)
hold off
legend("Waypoints Without Smoothing","Waypoints With Smoothing")
xlabel("X-axis")
ylabel("Y-axis")
title("Actor Waypoints Smoothing")

Input Arguments

tracklist — Actor track list information

ActorTrackData object | actorTracklist object | K-by-2 table

Actor track list information, specified as an ActorTrackData object, actorTracklist object, or a K-by-2 table. Each row in the table represents track information relative to its time.

The first column of the table must contain timestamps at which the track information was captured, specified as a positive scalar. Units are in seconds.

The second column of the table must contain track information of non-ego actors, specified as an M-by-1 structure. M is the number of actors. The structure must contain these fields:

Field	Description
TrackID	Track ID of the actor, specified as a numeric scalar, string scalar, or a character vector.
ClassID	Classification identifier of the actor, specified as one of these nonnegative integers: 1 — Car 2 — Truck 3 — Bicycle 4 — Pedestrian 0 — Others
Position	Position of the actor with respect to the ego frame, specified as a 3-element numeric row vector of the form [x y z]. Units are in meters.

The structure can also contain these optional fields:

Field	Description
Dimension	Dimensions of the actor, specified as a 3-element numeric row vector of the form [length width height]. Units are in meters.
Yaw	Yaw angle of the actor with respect to the ego frame, specified as a scalar. Units are in degrees.
Pitch	Pitch angle of the actor with respect to the ego frame, specified as a scalar. Units are in degrees.
Roll	Roll angle of the actor with respect to the ego frame, specified as a scalar. Units are in degrees.
Speed	Speed of the actor with respect to the ego frame, specified as a scalar. Units are in meters per second.
Velocity	Velocity of the actor with respect to the ego frame, specified as a 3-element numeric row vector of the form [vx vy vz]. Units are in meters per second.

The movements of the ego vehicle and non-ego actors must follow the vehicle coordinate system used by Automated Driving Toolbox. For more information on vehicle coordinate system, see Vehicle Coordinate System.

egoTrajectory — Ego trajectory information

waypointTrajectory object | Trajectory object

Ego trajectory information, specified as a waypointTrajectory (Sensor Fusion and Tracking Toolbox) object or Trajectory object.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: actorprops(tracklist,egoTrajectory,AgeThreshold=2) excludes actors with age less than the specified age threshold of 2.

AgeThreshold — Actor age threshold

2 (default) | positive integer

Actor age threshold, specified as a positive integer. This value is relative to the Age parameter of an actor in the output table actorInfo. The Age parameter specifies the number of times the actor has been tracked from entry time to exit time. The returned actorInfo table excludes actors with age less than the specified ageThreshold value.

SmoothWaypoints — Smooth waypoints function

[] (default) | function handle

Smooth waypoints function, specified as a function handle. The function smooths the waypoints of each actor.

The specified function must support this syntax:

waypointsOut = smoothFcn(waypointsIn)

where waypointsIn specifies the waypoints of the actors and waypointsOut is the smoothed waypoints.

SaveAs — File format in which to save actor trajectory information

"csv" (default) | "none"

File format in which to save the actor trajectory information, specified as "csv" or "none".

• csv — Save the actor trajectory information in a CSV file. You can import these CSV files into RoadRunner Scenario to create scenarios. The function stores ego trajectory information with the filename ego and stores the non-ego information with filenames that correspond to the track IDs of the respective actors. The function stores the CSV files in an actorTrajectories folder it creates on the path specified by the WriteLocation argument.

• none — The function does not save actor trajectory information.

WriteLocation — Location to which to write actor trajectory information

current working directory (default) | string scalar | character vector

Location to which to write the actor trajectory information, specified as a string scalar or character vector. The location you specify must have write permission. By default, the actorprops function stores the actor trajectory information files in the current working directory.

The function stores the actor trajectory information files in an actorTrajectories folder it creates on the path specified by the WriteLocation argument. If the actorTrajectories folder already exists on the specified path, the function creates a new folder with the suffix "_<K>" appended to the folder name, where K is a positive integer. The value of K increments based on the names of the folders already on the specified path. For example, if the actorTrajectories folder already exists, the function creates an actorTrajectories_1 folder, and if the actorTrajectories_1 folder already exists, it creates an actorTrajectories_2 folder.

Output Arguments

actorInfo — Actor trajectory information

table

Actor trajectory information, returned as a table. The trajectory parameters are in the world coordinate frame. Each row in the table represents the trajectory parameters of an actor.

The table contain these columns.

Column	Description
Age	Age of the actor, returned as a positive integer. This value specifies the number of times the actor has been tracked.
TrackID	Track ID of the actor, returned as a numeric scalar, string scalar, or a character vector.
ClassID	Actor classification identifier, returned as a nonnegative integer. Values are in the range 0 to 4.
EntryTime	Entry time of the actor, returned as a positive scalar. This value specifies the time of first detection of an actor. Units are in seconds.
ExitTime	Exit time of the actor, returned as a positive scalar. This value specifies the time of last detection of an actor. Units are in seconds.
Mesh	Mesh assigned to the actor, returned as an extendedObjectMesh object.
Time	Timestamps of actor detections, returned as an N-element column vector. N is the number of detections.
Waypoints	Waypoints of the actor center in the world frame from entry time to exit time, returned as an N-by-3 matrix. N is the number of waypoints. Units are in meters.
Speed	Speeds of the actor in the world frame from entry time to exit time, returned as an N-element column vector. Speed values are relative to the corresponding values of Waypoints. Units are in meters per second.
Roll	Roll angles of the actor in the world frame from entry time to exit time, returned as an N-element column vector. Roll values are relative to the corresponding values of Waypoints. Units are in degrees.
Pitch	Pitch angles of the actor in the world frame from entry time to exit time, returned as an N-element column vector. Pitch values are relative to the corresponding values of Waypoints. Units are in degrees.
Yaw	Yaw angles of the actor in the world frame from entry time to exit time, returned as an N-element column vector. Yaw values are relative to the corresponding values of Waypoints. Units are in degrees.
IsStationary	Actor is stationary, returned as a logical 1 (true) if the actor is stationary. Otherwise , this value is 0 (false).
Dimension	Dimensions of the actor, returned as a three-element numeric row vector of the form [length width height]. Units are in meters. Dependencies This column is optional, and appears in the table only if tracklist contains the dimension information of the actor.

writeLoc — Storage location of actor trajectory information

string scalar

Storage location of the actor trajectory information, returned as a string scalar. When you specify the SaveAs argument as "none", the function returns an empty array.

Version History

Introduced in R2022b

R2025a: Input tracklist supports ActorTrackData object

The tracklist input argument now supports the ActorTrackData object along with the previously supported actorTracklist object and a table.

R2024b_plus: Input egoTrajectory supports Trajectory object

The input egoTrajectory argument now supports the Trajectory object along with the previously supported waypointTrajectory (Sensor Fusion and Tracking Toolbox) object.

R2023a_plus: Additional name-value arguments

You can now specify these additional name-value arguments:

• SmoothWaypoints

• SaveAs

• WriteLocation

R2023a_plus: Additional output argument writeLoc

The actorprops function can now return the location on disk writeLoc where the function stores the actor trajectory information.

R2023a_plus: Output actorInfo table contains additional actor trajectory information

The output actorInfo table now includes these additional columns:

• Time

• Roll

• Pitch

• IsStationary

R2023a: Specify track list information using actorTracklist object

The actorprops function supports the actorTracklist object to specify the tracklist input. The object provides efficient data structure to store actor track list data with timestamps. You can add or remove data from the object and find track list information nearest to the specified timestamp.