ActorTrackData

Store recorded actor track data with timestamps

Since R2025a

Description

Add-On Required: This feature requires the Scenario Builder for Automated Driving Toolbox add-on.

The ActorTrackData object stores recorded actor track data and associates it with the timestamps at which it was recorded.

Creation

Syntax

trackData = scenariobuilder.ActorTrackData

trackData = scenariobuilder.ActorTrackData(timestamps,trackID,position)

trackData = scenariobuilder.ActorTrackData(timestamps,trackID,position,Name=Value)

Description

trackData = scenariobuilder.ActorTrackData creates an empty ActorTrackData object, trackdata.

trackData = scenariobuilder.ActorTrackData(timestamps,trackID,position) creates an ActorTrackData object with the Timestamps, TrackID, and Position properties set by the timestamp, trackID, and position arguments, respectively. Additionally, this syntax sets the SampleRate, SampleTime, Duration, NumSamples, and UniqueTrackIDs properties.

trackData = scenariobuilder.ActorTrackData(timestamps,trackID,position,Name=Value) sets writable properties using one or more name-value arguments. For example, Name="actorTrackData1" specifies the name of the recorded actor track data as "actorTrackData1".

Input Arguments

timestamps — Timestamps of actor track information

N-element numeric column vector | N-element datetime array | N-element duration array

Timestamps of actor track information, specified as an N-element numeric column vector, an N-element datetime array, or an N-element duration array. N is the number of timestamps. Each element in the timestamps argument specifies the time at which the corresponding actor track information was collected. If you specify an N-element numeric column vector, units must be in seconds.

When you initialize the object with timestamp, track ID, and position data, the object arranges the data by the input timestamps in increasing order.

This argument sets the Timestamps property.

trackID — Track IDs of actors

N-by-1 cell array

Track IDs of the actors, specified as an N-by-1 cell array. N is the number of timestamps. Each cell contains the track IDs of the actors detected at the corresponding timestamp, specified as an M-by-1 string array. M is the number of actors at the timestamp.

This argument sets the TrackID property.

Data Types: cell

position — Positions of actors

N-by-1 cell array

Positions of the actors with respect to the ego frame, specified as an N-by-1 cell array. N is the number of timestamps. Each cell contains the positions of the actors detected at the corresponding timestamp, specified as an M-by-3 numeric matrix. M is the number of actors at the timestamp. Each row specifies the position of an actor in the form [x y z]. Units are in meters.

This argument sets the Position property.

Data Types: cell

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: scenariobuilder.ActorTrackData(timestamps,trackID,position,Name="actorTrackData1") specifies the name of the recorded actor track data as "actorTrackData1".

Name — Name of recorded actor track data

'' (default) | string scalar | character vector

Name of the recorded actor track data, specified as a string scalar or character vector.

This argument sets the Name property.

Data Types: char | string

Category — Category names of actors

[] (default) | N-by-1 cell array

Category names of the actors, such as car, truck, bicycle, and pedestrian, specified as an N-by-1 cell array. N is the number of timestamps. Each cell contains the category names of the actors detected at the corresponding timestamp, specified as an M-by-1 string array. M is the number of actors at the timestamp.

This argument sets the Category property.

Data Types: cell

Dimension — Dimensions of actors

[] (default) | N-by-1 cell array

Dimensions of the actors, specified as an N-by-1 cell array. N is the number of timestamps. Each cell contains the dimensions of the actors detected at the corresponding timestamp, specified as an M-by-3 numeric matrix. M is the number of actors at the timestamp. Each row specifies the dimensions of an actor in the form [length width height]. Units are in meters.

This argument sets the Dimension property.

Data Types: cell

Orientation — Orientations of actors

[] (default) | N-by-1 cell array

Orientations of the actors, specified as an N-by-1 cell array. N is the number of timestamps. Each cell contains the orientations of the actors detected at the corresponding timestamp, specified as an M-by-3 numeric matrix. M is the number of actors at the timestamp. Each row specifies the orientation of an actor in the form [yaw pitch roll]. Units are in degrees.

This argument sets the Orientation property.

Data Types: cell

Speed — Speeds of actors

[] (default) | N-by-1 cell array

Speeds of the actors with respect to the ego frame, specified as an N-by-1 cell array. N is the number of timestamps. Each cell contains the speeds of the actors detected at the corresponding timestamp, specified as an M-element numeric row vector. M is the number of actors at the timestamp. Units are in meters per second.

This argument sets the Speed property.

Data Types: cell

Age — Ages of actor tracks

[] (default) | N-by-1 cell array

Ages of the actor tracks, specified as an N-by-1 cell array. The age of a track is the number of times it has been updated. N is the number of timestamps. Each cell contains the ages of the actor tracks at the corresponding timestamp, specified as an M-element row vector of positive integers. M is the number of actors at the timestamp.

This argument sets the Age property.

Data Types: cell

Velocity — Velocities of actors

[] (default) | N-by-1 cell array

Velocities of the actors with respect to the ego frame, specified as an N-by-1 cell array. N is the number of timestamps. Each cell contains the velocities of the actors detected at the corresponding timestamp, specified as an M-by-3 numeric matrix. M is the number of actors at the timestamp. Each row specifies the velocity of an actor in the form [vx vy vz]. Units are in meters per second.

This argument sets the Velocity property.

Data Types: cell

Attributes — Optional actor track attributes

[] (default) | N-by-1 array

Optional actor track attributes, specified as an N-by-1 array. N is the number of timestamps. Each element in the array contains the additional actor track attributes, such as acceleration values, recorded at the corresponding timestamp.

This argument sets the Attributes property.

Output Arguments

trackData — Actor track data

ActorTrackData object

Actor track data, returned as an ActorTrackData object.

Properties

Name — Name of recorded actor track data

'' (default) | string scalar | character vector

Name of the recorded actor track data, specified as a string scalar or character vector.

Data Types: char | string

NumSamples — Number of actor track samples

Read-only: 0 (default) | nonnegative integer

This property is read-only.

Number of actor track samples, represented as a nonnegative integer.

Data Types: uint8 | uint16 | uint32 | uint64

Duration — Time duration

Read-only: 0 (default) | nonnegative scalar

This property is read-only.

Time duration over which the actor track data was acquired, represented as a nonnegative scalar. Units are in seconds.

Data Types: double

SampleRate — Mean sample rate of actor track data

Read-only: 0 (default) | nonnegative scalar

This property is read-only.

Mean sample rate of the actor track data, represented as a nonnegative scalar. This value defines the number of actor track samples per second. Units are in hertz.

Data Types: double

SampleTime — Mean sample time of actor track data

Read-only: 0 (default) | nonnegative scalar

This property is read-only.

Mean sample time of the actor track data, represented as a nonnegative scalar. This value defines the mean time interval between two consecutive actor track samples. Units are in seconds.

Data Types: double

Timestamps — Timestamps of actor track information

[] (default) | N-element numeric column vector | N-element datetime array | N-element duration array

This property is read-only after object creation. To set this property, use the timestamps argument when calling the scenarioBuilder.ActorTrackData function.

Timestamps of the actor track information, represented as an N-element numeric column vector, an N-element datetime array, or an N-element duration array. N is the number of timestamps. Each element in the Timestamps property specifies the time at which the corresponding actor track data was collected. If you specify an N-element numeric column vector, units must be in seconds.

When you initialize the object with timestamp, track ID, and position data, the object arranges the data by the input timestamps in increasing order.

TrackID — Track IDs of actors

[] (default) | N-by-1 cell array

This property is read-only after object creation. To set this property, use the trackID argument when calling the scenarioBuilder.ActorTrackData function.

Track IDs of the actors, represented as an N-by-1 cell array. N is the number of timestamps. Each cell contains the track IDs of the actors detected at the corresponding timestamp, specified as an M-by-1 string array. M is the number of actors at the timestamp.

Data Types: cell

Category — Category names of actors

[] (default) | N-by-1 cell array

Category names of the actors, specified as an N-by-1 cell array. N is the number of timestamps. Each cell contains the category names of the actors detected at the corresponding timestamp, specified as an M-by-1 string array. M is the number of actors at the timestamp.

Data Types: cell

Position — Positions of actors

[] (default) | N-by-1 cell array

This property is read-only after object creation. To set this property, use the position argument when calling the scenarioBuilder.ActorTrackData function.

Positions of the actors with respect to the ego frame, represented as an N-by-1 cell array. N is the number of timestamps. Each cell contains the positions of the actors detected at the corresponding timestamp, specified as an M-by-3 numeric matrix. M is the number of actors at the timestamp. Each row specifies the position of an actor in the form [x y z]. Units are in meters.

Data Types: cell

Dimension — Dimensions of actors

[] (default) | N-by-1 cell array

Dimensions of the actors, specified as an N-by-1 cell array. N is the number of timestamps. Each cell contains the dimensions of the actors detected at the corresponding timestamp, specified as an M-by-3 numeric matrix. M is the number of actors at the timestamp. Each row specifies the dimensions of an actor in the form [length width height]. Units are in meters.

Data Types: cell

Orientation — Orientations of actors

[] (default) | N-by-1 cell array

Orientations of the actors, specified as an N-by-1 cell array. N is the number of timestamps. Each cell contains the orientations of the actors detected at the corresponding timestamp, specified as an M-by-3 numeric matrix. M is the number of actors at the timestamp. Each row specifies the orientation of an actor in the form [yaw pitch roll]. Units are in degrees.

Data Types: cell

Velocity — Velocities of actors

[] (default) | N-by-1 cell array

Velocities of the actors with respect to the ego frame, specified as an N-by-1 cell array. N is the number of timestamps. Each cell contains the velocities of the actors detected at the corresponding timestamp, specified as an M-by-3 numeric matrix. M is the number of actors at the timestamp. Each row specifies the velocity of an actor in the form [vx vy vz]. Units are in meters per second.

Data Types: cell

Speed — Speeds of actors

[] (default) | N-by-1 cell array

Speeds of the actors with respect to the ego frame, specified as an N-by-1 cell array. N is the number of timestamps. Each cell contains the speeds of the actors detected at the corresponding timestamp, specified as an M-element numeric row vector. M is the number of actors at the timestamp. Units are in meters per second.

Data Types: cell

Age — Ages of actor tracks

[] (default) | N-by-1 cell array

Ages of the actor tracks, specified as an N-by-1 cell array. The age of a track is the number of times it has been updated. N is the number of timestamps. Each cell contains the ages of the actor tracks at the corresponding timestamp, specified as an M-element row vector of positive integers. M is the number of actors at the timestamp.

Data Types: cell

Attributes — Optional actor track attributes

[] (default) | N-by-1 array

Optional actor track attributes, specified as an N-by-1 array. N is the number of timestamps. Each element in the array contains the additional actor track attributes, such as acceleration values, recorded at the corresponding timestamp.

UniqueTrackIDs — Unique actor track IDs

Read-only: [] (default) | P-by-1 string array

This property is read-only.

Unique actor track IDs across all timestamps, represented as a P-by-1 string array. P is the number of unique actor track IDs.

UniqueCategories — Unique category names of actors

Read-only: [] (default) | Q-by-1 string array

This property is read-only.

Unique category names of the actors across all timestamps, represented as a Q-by-1 string array. Q is the number of unique category names of the actors.

Object Functions

add	Add data to actor track data object
remove	Remove data from actor track data object
read	Read data from actor track data object
plot	Plot actor track data frame
play	Play track data from actor track data object
copy	Create copy of sensor data object
crop	Crop data from sensor data object
synchronize	Synchronize sensor data with reference sensor information
normalizeTimestamps	Normalize timestamps of sensor data object
filter	Filter track data from actor track data object
mergeTrackIDs	Merge two actor tracks using track IDs
mapTrackIDsToNumbers	Map actor track IDs to numbers
importFromObjectTrack	Import track list from objectTrack object
convertTimestamps	Convert timestamp format of sensor data object

Examples

Create Actor Track Data Object and Add Data Samples

Load recorded actor track data into the workspace.

load("trackedActorData.mat")

Initialize an ActorTrackData object using the information from the loaded actor track data.

idx = 100;
timestamps = trackedActorData.Timestamps;
trackID = trackedActorData.TrackID;
position = trackedActorData.Position;
trackData = scenariobuilder.ActorTrackData(timestamps(1:idx),trackID(1:idx),position(1:idx))

trackData = 
  ActorTrackData with properties:

                Name: ''

          NumSamples: 100
            Duration: 4.9491
          SampleRate: 20.2058
          SampleTime: 0.0500
          Timestamps: [100×1 double]

             TrackID: {100×1 cell}
            Category: []
            Position: {100×1 cell}
           Dimension: []
         Orientation: []
            Velocity: []
               Speed: []
                 Age: []

          Attributes: []

      UniqueTrackIDs: [6×1 string]
    UniqueCategories: []

Play the actor track data object.

play(trackData)

Add additional data samples to the actor track data object.

add(trackData,timestamps(idx+1:end),trackID(idx+1:end),position(idx+1:end))

Play the actor track data object, and observe the added actor tracks.

play(trackData)

Version History

Introduced in R2025a

R2025b_plus: New convertTimestamps object function

You can use the new convertTimestamps object function to convert the timestamps of a sensor data object to a different format.