pixelLabelDatastore

Datastore for pixel label data

Description

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.

Creation

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.

Syntax

pxds = pixelLabelDatastore(gTruth)

pxds = pixelLabelDatastore(location,classNames,pixelLabelIDs)

pxds = pixelLabelDatastore(___,Name,Value)

Description

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

gTruth — Ground truth data

groundTruth object | array of groundTruth objects

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.

location — Folder or image file names

character vector | cell array of character vectors | string array

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

location	Description
character vector, string scalar	Name 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 strings	File 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

classNames — Class names

cell array of character vectors | cell array of strings

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"]

pixelLabelIDs — IDs to relate pixel labels to class names

vector | m-by-3 matrix | cell array of column vectors | cell array of m-by-3 matrices

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.

Format	Description
vector	The length of the vector must equal the number of class names. Values must be unique.
m-by-3 matrix	m 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

IncludeSubfolders — Include subfolders

false (default) | 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.

FileExtensions — File extensions

character vector | cell array of character vectors | string scalar | string array

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"]

Properties

Files — Files included in datastore

character vector | cell array of character vectors

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.

ClassNames — Class names

cell array of character vectors

This property is read-only.

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

ReadSize — Maximum number of image files

1 (default) | positive integer

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

AlternateFileSystemRoots — Alternate file system root paths

string vector | cell array

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,

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

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

    {{'Z:\datasets','/mynetwork/datasets'};...
     {'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

ReadFcn — Function that reads pixel labeled image data

@readDatastoreImage (default) | function handle

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

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

combine	Combine data from multiple datastores
countEachLabel	Count occurrence of pixel or box labels
hasdata	Determine if data is available to read from label datastore
numpartitions	Number of partitions for label datastore
partition	Partition label datastore
preview	Read first row of data in datastore
read	Read data from label datastore
readall	Read all data in label datastore
readimage	Read specified pixel label data file
reset	Reset label datastore to initial state
shuffle	Return shuffled version of label datastore
transform	Transform datastore
subset	Create subset of datastore or FileSet
isPartitionable	Determine whether datastore is partitionable
isShuffleable	Determine whether datastore is shuffleable

Examples

Read and Display Pixel Label Data

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.

categories(C{1})

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

Overlay and display the pixel label data onto the image.

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

Read and Display 3-D Pixel Label Data

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'            }
    {'nonEnhancingTumor'}
    {'enhancingTumour'  }

Visualize the result using the viewer3d and volshow functions. Display the labels by specifying the OverlayData and OverlayAlpha name-value arguments.

viewer = viewer3d(BackgroundColor="white",BackgroundGradient="off",CameraZoom=2);

h = volshow(V,Parent=viewer, ... 
    RenderingStyle="GradientOpacity", ...
    GradientOpacityValue=0.8, ... 
    Alphamap=linspace(0,0.2,256), ...
    OverlayData=L{1}, ...
    OverlayAlpha=0.8);

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});
end

Tips

• 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:

  "file1.jpg"
  "file10.jpg"
  "file11.jpg"
  "file12.jpg"
  "file2.jpg"
  "file3.jpg"
  ...
  "file9.jpg"

  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