writeFrames

Write signal frames for ground truth data to disk

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

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     
    ____________

    {1x4 double}


lidarLabelSample =

  table

        Car     
    ____________

    {1x9 double}

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 (Computer Vision Toolbox) 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 (Computer Vision Toolbox) object. Visualize the written lidar frames by using a pcplayer (Computer Vision 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 Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

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 (Computer Vision 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.