read

Read data from sensor data object

Since R2024b

Syntax

data = read(sensorDataObj)

data = read(sensorDataObj,Timestamps=timestamps)

data = read(sensorDataObj,RowIndices=rowIndices)

data = read(___,Name=Value)

Description

data = read(sensorDataObj) reads all data from the sensor data object sensorDataObj, and returns a structure, data.

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

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

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 sensor data as a table of type timetable.

Note

This function requires the Scenario Builder for Automated Driving Toolbox™ support package. 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

Read Data from GPS Data Object

Load recorded GPS data into the workspace.

load("recordedGPSData.mat")

Initialize a GPSData object using information from the loaded GPS data.

gpsData = scenariobuilder.GPSData(timestamps,latitudes,longitudes,altitudes)

gpsData = 
  GPSData with properties:

          Name: ''

    NumSamples: 392
      Duration: 19.5498
    SampleRate: 20.0513
    SampleTime: 0.0500
    Timestamps: [392×1 double]

      Latitude: [392×1 single]
     Longitude: [392×1 single]
      Altitude: [392×1 single]

    Attributes: []

Read data from the GPS data object as a structure.

dataStruct = read(gpsData)

dataStruct = struct with fields:
    Timestamps: [392×1 double]
      Latitude: [392×1 single]
     Longitude: [392×1 single]
      Altitude: [392×1 single]

Read data from the GPS data object as a table.

dataTable = read(gpsData,Format="table")

dataTable=392×4 table
    Timestamps    Latitude    Longitude    Altitude
    __________    ________    _________    ________

    1.4616e+09     45.528      -122.66      5.0743 
    1.4616e+09     45.528      -122.66      5.0659 
    1.4616e+09     45.528      -122.66      5.0713 
    1.4616e+09     45.528      -122.66      5.0761 
    1.4616e+09     45.528      -122.66      5.0841 
    1.4616e+09     45.528      -122.66      5.0806 
    1.4616e+09     45.528      -122.66      5.0763 
    1.4616e+09     45.528      -122.66      5.0864 
    1.4616e+09     45.528      -122.66      5.0975 
    1.4616e+09     45.528      -122.66      5.1087 
    1.4616e+09     45.528      -122.66      5.1071 
    1.4616e+09     45.528      -122.66       5.106 
    1.4616e+09     45.528      -122.66      5.1196 
    1.4616e+09     45.528      -122.66      5.1321 
    1.4616e+09     45.528      -122.66      5.1405 
    1.4616e+09     45.528      -122.66       5.141 
      ⋮

Read Data from GPS Data Object Using Row Indices

Load recorded GPS data into the workspace.

load("recordedGPSData.mat")

Initialize a GPSData object using information from the loaded GPS data.

gpsData = scenariobuilder.GPSData(timestamps,latitudes,longitudes,altitudes)

gpsData = 
  GPSData with properties:

          Name: ''

    NumSamples: 392
      Duration: 19.5498
    SampleRate: 20.0513
    SampleTime: 0.0500
    Timestamps: [392×1 double]

      Latitude: [392×1 single]
     Longitude: [392×1 single]
      Altitude: [392×1 single]

    Attributes: []

Specify the row indices for which to read data from the GPS data object.

rowIdx = 1:10; 

Read data for the specified row indices.

data = read(gpsData,RowIndices=rowIdx)

data = struct with fields:
    Timestamps: [10×1 double]
      Latitude: [10×1 single]
     Longitude: [10×1 single]
      Altitude: [10×1 single]

Read Data from Trajectory Object Using Timestamps

Load recorded GPS data into the workspace.

load("recordedGPSData.mat","X","Y","Z","timestamps")

Create a Trajectory object by using the loaded timestamps and xyz-coordinates from the data.

traj = scenariobuilder.Trajectory(timestamps,X,Y,Z)

traj = 
  Trajectory with properties:

               Name: ''

         NumSamples: 392
           Duration: 19.5498
         SampleRate: 20.0513
         SampleTime: 0.0500
         Timestamps: [392×1 double]

           Position: [392×3 double]
        Orientation: [392×3 double]
           Velocity: [392×3 double]
             Course: [392×1 double]
        GroundSpeed: [392×1 double]
       Acceleration: [392×3 double]
    AngularVelocity: [392×3 double]

        LocalOrigin: [0 0 0]
         TimeOrigin: 0

         Attributes: []

Specify timestamps for which to read data from the trajectory object.

timestamps = timestamps(1:100);

Read data for the specified timestamps.

data = read(traj,Timestamps=timestamps)

data = struct with fields:
         Timestamps: [100×1 double]
           Position: [100×3 double]
        Orientation: [100×3 double]
           Velocity: [100×3 double]
             Course: [100×1 double]
        GroundSpeed: [100×1 double]
       Acceleration: [100×3 double]
    AngularVelocity: [100×3 double]

Input Arguments

sensorDataObj — Sensor data

GPSData object | Trajectory object | CameraData object | LidarData object

Sensor data, specified as a GPSData object, Trajectory object, CameraData object, or a LidarData object.

rowIndices — Row indices for which to read sensor data

positive integer scalar | M-element vector

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

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

timestamps — Timestamps for which to read sensor data

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

Timestamps for which to read the sensor data, specified as a nonnegative scalar, N-element numeric column vector, an N-element datetime array, or an N-element duration array. N is the number of timestamps. The datatype of the timestamps value and the datatype of the Timestamps property of the input sensor data object sensorDataObj 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 GPS data was collected.

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

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(gpsData,Format="timetable") returns the sensor 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 sensor data object sensorDataObj must be the same. If you specify a nonnegative scalar, units must be in seconds.

Data Types: single | double

Format — Format of output sensor data

"struct" (default) | "table"

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

• "struct" — The function returns the sensor data, data, as a structure.

• "table" — The function returns the sensor data, data, as a table.

PostProcessingFcn — Postprocessing function

function handle

Postprocessing function, specified as a function handle. The function postprocesses the sensor data. By default, the function does not postprocess the data from the input sensor data object sensorDataObj.

The function must support this syntax:

sensorDataProcessed = postProcessingFunction(dataRead,sensorDataObjIn),

where the input arguments specify:

• dataRead — Sensor data read from the sensor data object sensorDataObj.

• sensorDataObjIn — Sensor data object specified as the sensorDataObj input argument to the read function, required for custom postprocessing.

The sensorDataProcessed output argument returns the processed sensor 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 samples in the output sensor data data.

Note

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

Data Types: single | double

Output Arguments

data — Sensor data

structure (default) | table

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

If the input is a GPSData object, the output data contains these fields or columns.

• Timestamps — Timestamps of the sensor data.

• Latitude — Latitude coordinates of the sensor data. Units are in degrees.

• Longitude — Longitude coordinates of the sensor data. Units are in degrees.

• Altitude — Altitude coordinates of the sensor data. Units are in meters.

If the input is a Trajectory object, the output data contains these fields or columns.

• Timestamps — Timestamps of the sensor data.

• X — Waypoint x-coordinates of the sensor data. Units are in meters.

• Y — Waypoint y-coordinates of the sensor data. Units are in meters.

• Z — Waypoint z-coordinates of the sensor data. Units are in meters.

• Velocities — Velocity at each waypoint, returned as a three-element row vector of the form [xVel yVel zVel]. Units are in meters per second.

• Course — Course angle at each waypoint, returned as a scalar. Units are in degrees.

• GroundSpeed — Ground speed at each waypoint, returned as a scalar. Units are in meters per second.

• Acceleration — Acceleration at each waypoint, returned as a three-element row vector of the form [xAcc yAcc zAcc]. Units are in m/s².

• AngularVelocity — Angular velocity at each waypoint, returned as a three-element row vector of the form [xAngVel yAngVel zAngVel]. Units are in rad/s².

If the input is a CameraData object, the output data contains these fields or columns.

• Timestamps — Timestamps of the sensor data.

• Frames — Sequence of image frames for each timestamp, specified as a cell array. Each cell is a string scalar, character vector, or a P-by-Q-by-R array. If returned as a string scalar or a character vector, it specifies an image filename or an absolute or a relative path of an image file. If returned as an array, P and Q are the height and width of the image, R is the number of color channels.

If the input is a LidarData object, the output data contains these fields or columns.

• Timestamps — Timestamps of the sensor data.

• PointClouds — Lidar point cloud for each timestamp, specified as a cell array. Each cell is a string scalar, character vector, or a pointCloud object. If returned as a string scalar or a character vector, it specifies a point cloud filename, or an absolute or a relative path of a point cloud file.

Version History

Introduced in R2024b