Main Content


Datastore for pixel label data


You can use a PixelLabelDatastore object to read pixel label data for semantic segmentation.

To read pixel label data from a PixelLabelDatastore, use the read function. This function returns a categorical array that contains a categorical label assigned to every (i,j) pixel location or (i,j,k) voxel location.


Create a PixelLabelDatastore object using the pixelLabelDatastore function described here. Once the object is created, you can use functions that access and manage the data. You can use dot notation to modify the ReadSize and ReadFcn properties.



pxds = pixelLabelDatastore(gTruth) creates a PixelLabelDatastore object from a groundTruth object or an array of groundTruth objects.

pxds = pixelLabelDatastore(location,classNames,pixelLabelIDs) creates a PixelLabelDatastore object from image files that store pixel label data, in the folder or files specified by location. The function creates the object using pixel IDs that map image pixel label values to class names.

pxds = pixelLabelDatastore(___,Name,Value) creates a PixelLabelDatastore object using name-value pair arguments to set one or both of the ReadSize or AlternateFileSystemRoots properties. For image file input, you can also use name-value pair arguments to set the ReadFcn property or to specify options about files to include in the datastore. You can specify multiple name-value pairs. Enclose each property name in quotes.

For example, pixelLabelDatastore(loc,names,ids,"ReadSize",8,"FileExtensions","png") creates a pixel label datastore that includes only PNG images and that reads eight images during each call to the read function.

Input Arguments

expand all

Ground truth data, specified as a groundTruth object or as an array of groundTruth objects. Each groundTruth object contains information about the data source, the list of label definitions, and all marked labels for a set of ground truth labels.

Folder or image file names, specified as a character vector, string array, or cell array of character vectors. Images must contain uint8 data.

character vector, string scalarName of a folder. Files within subfolders of the specified folder are not automatically included in the datastore. The datastore includes only images with supported file formats and ignores any other format. See a list of supported file formats by using the imformats function.
cell array of character vectors, array of stringsFile names of multiple images.

pixelLabelDatastore expands the file names and stores the full file paths in the Files property.

You can use the wildcard character (*) when specifying location. This character indicates that all matching files or all files in the matching folders are included in the datastore.

If the files are not in the current folder, then you must include the full or relative path.

If the files are not available locally, then the full path of the files or folders must be an internationalized resource identifier (IRI), such as hdfs://hostname:portnumber/path_to_file. For information on using a datastore with Amazon S3™ and HDFS™, see Work with Remote Data.

Example: "file1.jpg"

Example: "../dir/data/file1.png"

Example: ["C:\dir\data\file1.tif","C:\dir\data\file2.tif"]

Example: 'C:\dir\data\*.jpg'

Data Types: char | string

Class names, specified as a cell array of strings or character vectors. pixelLabelDatastore converts the names to a cell array and stores the names in the ClassNames property.

Example: ["sky" "grass" "building" "sidewalk"]

IDs to map pixel labels to ClassNames, specified as a vector, an m-by-3 matrix, a cell array of column vectors, or a cell array of m-by-3 matrices. Values must be integers in the range [0, 255]. m-by-3 matrices are only supported for RGB images.

vectorThe length of the vector must equal the number of class names. Values must be unique.
m-by-3 matrixm corresponds to the number of class names. Each row contains a 3-element vector representing the RGB pixel value to associate with each class name. Vectors must be unique. Use this format for pixel label data stored as RGB images.

cell array of column vectors

cell array of m-by-3 matrices

Use a cell array to map multiple pixel label IDs to one class name.

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: "IncludeSubfolders",true

Include subfolders, specified as false (0), or true (1). Specify true to include all files and subfolders within each folder or false to include only the files within each folder.

The IncludeSubfolders argument is not supported when you specify ground truth data gTruth.

File extensions of files to include in the datastore, specified as a character vector, cell array of character vectors, string scalar, or string array. By default, the datastore includes files with all extensions supported by the imformats function.

The FileExtensions argument is not supported when you specify ground truth data gTruth.

Example: ["png" "gif" "bmp"]


expand all

This property is read-only.

Files included in the datastore, specified as a character vector or cell array of character vectors. Each character vector is a full path to a file. When you create a PixelLabelDatastore object, use the location argument to set this property.

This property is read-only.

Class names, specified as a cell array of character vectors.

Maximum number of image files to read in each call to the read function, specified as a positive integer.

Alternate file system root paths, specified as the name-value argument consisting of "AlternateFileSystemRoots" and a string vector or a cell array. Use "AlternateFileSystemRoots" when you create a datastore on a local machine, but need to access and process the data on another machine (possibly of a different operating system). Also, when processing data using the Parallel Computing Toolbox™ and the MATLAB® Parallel Server™, and the data is stored on your local machines with a copy of the data available on different platform cloud or cluster machines, you must use "AlternateFileSystemRoots" to associate the root paths.

  • To associate a set of root paths that are equivalent to one another, specify "AlternateFileSystemRoots" as a string vector. For example,


  • To associate multiple sets of root paths that are equivalent for the datastore, specify "AlternateFileSystemRoots" as a cell array containing multiple rows where each row represents a set of equivalent root paths. Specify each row in the cell array as either a string vector or a cell array of character vectors. For example:

    • Specify "AlternateFileSystemRoots" as a cell array of string vectors.

      {["Z:\datasets", "/mynetwork/datasets"];...
       ["Y:\datasets", "/mynetwork2/datasets","S:\datasets"]}

    • Alternatively, specify "AlternateFileSystemRoots" as a cell array of cell array of character vectors.

       {'Y:\datasets', '/mynetwork2/datasets','S:\datasets'}}

The value of "AlternateFileSystemRoots" must satisfy these conditions:

  • Contains one or more rows, where each row specifies a set of equivalent root paths.

  • Each row specifies multiple root paths and each root path must contain at least two characters.

  • Root paths are unique and are not subfolders of one another.

  • Contains at least one root path entry that points to the location of the files.

For more information, see Set Up Datastore for Processing on Different Machines or Clusters.

Example: ["Z:\datasets","/mynetwork/datasets"]

Data Types: string | cell

Function that reads pixel labeled image data, specified as a function handle. The custom read function must take an image file name as input, and then output the corresponding pixel labeled data as a categorical matrix, logical matrix, or numeric matrix of data type uint8. For example, if customreader is the specified function to read the image data, then it must have a signature similar to the following:

function C = customreader(filename)
If the read function has more than one output argument, then only the first one is used. The rest are ignored.

The ReadFcn property is not supported when you specify ground truth data gTruth.

Example: @customreader

Object Functions

combineCombine data from multiple datastores
countEachLabelCount occurrence of pixel or box labels
hasdataDetermine if data is available to read from label datastore
numpartitionsNumber of partitions for label datastore
partitionPartition label datastore
previewRead first row of data in datastore
readRead data from label datastore
readallRead all data in label datastore
readimageRead specified pixel label data file
resetReset label datastore to initial state
shuffleReturn shuffled version of label datastore
transformTransform datastore
subsetCreate subset of datastore or FileSet
isPartitionableDetermine whether datastore is partitionable
isShuffleableDetermine whether datastore is shuffleable


collapse all

Overlay pixel label data on an image.

Set the location of the image and pixel label data.

dataDir = fullfile(toolboxdir('vision'),'visiondata');
imDir = fullfile(dataDir,'building');
pxDir = fullfile(dataDir,'buildingPixelLabels');

Create an image datastore.

imds = imageDatastore(imDir);

Create a pixel label datastore.

classNames = ["sky" "grass" "building" "sidewalk"];
pixelLabelID = [1 2 3 4];
pxds = pixelLabelDatastore(pxDir,classNames,pixelLabelID);

Read the image and pixel label data. read(pxds) returns a categorical matrix, C. The element C(i,j) in the matrix is the categorical label assigned to the pixel at the location l(i,j).

I = read(imds);
C = read(pxds);

Display the label categories in C.

ans = 4x1 cell
    {'sky'     }
    {'grass'   }

Overlay and display the pixel label data onto the image.

B = labeloverlay(I,C{1});

Specify the location of 3-D volume and pixel label data. This data is a labeled 3-D MRI scan of a brain.

dataDir = fullfile(toolboxdir("images"),"imdata");
imDir = fullfile(dataDir,"BrainMRILabeled","images");
pxDir = fullfile(dataDir,"BrainMRILabeled","labels");

Specify a custom read function. This example specifies a function called samplePXDSMatReader (defined at the end of the example) that read 3-D image data from MAT image files.

matReader = @samplePXDSMatReader;

Create an image datastore.

imds = imageDatastore(imDir,"FileExtensions",".mat","ReadFcn",matReader);

Create a pixel label datastore.

classNames = ["edema","nonEnhancingTumor","enhancingTumour"];
pixelLabelID = [1 2 3];
pxds = pixelLabelDatastore(pxDir,classNames,pixelLabelID,"FileExtensions",".mat","ReadFcn",matReader);

Read volume and pixel label data. L is a categorical matrix, where L(i,j,k) is the categorical label assigned to V(i,j,k).

V = read(imds);
L = read(pxds);

Display the label categories.

C = categories(L{1})
C = 3×1 cell
    {'edema'            }
    {'enhancingTumour'  }

Choose to visualize the nonEnhancingTumor label.

showLabels = strcmp(C',"nonEnhancingTumor");

Visualize the result using the viewer3d and volshow functions. Display the labels by specifying the OverlayAlphamap name-value argument.

viewer = viewer3d(BackgroundColor="white",BackgroundGradient="off",CameraZoom=1.2);
h = volshow(V,OverlayData=L{1},Parent=viewer, ... 
    RenderingStyle="GradientOpacity",GradientOpacityValue=0.8, ... 
    Alphamap=linspace(0,0.2,256),OverlayAlphamap=[0 showLabels]);

This example defines a helper function, samplePXDSMatReader, to read the 3-D image data from the image files. This function loads a MAT file and returns the first variable saved in that file.

function data = samplePXDSMatReader(filename)
    inp = load(filename);
    f = fields(inp);
    data = inp.(f{1});


  • A pixelLabelDatastore stores files in lexicographical order. For example, if you have twelve files named "file1.jpg", "file2.jpg", … , "file11.jpg", and "file12.jpg", then the files are stored in this order:


    In contrast, an imageDatastore stores files in the order they are added to the datastore. If you simultaneously read a ground truth image and pixel label data, then you may encounter a mismatch between the images and the labels. If this occurs, then rename the pixel label files so that they have the correct order. For example, rename "file1.jpg", … , "file9.jpg" to "file01.jpg", …, "file09.jpg".

  • To extract semantic segmentation data from a groundTruth object generated by the Video Labeler app, use the pixelLabelTrainingData function.

Version History

Introduced in R2017b