writeFrames

R2026b

Write signal frames for multi-sensor ground truth data to disk

Since R2026b

Syntax

fileNames = writeFrames(gTruth,signalNames,location)

fileNames = writeFrames(gTruth,signalNames,location,timestamps)

fileNames = writeFrames(___,Name,Value)

Description

fileNames = writeFrames(gTruth,signalNames,location) writes the frames of ground truth signal sources to the specified folder locations. The function returns the names of the files containing the written frames. fileNames contains one file name per signal specified by signalNames per groundTruthMultiSensor object specified by gTruth.

Use these written frames and the associated ground truth labels obtained from the gatherLabelData function as training data for machine learning or deep learning models.

fileNames = writeFrames(gTruth,signalNames,location,timestamps) specifies the timestamps of the signal frames to write. To obtain signal timestamps, use the gatherLabelData function.

fileNames = writeFrames(___,Name,Value) specifies options using one or more name-value pair arguments, in addition to any of the input argument combinations from previous syntaxes. For example, you can specify the prefix and file type extension of the file names for the written frames.

Examples

Gather Label Data and Write Associated Signal Frames

Gather label data for a video signal and a lidar point cloud sequence signal from a groundTruthMultiSensor object. Write the signal frames associated with that label data to disk and visualize the frames.

This example assumes you have a groundTruthMultiSensor object, gTruth, in the workspace that contains label data for a video and a lidar point cloud sequence.

Specify the signals from which to gather label data.

signalNames = ["video_01_city_c2s_fcw_10s" "lidarSequence"];

The video contains rectangle labels, whereas the lidar point cloud sequence contains cuboid labels. Gather the rectangle labels from the video and the cuboid labels from the lidar point cloud sequence.

labelTypes = [labelType.Rectangle labelType.Cuboid];
[labelData,timestamps] = gatherLabelData(gTruth,signalNames,labelTypes);

Write signal frames associated with the gathered label data to temporary folder locations, with one folder per signal. Use the timestamps returned by the gatherLabelData function to indicate which signal frames to write.

outputFolder = fullfile(tempdir,["videoFrames" "lidarFrames"]);
fileNames = writeFrames(gTruth,signalNames,outputFolder,timestamps);

Writing 2 frames from the following signals:

* video_01_city_c2s_fcw_10s
* lidarSequence

Load the written video signal frames by using an imageDatastore object. Load the associated rectangle label data by using a boxLabelDatastore object.

imds = imageDatastore(fileNames{1});
blds = boxLabelDatastore(labelData{1});

Load the written lidar signal frames by using a fileDatastore object. Load the associated cuboid label data by using a boxLabelDatastore object.

fds = fileDatastore(fileNames{2},ReadFcn=@pcread);
clds = boxLabelDatastore(labelData{2});

Visualize the written video frames by using a vision.VideoPlayer object. Visualize the written lidar frames by using a pcplayer object.

videoPlayer = vision.VideoPlayer;

ptCloud = preview(fds);
ptCloudPlayer = pcplayer(ptCloud.XLimits,ptCloud.YLimits,ptCloud.ZLimits);

while hasdata(imds)
    % Read video and lidar frames.
    I = read(imds);
    ptCloud = read(fds);

    % Visualize video and lidar frames.
    videoPlayer(I);
    view(ptCloudPlayer,ptCloud);
end

Input Arguments

gTruth — Multi-sensor ground truth data

groundTruthMultiSensor object | vector of groundTruthMultiSensor objects

Multi-sensor ground truth data, specified as a groundTruthMultiSensor object or vector of groundTruthMultiSensor objects.

signalNames — Names of signals

character vector | cell array of character vectors | string scalar | string vector

Names of the signals for which to write frames, specified as a character vector, string scalar, cell array of character vectors, or string vector.

location — Folder locations

matrix of strings | cell array of character vectors

Folder locations to which to write frames, specified as an M-by-N matrix of strings or an M-by-N cell array of character vectors, where M is the number of groundTruthMultiSensor objects in gTruth and N is the number of signals in signalNames.

timestamps — Timestamps of frames to write

duration vector | cell array of duration vectors

Timestamps of the frames to write, specified as a duration vector or an M-by-N cell array of duration vectors.

Name-Value Arguments

Example: writeFrames(gTruth,signalNames,outputFolder,timestamps,Verbose=true)

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.

NamePrefix — File name prefix for each signal

character vector | string scalar | cell array of character vectors | string vector

File name prefix for each signal in signalNames. By default, 'NamePrefix' is the name of each signal in signalNames.

FileType — File type for each signal

"jpg" for Image signals, "pcd" for PointCloud signals (default) | character vector | string scalar | cell array of character vectors | string vector

File type for each signal in signalNames. For Image signals, all file types supported by imwrite are valid. For PointCloud signals, valid types are "pcd" and "ply".

Verbose — Display writing progress information

true or 1 (default) | false or 0

Display writing progress information at the command line.

Output Arguments

fileNames — File names of written frames

cell array of string column vectors

File names of the written frames, returned as an M-by-N cell array of string vectors.

Version History

Introduced in R2026b