read

Read data from actor track data object

Since R2025a

Syntax

data = read(trackData)

data = read(trackData,Timestamps=timestamps)

data = read(trackData,RowIndices=rowIndices)

data = read(trackData,TrackIDs=trackIDs)

data = read(___,Name=Value)

Description

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

data = read(trackData) reads all data from the actor track data object trackData, and returns it as a structure, data.

data = read(trackData,Timestamps=timestamps) reads data from the trackData object for the specified timestamps timestamps.

data = read(trackData,RowIndices=rowIndices) reads data from the trackData object for the specified row indices rowIndices.

data = read(trackData,TrackIDs=trackIDs) reads data from the trackData object for the specified actor track IDs trackIDs.

data = read(___,Name=Value) specifies options using one or more name-value arguments in addition to any combination of input arguments from the previous syntaxes. For example, Format="timetable" returns the actor track data as a table of type timetable.

Examples

Read Data from Actor Track Data Object Using Track IDs

Load recorded actor track data into the workspace.

load("trackedActorData.mat")

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

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

trackData = 
  ActorTrackData with properties:

                Name: ''

          NumSamples: 600
            Duration: 29.9510
          SampleRate: 20.0327
          SampleTime: 0.0500
          Timestamps: [600×1 double]

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

          Attributes: []

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

Specify the track IDs for which to read data from the actor track data object.

trackIDs = ["22","23","24","25"];

Read the data for the specified track IDs.

data = read(trackData,TrackIDs=trackIDs)

data = struct with fields:
    Timestamps: [106×1 double]
       TrackID: {106×1 cell}
      Position: {106×1 cell}

Input Arguments

trackData — Actor track data

ActorTrackData object

Actor track data, specified as an ActorTrackData object.

rowIndices — Row indices for which to read actor track data

positive integer | M-element vector

Row indices for which to read the actor track data, specified as a positive integer or an M-element vector of positive integers. M is the number of rows of the trackData input from which to read. Values must be in the range [1, NumSamples], where NumSamples is the number of samples in the input actor track data object trackData.

Data Types: single | double | uint8 | uint16 | uint32 | uint64

timestamps — Timestamps for which to read actor track data

nonnegative scalar | M-element numeric column vector | M-element datetime array | M-element duration array

Timestamps for which to read the actor track data, specified as a nonnegative scalar, M-element numeric column vector, an M-element datetime array, or an M-element duration array. M is the number of timestamps. The data type of the timestamps value and the data type of the Timestamps property of the input actor track data object trackData must be the same. If you specify a nonnegative scalar or an N-element numeric column vector, units must be in seconds. Each element in the timestamps argument specifies the time at which the corresponding track data was collected.

The data in the output structure or time table retains the order you specify to this argument.

trackIDs — Track IDs of actors for which to read actor track data

M-element string array of valid track IDs

Track IDs of the actors for which to read actor track data, specified as an M-element string array of valid track IDs. M is the number of track IDs. The specified trackIDs must be a subset of the track IDs in the TrackID property of the input actor track data object trackData.

Data Types: string

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: data = read(trackData,Format="timetable") returns the actor track data data as a table of type timetable.

TimeOrigin — Reference time

0 (default) | nonnegative scalar | datetime scalar | duration scalar

Reference time to subtract from all timestamps, specified as a nonnegative scalar, datetime scalar, or a duration scalar. The data type of the TimeOrigin value and the data type of the Timestamps property of the input actor track data object trackData must be the same. If you specify a nonnegative scalar, units must be in seconds.

Format — Format of output actor track data

"struct" (default) | "table"

Format of the output actor track data, specified as "struct" or "table".

• "struct" — The function returns the actor track data data as a structure.

• "table" — The function returns the actor track data data as a table of type timetable.

ExpandRows — Expand tracks for timestamps with multiple actor tracks

false or 0 (default) | true or 1

Expand the tracks for the timestamps with multiple actor tracks, specified as a logical 1 (true) or 0 (false).

If specified as true, the function separates actor tracks with the same timestamp, as well as their track data such as position and orientation information, onto individual rows.

Data Types: logical

PostProcessingFcn — Postprocessing function

function handle

Postprocessing function, specified as a function handle. The specified function postprocesses the actor track data. By default, the read function does not postprocess the data from the input actor track data object trackData.

The function must support this syntax:

trackDataProcessed = postProcessingFunction(dataRead,trackDataIn)

, where the input arguments specify:

• dataRead — Actor track data read from the ActorTrackData object trackData.

• trackDataIn — Actor track data object specified as the trackData input argument to the read function, required for custom postprocessing.

The trackDataProcessed output argument returns the processed actor track data as a cell array, where each cell contains the processed data for a timestamp. The read function applies the PostProcessingFcn to each row of data corresponding to a timestamp.

TimeTol — Tolerance time

1e-6 (default) | nonnegative scalar

Tolerance time to read data, specified as a nonnegative scalar. Units are in seconds. For each element of timestamps, i, the function reads data samples with timestamps in the range [i – timeTol, i + timeTol]. Increasing the tolerance time can increase the number of samples in the output actor track data data.

Note

To use the TimeTol argument, you must specify the timestamps input argument.

Data Types: single | double

Output Arguments

data — Actor track data

structure (default) | table

Actor track data, returned as a structure or a table of type timetable. The Format name-value argument specifies the type of actor track data output.

The output data contains one or more of these fields or columns.

• Timestamps — Timestamps of the actor track data.

• TrackID — Track IDs of the actors.

• Category — Category names of the actors.

• Position — Positions of the actors in the form [x y z]. Units are in meters..

• Dimension — Dimensions of the actors in the form [length width height]. Units are in meters.

• Orientation — Orientations of the actors in the form [yaw pitch roll]. Units are in degrees.

• Velocity — Velocities of the actors in the form [vx vy vz]. Units are in meters per second.

• Speed — Speeds of the actors. Units are in meters per second.

• Age — Ages of the actor tracks.

Version History

Introduced in R2025a