writeFrames
Syntax
Description
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
= writeFrames(gTruth
,signalNames
,location
)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.
specifies the timestamps of the signal frames to write. To obtain signal timestamps, use the
fileNames
= writeFrames(gTruth
,signalNames
,location
,timestamps
)gatherLabelData
function.
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.fileNames
= writeFrames(___,Name,Value
)
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 _________________ {[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
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 ofgroundTruthMultisignal
objects ingTruth
.N
is the number of signals insignalNames
.location(m,n)
(for matrix inputs) orlocation{m,n}
(for cell array inputs) contains the frame-writing folder location for then
th signal ofsignalNames
that is in them
thgroundTruthMultisignal
object ofgTruth
.
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 ofgroundTruthMultisignal
objects ingTruth
.N
is the number of signals insignalNames
.timestamps{m,n}
contains the timestamps for then
th signal ofsignalNames
that is in them
thgroundTruthMultisignal
object ofgTruth
.
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 |
Point cloud data (PCD) and polygon
(PLY) files are written using binary encoding. For more details on these
file formats, see the |
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
true
or 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 ofgroundTruthMultisignal
objects ingTruth
.N
is the number of signals insignalNames
.fileNames{m,n}
contains the file names for the frames of then
th signal ofsignalNames
that is in them
thgroundTruthMultisignal
object ofgTruth
.
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
,
where:NamePrefix
_UID
.FileType
is the file name prefix. To set the file name prefix, use theNamePrefix
'NamePrefix'
name-value pair argument.
is the unique integer index for each written frame. TheUID
writeFrames
function generates these indices.
is the file type extension. To set the file type extension, use theFileType
'FileType'
name-value pair argument.
Version History
Introduced in R2020a
See Also
groundTruthMultisignal
| gatherLabelData
| imformats
| imwrite
| pcwrite
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)