pixelLabelTrainingData

Create training data for semantic segmentation from ground truth

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 into a pixelLabelImageDatastore and use the trainNetwork (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.

[imds,pxds] = pixelLabelTrainingData(gTruth,Name,Value) returns image and pixel label datastores with additional options specified by one or more name-value pair 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

Prepare Data for Evaluating Semantic Segmentation Algorithm

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

gTruth — Ground truth data

scalar groundTruth object | array of groundTruth objects

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 comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'SamplingFactor',5

SamplingFactor — Factor for subsampling images

1 (default) | integer | vector of integers

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.

Value	Sampling Factor
Integer	Manually set the sampling factor to apply to all data.
Vector of integers	When you input a vector of ground truth objects, the function uses the sampling factor specified by the corresponding vector element.

ImageFormat — Image file format

PNG (default) | string scalar | character vector

Image file format, specified as the comma-separated pair consisting of 'ImageFormat' and 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.

WriteLocation — Name of folder

pwd (current working folder) (default) | string scalar | character vector

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:

• groundTruth objects created using a video file or a custom data source.

• An array of groundTruth objects created using imageDatastore with different custom read functions.

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.

ImageFormat — Image file format

PNG (default) | string scalar | character vector

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.

• An array of groundTruth objects created using imageDatastore with different custom read functions.

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.

NamePrefix — Prefix for output image file names

string scalar | character vector

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:

• groundTruth objects created using a video file or a custom data source.

• An array of groundTruth objects created using imageDatastore with custom read functions.

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.

Verbose — Display training progress

true (default) | false

Display training progress on the MATLAB command line, specified as the comma-separated pair consisting of 'Verbose' and true or false. This argument applies only for groundTruth objects created using a video file or a custom data source.

Output Arguments

imds — Collection of images

ImageDatastore object

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.

pxds — Collection of pixel-labeled data

PixelLabelDatastore object

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.