Main Content


(To be removed) Create datastore for semantic segmentation networks

pixelLabelImageSource will be removed in a future release. Create a datastore for semantic segmentation networks by using the imageDatastore and pixelLabelDatastore objects and the combine function instead. For more information, see Compatibility Considerations.



pximds = pixelLabelImageSource(gTruth) returns a pixel label image datastore for training a semantic segmentation network based on the input array of groundTruth objects. Use the output pixelLabelImageDatastore object with the trainnet (Deep Learning Toolbox) function to train convolutional neural networks for semantic segmentation.

pximds = pixelLabelImageSource(imds,pxds) returns a pixel label image datastore based on the input image datastore and the pixel label datastore objects. imds is an ImageDatastore object that represents the training input to the network. pxds is a PixelLabelDatastore object that represents the required network output.

pximds = pixelLabelImageSource(___,Name,Value) sets properties of the returned pixel label image datastore using name-value pairs. You can specify multiple name-value pairs. Enclose each argument name in quotes.


Augment Data While Training Using PixelLabelImageSource

Configure a pixel label image datastore to augment data while training. This example uses the pixelLabelImageSource function to create a pixel label image datastore object.

Load training images and pixel labels.

dataSetDir = fullfile(toolboxdir('vision'),'visiondata','triangleImages');
imageDir = fullfile(dataSetDir,'trainingImages');
labelDir = fullfile(dataSetDir,'trainingLabels');

Create an imageDatastore object to hold the training images.

imds = imageDatastore(imageDir);

Define the class names and their associated label IDs.

classNames = ["triangle","background"];
labelIDs   = [255 0];

Create a pixelLabelDatastore object to hold the ground truth pixel labels for the training images.

pxds = pixelLabelDatastore(labelDir, classNames, labelIDs);

Create an imageDataAugmenter object to randomly rotate and mirror image data.

augmenter = imageDataAugmenter('RandRotation',[-10 10],'RandXReflection',true)
augmenter = 
  imageDataAugmenter with properties:

           FillValue: 0
     RandXReflection: 1
     RandYReflection: 0
        RandRotation: [-10 10]
           RandScale: [1 1]
          RandXScale: [1 1]
          RandYScale: [1 1]
          RandXShear: [0 0]
          RandYShear: [0 0]
    RandXTranslation: [0 0]
    RandYTranslation: [0 0]

Use the pixelLabelImageSource function to create a pixelLabelImageDatastore object that can be used to train the network with augmented data.

plimds = pixelLabelImageSource(imds,pxds,'DataAugmentation',augmenter)
plimds = 
  pixelLabelImageDatastore with properties:

                  Images: {200x1 cell}
          PixelLabelData: {200x1 cell}
              ClassNames: {2x1 cell}
        DataAugmentation: [1x1 imageDataAugmenter]
      ColorPreprocessing: 'none'
              OutputSize: []
          OutputSizeMode: 'resize'
           MiniBatchSize: 1
         NumObservations: 200
    DispatchInBackground: 0

Input Arguments

collapse all

Ground truth data, specified as a groundTruth object. You can use the Image Labeler to create a groundTruth object for training a semantic segmentation network.

Collection of images, specified as an ImageDatastore object.

Collection of pixel labeled images, specified as a PixelLabelDatastore object. The object contains the pixel labeled images for each image contained in the imds input object.

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: 'ColorProcessing','rgb2gray'

Image data augmentation, specified as 'none' or an imageDataAugmenter object. This argument sets the DataAugmentation property of the returned pixel label image datastore, pximds.

Color channel preprocessing, specified as 'none', 'gray2rgb', or 'rgb2gray'. This argument sets the ColorPreprocessing property of the returned pixel label image datastore, pximds. Use this property when you need the image data created by the data source must be only color or grayscale, but the training set includes both. Suppose you need to train a network that expects color images but some of your training images are grayscale. Set ColorPreprocessing to 'gray2rgb' to replicate the color channels of the grayscale images in the input image set. Using the 'gray2rgb' option creates M-by-N-by-3 output images.

Size of images produced by data source, specified as a 2-element vector indicating the number of rows and columns. This argument sets the OutputSize property of the returned pixel label image datastore, pximds. When you specify the OutputSize, image sizes are adjusted as necessary. By default, this property is empty, which means that the images are not adjusted.

Technique used to adjust image sizes, specified as 'false', 'resize', 'centercrop', or 'randcrop'. This argument sets the OutputSizeMode property of the returned pixel label image datastore, pximds. This property applies only when you set OutputSize to a value other than [].

Preprocess images in parallel, specified as false or true. This argument sets the DispatchInBackground property of the returned pixel label image datastore object, pximds. If BackgroundExecution is true and you have Parallel Computing Toolbox™, then the pixel label image datastore asynchronously reads, augments, and queues pixel labeled images for use in training.

Output Arguments

collapse all

Pixel label image datastore, returned as a pixelLabelImageDatastore object.

Version History

Introduced in R2017b

expand all

R2018a: pixelLabelImageSource object is removed

In R2017b, you could create a pixelLabelImageSource object for training semantic segmentation networks. Starting in R2018a, the pixelLabelImageSource object has been removed. Use a pixelLabelImageDatastore object instead.

A pixelLabelImageDatastore has additional properties and methods to assist with data preprocessing. Unlike pixelLabelImageSource, which could be used for training only, you can use a pixelLabelImageDatastore for both training and prediction.

To create a pixelLabelImageDatastore object, you can use either the pixelLabelImageDatastore function (recommended) or the pixelLabelImageSource function.