writeVideoScenes

Write video sequence to video file

Since R2021b

Syntax

filenames = writeVideoScenes(gTruth,timeRanges,folderNames)

filenames = writeVideoScenes(gTruth,timeRanges,rootFolder,folderNames)

filenames = writeVideoScenes(___,Name=Value)

Description

filenames = writeVideoScenes(gTruth,timeRanges,folderNames) writes sequences of ground truth data to separate files, filenames, that correspond to time ranges, timeRanges. Video files are written to the folders specified by the folderNames input.

The function writes video scenes using the image data and corresponding timestamp data contained in the specified groundTruth objects. All nonimage data, such as lidar, is ignored.

filenames = writeVideoScenes(gTruth,timeRanges,rootFolder,folderNames) also specifies the root folder name to prepend to each of the folder names.

filenames = writeVideoScenes(___,Name=Value) specifies options using name-value arguments, in addition to any combination of input arguments from previous syntaxes. For example, writeVideoScenes(gTruth,timeRanges,folderNames,Verbose=true) displays progress information while writing video scenes to files.

Examples

Gather Scene Label Information and Write Video Scenes to Files

Load ground truth scene label definitions and label data into the workspace.

data = load("groundTruthSceneLabels.mat");
labelDefinitions = data.labelDefinitions;
labelData = data.labelData;

Create a ground truth data source using a video file.

gSource = groundTruthDataSource("viptrain.avi");

Create a ground truth object using the ground truth data source.

gTruth = groundTruth(gSource,labelDefinitions,labelData);

Gather all the scene time ranges and the scene labels.

[timeRanges,sceneLabels] = sceneTimeRanges(gTruth);

Select a folder in the temp directory to write the video scenes to.

rootFolder = fullfile(tempdir,"videoScenes");

Use the scene label names as folder names.

folderNames = sceneLabels;

Write the video scenes to the "videoScenes" folder. Specify the subfolder names for each duration as the scene label names.

filenames = writeVideoScenes(gTruth,timeRanges,rootFolder,folderNames);

[==================================================] 100%
Elapsed time: 00:00:01
Estimated time remaining: 00:00:00

Input Arguments

gTruth — Ground truth

vector of groundTruth objects | vector of groundTruthMultisignal objects

Ground truth, specified as a vector of groundTruth objects or groundTruthMultisignal (Automated Driving Toolbox) objects.

timeRanges — Time ranges of ground truth source data

M-by-1 cell array | M-by-N cell array

Time ranges of ground truth source data, specified as an M-by-1 cell array for a groundTruth object or an M-by-N cell array for a groundTruthMultisignal object. M is the number of elements in gTruth and N represents the number of signals per element. Each cell of the array contains a T-by-2 duration matrix, where T is the number of time ranges in the corresponding element of gTruth. Each row of the matrix corresponds to a time range in the ground truth data for which a scene label has been applied, specified in the form [rangeStart rangeEnd].

folderNames — Folder names

M-1 cell array | M-by-N cell array

Folder names for the video scenes, specified as an M-by-1 cell array for a groundTruth object or an M-by-N cell array for a groundTruthMultisignal object. Each cell in the cell array corresponds to an element of gTruth, and contains a T-by-1 vector of strings or categorical vector that specifies the paths to the folders for the corresponding time ranges.

You must specify each folder name must be specified as a full path or as a relative path from the current folder. When you specify a folder name that does not exist, the function creates a new folder with the specified name. When writing video scene files, the function overwrites files with the same name that already exists in the specified folder. For example, if you call the writeVideoScenes function twice with the same input arguments, the files output by the second function call overwrite those from the first.

To select and write specific signals in a groundTruthMultisignal object to a specified location, use the selectLabelsBySignalName (Automated Driving Toolbox) function before calling the writeVideoScene function.

rootFolder — Root folder name

character vector | string scalar

Root folder name to prepend to each of the folder names, specified as a character vector or a string scalar.

Name-Value Arguments

Example: writeVideoScenes(gTruth,timeRanges,folderNames,Verbose=true) displays progress information while writing video scenes to files.

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

array of strings | cell array of character vectors

File name prefix, specified as an array of strings or a cell array of character vectors. Default values depend on the gTruth input type:

• groundTruth object — The function uses the file names (without their extension) in the DataSource property of the groundTruth object.

• groundTruthMultisignal object — The function uses the input signal names.

VideoProfile — Video profile

"Motion JPEG AVI" (default) | "Archival" | "Motion JPEG 2000" | "MPEG-4" | "Uncompressed AVI" | "Indexed AVI" | "Grayscale AVI"

Video profile for writing video scenes, specified as one of the video profiles listed in the table. The VideoProfile argument usage is the same as the profile argument of the VideoWriter object.

Value of VideoProfile	Description
"Archival"	Motion JPEG 2000 file with lossless compression
"Motion JPEG AVI"	AVI file using Motion JPEG encoding
"Motion JPEG 2000"	Motion JPEG 2000 file
'MPEG-4'	MPEG-4 file with H.264 encoding (systems with Windows® 7 or later, or macOS 10.7 and later)
'Uncompressed AVI'	Uncompressed AVI file with RGB24 video
'Indexed AVI'	Uncompressed AVI file with indexed video
'Grayscale AVI'	Uncompressed AVI file with grayscale video

Verbose — Display progress on screen

true or 1 (default) | false or 0

Display progress on screen, specified as a logical 1(true) or 0(false).

Output Arguments

filenames — Full path file names

M-by-1 cell array

Full path file names to the saved video scenes, returned as an M-by-1 cell array of T-by-1 vector of strings. M is the number of elements in the gTruth input argument. T is the number of time ranges in the corresponding element of gTruth. Each element of the vector of strings specifies the full path to the saved video scene for the corresponding time range.

The function sets the output file names as NamePrefix_UID.EXT, where UID is a unique integer index for each written scene and EXT is the video file extension determined by the VideoProfile argument.

Version History

Introduced in R2021b