writeFrames

Write ground truth video frames to disk

Since R2025a

collapse all in page

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.

example

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

collapse all

Open Live Script

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\ncorriel\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)

Figure contains an axes object. The hidden axes object contains an object of type image.

Input Arguments

collapse all

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

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

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

collapse all

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.

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.

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.

Run parallel computations , specified as a numeric or logical 1 (true) or 0 (false).

To run in parallel, set UseParallel to true, or enable parallel computation by default using the Computer Vision Toolbox™ preferences.

For more information, see Parallel Computing Toolbox Support.

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

collapse all

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.

Version History

Introduced in R2025a

See Also

Functions

Topics