Main Content

pixelLabelTrainingData

Create training data for semantic segmentation from ground truth

collapse all in page

Syntax

[imds,pxds] = pixelLabelTrainingData(gTruth)
[imds,pxds] = pixelLabelTrainingData(gTruth,Name,Value)

Description

[imds,pxds] = pixelLabelTrainingData(gTruth) creates image datastore imds and pixel label datastore pxds from the specified ground truth. You can combine the returned datastores using the combine function and use the trainnet (Deep Learning Toolbox) function to train deep learning segmentation networks. You can also use these datastores with the evaluateSemanticSegmentation function to evaluate the result from deep learning or classical segmentation methods.

This function supports parallel computing using multiple MATLAB® workers. Enable parallel computing using the Computer Vision Toolbox Preferences dialog box.

example

[imds,pxds] = pixelLabelTrainingData(gTruth,Name,Value) returns image and pixel label datastores with additional options specified by one or more name-value arguments.

  • If the groundTruth objects in gTruth were created using a video file, a custom data source, or an imageDatastore with different custom read functions, then you can specify any combination of name-value pair arguments.

  • If the groundTruth objects were created from an image collection or image sequence data source, then you can specify only the SamplingFactor name-value pair argument

Examples

collapse all

Open Live Script

Load a groundTruth object named gTruth. The ground truth contains pixel labels for triangles and background, annotated on a video with 100 frames.

visiondataPath = fullfile(matlabroot, 'toolbox', 'vision', 'visiondata');
addpath(fullfile(visiondataPath, 'triangleImages'));
addpath(fullfile(visiondataPath, 'triangleImages', 'testLabels'));
loadedData = load(fullfile(visiondataPath, 'triangleImages', 'triangleGroundTruth.mat'));
gTruth = loadedData.gTruth;

Create a folder in the current directory.

foldername = fullfile(tempdir,"videoFrames");
mkdir(foldername)

Create an imageDatastore and a pixelLabelDatastore from the video file and corresponding pixel labels. Write every fifth image to disk.

[imds,pxdsTruth] = pixelLabelTrainingData(gTruth,...
    'SamplingFactor',5,'WriteLocation',foldername);
Write images extracted for training to folder: 
    /tmp/videoFrames

Writing 20 images extracted from triangleVideo.avi...Completed.

Confirm that the temporary folder contains every fifth image.

imds.Files
ans = 20×1 cell
    {'/tmp/videoFrames/triangleVideo01.png'}
    {'/tmp/videoFrames/triangleVideo06.png'}
    {'/tmp/videoFrames/triangleVideo11.png'}
    {'/tmp/videoFrames/triangleVideo16.png'}
    {'/tmp/videoFrames/triangleVideo21.png'}
    {'/tmp/videoFrames/triangleVideo26.png'}
    {'/tmp/videoFrames/triangleVideo31.png'}
    {'/tmp/videoFrames/triangleVideo36.png'}
    {'/tmp/videoFrames/triangleVideo41.png'}
    {'/tmp/videoFrames/triangleVideo46.png'}
    {'/tmp/videoFrames/triangleVideo51.png'}
    {'/tmp/videoFrames/triangleVideo56.png'}
    {'/tmp/videoFrames/triangleVideo61.png'}
    {'/tmp/videoFrames/triangleVideo66.png'}
    {'/tmp/videoFrames/triangleVideo71.png'}
    {'/tmp/videoFrames/triangleVideo76.png'}
    {'/tmp/videoFrames/triangleVideo81.png'}
    {'/tmp/videoFrames/triangleVideo86.png'}
    {'/tmp/videoFrames/triangleVideo91.png'}
    {'/tmp/videoFrames/triangleVideo96.png'}

Remove the video and images from the path.

rmpath(fullfile(visiondataPath, 'triangleImages'));
rmpath(fullfile(visiondataPath, 'triangleImages', 'testLabels'));

Input Arguments

collapse all

Ground truth data, specified as a scalar groundTruth object or an array of groundTruth objects. When gTruth is an array of groundTruth objects, the LabelDefinitions property of each object must contain the same pixel label names.

If you use custom data sources in gTruth with parallel computing enabled, then the reader function is expected to work with a pool of MATLAB workers to read images from the data source in parallel.

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: "SamplingFactor",5

Factor for subsampling images in the ground truth data source, specified an integer or a vector of integers. For a sampling factor of N, the returned training data includes every Nth image in the ground truth data source. The function ignores ground truth images with empty label data.

Use sampled data to reduce repeated data, such as a sequence of images with the same scene and labels. It can also help in reducing training time.

ValueSampling Factor
IntegerManually set the sampling factor to apply to all data.
Vector of integersWhen you input a vector of ground truth objects, the function uses the sampling factor specified by the corresponding vector element.

Image file format, specified as a string scalar or character vector. File formats must be supported by imwrite. This argument applies only for groundTruth objects created using a video file or a custom data source.

Folder name to write extracted images to, specified as a string scalar or character vector. The specified folder must exist and have write permissions.

This argument applies only for:

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 containing datastores, use the default read functions.

Image file format, specified as a string scalar or character vector. File formats must be supported by imwrite.

This argument applies only for:

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 containing datastores, use the default read functions.

Prefix for output image file names, specified as a string scalar or character vector. The image files are named as:

<name_prefix><source_number>_<image_number>.<image_format>

The default value uses the name of the data source that the images were extracted from, strcat(sourceName,"_") for video and custom data source, or "datastore" for image datastore.

This argument applies only for:

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 containing datastores, use the default read functions.

Display training progress on the MATLAB command line, specified as true or false. This argument applies only for groundTruth objects created using a video file or a custom data source.

Output Arguments

collapse all

Collection of images extracted from the ground truth, gTruth, returned as an ImageDatastore object. Each image in imds has annotations with at least one class of pixel labels. imds ignores images that with no annotations.

Collection of pixel-labeled data extracted from the ground truth, gTruth, returned as a PixelLabelDatastore object. The object contains a categorical matrix of pixel labels for each image contained in the image datastore, imds. Labels that do not correspond to pixel labels are ignored.

Version History

Introduced in R2018a

See Also

Apps

Functions

Objects

Topics