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 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 or a custom data source, 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')); 
load(fullfile(visiondataPath,'triangleImages','triangleGroundTruth.mat'));

Create a temporary folder.

tempf = 'C:\temp\';
mkdir(tempf)

Warning: Directory already exists.

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

[imds,pxdsTruth] = pixelLabelTrainingData(gTruth,...
    'SamplingFactor',5,'WriteLocation',tempf);

Write images extracted for training to folder: 
    C:\temp\

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

Confirm that the temporary folder contains every fifth image.

imds.Files

ans = 20×1 cell array
    {'C:\temp\triangleVideo01.png'}
    {'C:\temp\triangleVideo06.png'}
    {'C:\temp\triangleVideo11.png'}
    {'C:\temp\triangleVideo16.png'}
    {'C:\temp\triangleVideo21.png'}
    {'C:\temp\triangleVideo26.png'}
    {'C:\temp\triangleVideo31.png'}
    {'C:\temp\triangleVideo36.png'}
    {'C:\temp\triangleVideo41.png'}
    {'C:\temp\triangleVideo46.png'}
    {'C:\temp\triangleVideo51.png'}
    {'C:\temp\triangleVideo56.png'}
    {'C:\temp\triangleVideo61.png'}
    {'C:\temp\triangleVideo66.png'}
    {'C:\temp\triangleVideo71.png'}
    {'C:\temp\triangleVideo76.png'}
    {'C:\temp\triangleVideo81.png'}
    {'C:\temp\triangleVideo86.png'}
    {'C:\temp\triangleVideo91.png'}
    {'C:\temp\triangleVideo96.png'}

Remove the video and images from the path.

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

Warning: "D:\jobarchive\Bvision\2018_11_29_h16m30s59_job1011195_pass\matlab\toolbox\vision\visiondata\triangleImages\testImages" not found in path.

delete([tempf,'triangleVideo*.png'])

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 Pair 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 at which to subsample images

1 (default) | integer | vector of integers

Factor at which to subsample images in the ground truth data source, specified as the comma-separated pair consisting of 'SamplingFactor' and an integer or a vector of integers. For a sampling factor of N, the returned image datastore imds includes every Nth image in the ground truth data source. Ground truth images with empty pixel labels are ignored.

SamplingFactor	Sampling Factor Applied
Integer	All ground truth data sources in gTruth are sampled with the same sampling factor, N.
Vector of integers	The kth ground truth data source in gTruth is sampled with a sampling factor of N(k).

'WriteLocation' — Folder name

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

Folder name to which extracted images are written, specified as the comma-separated pair consisting of 'WriteLocation' and 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.

'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.

'NamePrefix' — Prefix applied to file names

string scalar | character vector

Prefix applied to file names of the output images, specified as the comma-separated pair consisting of 'NamePrefix' and a string scalar or character vector. The image files are named as:

<name_prefix><image_number>.<image_format>

The default value of NamePrefix is the name of the video file or data source containing the images. This argument applies only for groundTruth objects created using a video file or a custom data source.

'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.