This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English version of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materials including this page, select Japan from the country navigator on the bottom of this page.


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 matrix that contains a categorical label assigned to every (i,j) pixel 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)
pxds = pixelLabelDatastore(location,classNames,pixelLabelIDs)
pxds = pixelLabelDatastore(location,Name,Value)



pxds = pixelLabelDatastore(gTruth) creates a PixelLabelDatastore object from 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(location,Name,Value) creates a PixelLabelDatastore object using Name,Value pair arguments to set the ReadSize property and the IncludeSubfolders value. You can specify multiple Name,Value pair arguments. Enclose each property name in quotes.

Input Arguments

expand all

Ground truth, specified 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 or cell array of character vectors.

character vectorName 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 vectorsFile 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 Read Remote Data (MATLAB).

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 | cell

Class names, specified as a cell array of 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].

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 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 single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'IncludeSubfolders',true

expand all

Subfolder inclusion flag, specified as the comma-separated pair consisting of 'IncludeSubfolders' and 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.


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.

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

Example: @customreader

Object Functions

hasdataDetermine if data is available to read from datastore
countEachLabelCount occurrence of pixel label for data source images
numpartitionsNumber of partitions for pixel label datastore
partitionPartition a pixel label datastore
previewReads first image from pixel label datastore
readRead next consecutive file from pixel label datastore
readallRead all pixel label data
readimageRead specified pixel label data file
resetReset pixel label datastore to initial state


expand 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 and a pixel label datastore

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

Read the image and pixel label data. read(pxs) 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 = 4×1 cell array
    {'sky'     }
    {'grass'   }

Overlay and display the pixel label data onto the image.

B = labeloverlay(I,C);

Introduced in R2017b