writeFrames

R2026b

Write ground truth video frames to disk

Since R2025a

Syntax

files = writeFrames(gTruth,location)

files = writeFrames(gTruth,location,timestamps)

files = writeFrames(___,Name=Value)

Description

files = writeFrames(gTruth,location) writes all video frames from one or more ground truth objects gTruth to the folder specified by location. The function returns the paths to the output video frames files.

files = writeFrames(gTruth,location,timestamps) writes video frames with the specified timestamps to disk.

files = writeFrames(___,Name=Value) specifies options using one or more name-value arguments in addition to any combination of input arguments from previous syntaxes. For example, ImageFormat="jpg" sets the returned video frames to the JPEG format.

Examples

Write Video Frames from Ground Truth Object

Load a ground truth object that contains rectangle labels for a video into the workspace.

data = load("peopleWalkingGroundtruth.mat");
gTruth = data.peopleWalking;

Gather rectangle labels from the video.

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

Write the image frames associated with the gathered label data to a temporary folder location. Use the timestamps returned by the gatherLabelData function to indicate which video frames to write.

outputFolder = fullfile(tempdir,"videoFrames");
fileNames = writeFrames(gTruth,outputFolder,timestamps);

Write images extracted for training to folder: 
    C:\Users\user\AppData\Local\Temp\videoFrames

Writing 600 images extracted from atrium.mp4...Completed.

Create an image datastore of the written video image frames, and a box label datastore of the corresponding rectangle label data.

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

Combine the datastores using the combine function.

ds = combine(imds,blds);

Visualize the written video image frames using the montage function.

frameData = {};
while hasdata(ds)
    data = read(ds);
    % Only visualize frames with box data.
    if ~isempty(data{2})
        frameData{end + 1} = insertObjectAnnotation(data{1},"Rectangle",data{2},data{3});
    end
end

figure
montage(frameData,BorderSize=3)

Input Arguments

gTruth — Ground truth labels

groundTruth object | array of groundTruth objects

Ground truth labels, specified as a groundTruth object or as an array of groundTruth objects.

location — Destination folder

string scalar | character vector

Destination folder to which to write the video frames, specified as a string scalar or character vector.

timestamps — Timestamps

cell array of duration vectors

Timestamps, specified as an M-by-1 cell array of duration vectors, where M is the number of groundTruth objects in gTruth. To use this argument, you must specify an input ground truth object that contains duration-based data. If the input ground truth object does not have duration-based data, the function ignores the timestamps argument and writes all image data from the ground truth object.

Name-Value Arguments

Example: writeFrames(gTruth,location,ImageFormat="jpg") sets the returned video frames to the JPEG format.

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.

ImageFormat — Image format

character vector | string scalar

Image format, specified as a character vector or string scalar. This value specifies the image format for the returned video frames files. You must specify a file format supported by imwrite.

NamePrefix — Prefix for output filenames

string scalar | character vector

Prefix for output filenames, specified as a string scalar or character vector. The output image files use this naming convention::

NamePrefix_source_number_image_number.ImageFormat, where,

• NamePrefix is the filename prefix, specified by the NamePrefix name-value argument.

• source_number corresponds to the ground truth object. For example, if the input gTruth is an array of three ground truth objects, the function outputs files with three different source_number values, 1, 2, and 3, corresponding to the index of each ground truth object in the array.

• image_number is the image or video frame number.

The default value NamePrefix depends on the source of the data.

• Video or custom data source — NamePrefix uses the name of the data source, sourceName.

• Image datastore — NamePrefix uses the value "datastore".

The function ignores this argument when:

• The input groundTruth object was created from an image sequence data source.

• The array of input groundTruth objects all contain image datastores using the same custom read function.

• Any of the input groundTruth objects contain datastores and use the default read functions.

UseParallel — Option to perform computations in parallel

"off" (default) | "auto" | "on"

Option to perform computations in parallel using a parallel pool of workers, specified as one of these values:

• "off" — Run in serial on the MATLAB client.

• "auto" — Use a parallel pool if one is open or if MATLAB can automatically create one. If a parallel pool is not available, run in serial on the MATLAB client.

• "on" — Use a parallel pool if one is open or if MATLAB can automatically create one. If a parallel pool is not available, throw an error.

If you do not have a parallel pool open and automatic pool creation is enabled, MATLAB opens a pool using the default cluster profile. Using parallel computing requires Parallel Computing Toolbox™. For more information, see Run MATLAB Functions with Automatic Parallel Support (Parallel Computing Toolbox).

Dependencies

To enable parallel processing, change the default cluster profile to use a local cluster.

Data Types: char | string

Verbose — Flag to display training progress

true or 1 (default) | false or 0

Flag to display training progress at the MATLAB^® command line, specified as a numeric or logical 1 (true) or 0 (false). This argument applies only for groundTruth objects created using a video file or a custom data source.

Output Arguments

files — File paths of written frames

M-by-1 cell array

File paths of written frames, returned as an M-by-1 cell array. M is the number of ground truth objects. Each cell contains an N-element vector of strings, where N is the number of image frames written to the specified folder. Each string specifies the full path of an output file. The output files use this naming convention:

NamePrefix_source_number_image_number.ImageFormat, where,

• NamePrefix is the filename prefix, specified by the NamePrefix name-value argument.

• source_number corresponds to the ground truth object. For example, if the input gTruth is an array of three ground truth objects, the function outputs files with three different source_number values, 1, 2, and 3, corresponding to the index of each ground truth object in the array.

• image_number is the image or video frame number.

Extended Capabilities

Automatic Parallel Support

Accelerate code by automatically running computation in parallel using Parallel Computing Toolbox™.

writeFrames has automatic parallel support.

To run computations in parallel, set the UseParallel argument to "on" or "auto".

For more information, see Run MATLAB Functions with Automatic Parallel Support (Parallel Computing Toolbox).

Version History

Introduced in R2025a

R2026b: Updated UseParallel argument syntax

The UseParallel argument for the writeFrames function now accepts "off", "auto", or "on" instead of logical true or false values. Using logical values is not recommended.