CameraData

Store sequence of camera data with timestamps

Since R2024b

Description

The CameraData object stores a sequence of camera data.

Creation

Syntax

camData = scenariobuilder.CameraData

camData = scenariobuilder.CameraData(timestamps,frames)

camData = scenariobuilder.CameraData(video)

camData = scenariobuilder.CameraData(rosbag,topic)

camData = scenariobuilder.CameraData(___,Name=Value)

Description

camData = scenariobuilder.CameraData creates an empty CameraData object, camData.

camData = scenariobuilder.CameraData(timestamps,frames) creates a CameraData object, camData, with the Timestamps and Frames properties set by the timestamps and frames arguments, respectively. Additionally, this syntax sets the SampleRate, SampleTime, TimeDuration, and NumSamples properties.

camData = scenariobuilder.CameraData(video) creates a CameraData object, camData, containing image data extracted from the specified video video.

camData = scenariobuilder.CameraData(rosbag,topic) extracts data such as timestamps and camera data from the specified topic topic in the input rosbag file rosbag, and creates a CameraData object, camData. (since R2025b)

Note: To use a rosbag file or ROS 2 bag file, you must have a ROS Toolbox license.

camData = scenariobuilder.CameraData(___,Name=Value) sets writable properties using one or more name-value arguments. For example, Name="camera1" specifies the name of the camera sensor as "camera1".

Note

This feature 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.

Input Arguments

timestamps — Timestamps of camera data

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

Timestamps of the camera data, 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 camera data was collected. If you specify an N-element numeric column vector, units must be in seconds.

This argument sets the Timestamps property.

frames — Sequence of image frames

N-by-1 string array | N-by-1 cell array of character vectors | P-by-Q-by-R-by-N array | string scalar | ImageDatastore object

Sequence of image frames, specified as an N-by-1 string array, N-by-1 cell array of character vectors, P-by-Q-by-R-by-N array, a string scalar, or an ImageDatastore object. N is the number of timestamps.

If you specify an N-by-1 string array or an N-by-1 cell array of character vectors, each element in the array represents an image filename, an absolute or relative path of an image file.

If you specify a P-by-Q-by-R-by-N array, P and Q are the height and width of the image, R is the number of color channels, and N is the number of image frames.

If you specify a string scalar, the string must specify an absolute or relative path to a folder containing image files.

This argument sets the Frames property.

video — Video filename

string scalar | character vector

Video filename, specified as a character vector or string scalar.

You can specify video as the absolute or relative path to your file. For example, if the file myFile.mp4 is in your current folder, C:\myFolder, you can specify video as "myFile.mp4" or "C:\myFolder\myFile.mp4".

For more information, see Supported Video and Audio File Formats.

This argument sets the Frames and Timestamps properties.

Data Types: char | string

rosbag — Rosbag filename

string scalar | character vector | BagSelection object | ros2bagreader object

Since R2025b

Rosbag filename, specified as a string scalar, character vector, a BagSelection (ROS Toolbox) object, or a ros2bagreader (ROS Toolbox) object.

If you specify a string scalar or character vector, the rosbag argument must represent an absolute or relative path to a rosbag file with .bag extension, or a ROS 2 bag file with .db3 extension. For example, if the file myFile.bag is in your current folder, C:\myFolder, you can specify rosbag as "myFile.bag" or "C:\myFolder\myFile.bag".

topic — Topic name

string scalar | character vector

Since R2025b

Topic name in the input rosbag file, specified as a string scalar or character vector.

The scenariobuilder.CameraData function suggests you available topic names in the input rosbag file rosbag as tab completion for the third input argument. Alternatively, to find all topic names in the rosbag file, use the bagInfo = rosbag('info',filename) syntax of the rosbag (ROS Toolbox) function.

Data Types: char | 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: scenariobuilder.CameraData(Name="camera1") specifies the name of the camera sensor as "camera1".

Name — Name of camera sensor

'' (default) | string scalar | character vector

Name of the camera sensor, specified as a string scalar or character vector.

This argument sets the Name property.

Data Types: char | string

SensorParameters — Optional camera sensor parameters

[] (default) | camera parameters

Optional camera sensor parameters, specified as camera parameters, such as a monoCamera object.

This argument sets the SensorParameters property.

Attributes — Optional camera attributes

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

Optional camera attributes, specified as an N-by-1 array. N is the number of timestamps. Each element in the array contains the additional camera attributes, such as classification labels, detected at the corresponding timestamp.

This argument sets the Attributes property.

Properties

Name — Name of camera sensor

'' (default) | string scalar | character vector

Name of the camera sensor, specified as a string scalar or character vector.

Data Types: char | string

NumSamples — Number of image frames

Read-only: 0 (default) | nonnegative integer

This property is read-only.

Number of image frames, 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 for which the camera data was acquired, represented as a nonnegative scalar. Units are in seconds.

Data Types: double

SampleRate — Mean sample rate of camera data

Read-only: 0 (default) | nonnegative scalar

This property is read-only.

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

Data Types: double

SampleTime — Mean sample time of camera data

Read-only: 0 (default) | nonnegative scalar

This property is read-only.

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

Data Types: double

Timestamps — Timestamps of camera data

[] (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.CameraData function.

Timestamps of the camera data, 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 camera data was collected. If you specify an N-element numeric column vector, units must be in seconds.

When you initialize the object with timestamps and frames, the object arranges the data by the input timestamps in increasing order.

When you initialize the object with video, the object assigns the timestamps in the increasing order, which is linearly spaced from 0 to the duration of the video.

Frames — Sequence of image frames

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

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

Sequence of image frames, represented as an N-by-1 cell array. N is the number of timestamps. Each cell is a string scalar, character vector, or a P-by-Q-by-R array. If represented 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 represented as an array, P and Q are the height and width of the image, R is the number of color channels.

SensorParameters — Optional camera sensor parameters

[] (default) | camera parameters

Optional camera sensor parameters, specified as camera parameters, such as a monoCamera object.

Attributes — Optional camera attributes

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

Optional camera attributes, specified as an N-by-1 array. N is the number of timestamps. Each element in the array contains the additional camera attributes, such as classification labels, detected at the corresponding timestamp.

Object Functions

add	Add data to camera data object
remove	Remove data from sensor data object
read	Read data from sensor data object
copy	Create copy of sensor data object
crop	Crop data from sensor data object
synchronize	Synchronize sensor data with reference sensor information
play	Play video from camera data object
datastore	Create datastore from sensor data object
normalizeTimestamps	Normalize timestamps of sensor data object
convertTimestamps	Convert timestamp format of sensor data object

Examples

Create Camera Data Object and Add Data Samples

Specify a sequence of image filenames.

images = {'Frame01.png','Frame02.png','Frame03.png','Frame04.png','Frame05.png', ...
    'Frame06.png','Frame07.png','Frame08.png','Frame09.png','Frame10.png'}';

Specify timestamps for each image frame.

timestamps = (0.1:0.1:1)';

Create an empty camera data object.

camData = scenariobuilder.CameraData

camData = 
  CameraData with properties:

                Name: ''

          NumSamples: 0
            Duration: 0
          SampleRate: 0
          SampleTime: 0
          Timestamps: []

              Frames: []
    SensorParameters: []

          Attributes: []

Add data samples to the camera data object.

add(camData,timestamps,images)

Play the camera data object.

play(camData)

Create Camera Data Object from Video

Specify the path of a video file.

filePath = fullfile(toolboxdir("driving"),"drivingdata","udacity","drive_segment_09_29_16","centerCamera.avi");

Create a camera data object using the specified file.

camData = scenariobuilder.CameraData(filePath)

camData = 
  CameraData with properties:

                Name: ''

          NumSamples: 700
            Duration: 35
          SampleRate: 20
          SampleTime: 0.0501
          Timestamps: [700×1 double]

              Frames: {700×1 cell}
    SensorParameters: []

          Attributes: []

Play the camera data object.

play(camData)

Create Camera Data Object from Image Datastore

Create an image datastore from the images in the current working directory attached to the example as supporting files.

imageDS = imageDatastore(pwd);

Specify timestamps for each image frame.

timestamps = (0.1:0.1:1)';

Create a camera data object using the specified timestamps and image datastore.

camData = scenariobuilder.CameraData(timestamps,imageDS)

camData = 
  CameraData with properties:

                Name: ''

          NumSamples: 10
            Duration: 0.9000
          SampleRate: 11.1111
          SampleTime: 0.1000
          Timestamps: [10×1 double]

              Frames: {10×1 cell}
    SensorParameters: []

          Attributes: []

Play the camera data object.

play(camData)

Create Camera Data Object and Lidar Data Object from Rosbag File

Since R2025b

Create a camera data object and a lidar data object from a rosbag file.

Note: This example requires a ROS Toolbox license.

Download a ZIP file, DrivingData_Seg7_Seq30.zip, and then unzip the file. The file contains raw sensor data, such as GPS data, camera data, and lidar data. The rosbag file MultiSensorDrivingData_Seg7_Seq30.bag contains 100 frames of raw camera data and 60 frames of raw lidar data.

dataFolder = pwd;
dataFilename = "DrivingData_Seg7_Seq30.zip";
url = "https://ssd.mathworks.com/supportfiles/driving/data/" + dataFilename;
filePath = fullfile(dataFolder,dataFilename);
if ~isfile(filePath)
    websave(filePath,url);
end
unzip(filePath,dataFolder)
rosFilePath = fullfile(dataFolder,"DrivingData_Seg7_Seq30","MultiSensorDrivingData_Seg7_Seq30.bag");

Create a camera data object from the rosbag file.

camData = scenariobuilder.CameraData(rosFilePath,"/flir_adk_out/camera_21355709/image_raw")

camData = 
  CameraData with properties:

                Name: ''

          NumSamples: 100
            Duration: 14.5894
          SampleRate: 6.8543
          SampleTime: 0.1474
          Timestamps: [100×1 double]

              Frames: [100×1 string]
    SensorParameters: []

          Attributes: []

Visualize the camera data object.

play(camData)

Create a lidar data object from the rosbag file.

lidarData = scenariobuilder.LidarData(rosFilePath,"/os1_cloud_node/points")

lidarData = 
  LidarData with properties:

                Name: ''

          NumSamples: 60
            Duration: 14.7427
          SampleRate: 4.0698
          SampleTime: 0.2499
          Timestamps: [60×1 double]

         PointClouds: [60×1 string]
    SensorParameters: []

          Attributes: []

Visualize the lidar data object.

play(lidarData)

Version History

Introduced in R2024b

R2025b_plus: Create camera data object from rosbag

You can now specify these input arguments to create a camera data object from a rosbag file.

• rosbag

• topic

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.