writeFrames

R2026b

(To be removed) Write signal frames for ground truth data to disk

writeFrames will be removed in a future release. Use the groundTruthMultiSensor (Point Cloud Toolbox) object instead. For information on updating your code, see Version History.

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 groundTruthMultisignal 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 groundTruthMultisignal object. Write the signal frames associated with that label data to disk and visualize the frames.

Add the point cloud sequence folder path to the MATLAB® search path. The video is already on the MATLAB search path.

pcSeqDir = fullfile(toolboxdir('driving'),'core','drivingdata', ...
    'lidarSequence');
addpath(pcSeqDir);

Load a groundTruthMultisignal object that contains label data for the video and the lidar point cloud sequence.

data = load('MultisignalGTruth.mat');
gTruth = data.gTruth;

Warning: While loading an object of class 'groundTruthMultisignal':
Expected the number of labels to be 2 in the input SceneLabelData 

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);

Display the first eight rows of label data from the two signals. Both signals contain data for the Car label. In the video, the Car label is drawn as a rectangle bounding box. In the lidar point cloud sequence, the Car label is drawn as a cuboid bounding box.

videoLabelSample = head(labelData{1})
lidarLabelSample = head(labelData{2})

videoLabelSample =

  table

           Car       
    _________________

    {[299 213 42 33]}


lidarLabelSample =

  table

                            Car                         
    ____________________________________________________

    {[17.7444 6.7386 3.3291 3.6109 3.2214 3.5583 0 0 0]}

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 (Point Cloud Toolbox) 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

Remove the path to the point cloud sequence folder.

rmpath(pcSeqDir);

Input Arguments

gTruth — Multisignal ground truth data

groundTruthMultisignal object | vector of groundTruthMultisignal objects

Multisignal ground truth data, specified as a groundTruthMultisignal object or vector of groundTruthMultisignal 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. The signal names must be valid signal names stored in the input multisignal ground truth data, gTruth.

To obtain the signal names from a groundTruthMultisignal object, use this syntax, where gTruth is the variable name of the object:

gTruth.DataSource.SignalName

Example: 'video_01_city_c2s_fcw_10s'

Example: "video_01_city_c2s_fcw_10s"

Example: {'video_01_city_c2s_fcw_10s','lidarSequence'}

Example: ["video_01_city_c2s_fcw_10s" "lidarSequence"]

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 groundTruthMultisignal objects in gTruth.

• N is the number of signals in signalNames.

• location(m,n) (for matrix inputs) or location{m,n} (for cell array inputs) contains the frame-writing folder location for the nth signal of signalNames that is in the mth groundTruthMultisignal object of gTruth.

You can specify folder locations as relative paths or full file paths. If any specified folder locations do not exist, the writeFrames function creates the folders. All folder locations must be unique. If files already exist in a specified folder location, and the existing files are writeable, then the writeFrames function overwrites them.

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, where:

• M is the number of groundTruthMultisignal objects in gTruth.

• N is the number of signals in signalNames.

• timestamps{m,n} contains the timestamps for the nth signal of signalNames that is in the mth groundTruthMultisignal object of gTruth.

If you are writing frames for only one signal and one groundTruthMultisignal object, specify timestamps as a single duration vector.

By default, the writeFrames function writes all signal frames. When a signal does not have a frame at the specified timestamps, the function writes the frame with the nearest preceding timestamp.

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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'NamePrefix',["video" "lidar"],'FileType',["png" "ply"] writes video frames with file names of the format video_001.png, video_002.png, and so on, and writes lidar frames with file names of the format lidar_001.ply, lidar_002.ply, and so on.

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, specified as the comma-separated pair consisting of 'NamePrefix' and a character vector, string scalar, cell array of character vectors, or string vector.

Each element of 'NamePrefix' specifies the file type for the signal in the corresponding position of 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, specified as the comma-separated pair consisting of 'FileType' and a character vector, string scalar, cell array of character vectors, or string vector.

Each element of 'FileType' specifies the file type for the signal in the corresponding position of signalNames. Use this name-value pair argument to specify the file extensions in the names of the written files.

The supported file types for a signal depend on whether that signal is of type Image or PointCloud.

Signal Type	Supported File Types
Image	All file types supported by the imwrite function
PointCloud	"pcd" or "ply" Point cloud data (PCD) and polygon (PLY) files are written using binary encoding. For more details on these file formats, see the pcwrite (Point Cloud Toolbox) function.

To view the signal types for signals stored in a groundTruthMultisignal object, gTruth, use this code:

gTruth.DataSource.SignalType

Example: 'FileType','png'

Example: 'FileType',"png"

Example: 'FileType',{'png','ply'}

Example: 'FileType',["png" "ply"]

Verbose — Display writing progress information

trueor 1 (default) | false or 0

Display writing progress information at the MATLAB^® command line, specified as the comma-separated pair consisting of 'Verbose' and logical 1 (true) or 0 (false).

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, where:

• M is the number of groundTruthMultisignal objects in gTruth.

• N is the number of signals in signalNames.

• fileNames{m,n} contains the file names for the frames of the nth signal of signalNames that is in the mth groundTruthMultisignal object of gTruth.

The file names for each signal are returned in a string column vector, where each row contains the file name for a written frame. If you specified the input timestamps, then each file name represents a written frame at the timestamp in the corresponding position of timestamps.

Each output file is named NamePrefix_UID.FileType, where:

• NamePrefix is the file name prefix. To set the file name prefix, use the 'NamePrefix' name-value pair argument.

• UID is the unique integer index for each written frame. The writeFrames function generates these indices.

• FileType is the file type extension. To set the file type extension, use the 'FileType' name-value pair argument.

Version History

Introduced in R2020a

R2026b: To be removed

The writeFrames object function will be removed in a future release. Use the groundTruthMultiSensor (Point Cloud Toolbox) object and its associated object functions instead.