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.

example

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

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

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

expand all

`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

collapse all

Read and Display Pixel Label Data

Open Live Script

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)

Figure contains an axes object. The hidden axes object contains an object of type image.

Read and Display 3-D Pixel Label Data

Open Live Script

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

pixelLabelDatastore

Description

Creation

Syntax

Description

Input Arguments

`gTruth` — Ground truth data
`groundTruth` object | array of `groundTruth` objects

`location` — Folder or image file names
character vector | cell array of character vectors | string array

`classNames` — Class names
cell array of character vectors | cell array of strings

`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

`IncludeSubfolders` — Include subfolders
`false` (default) | `true`

`FileExtensions` — File extensions
character vector | cell array of character vectors | string scalar | string array

Properties

`Files` — Files included in datastore
character vector | cell array of character vectors

`ClassNames` — Class names
cell array of character vectors

`ReadSize` — Maximum number of image files
`1` (default) | positive integer

`AlternateFileSystemRoots` — Alternate file system root paths
string vector | cell array

`ReadFcn` — Function that reads pixel labeled image data
`@readDatastoreImage` (default) | function handle

Object Functions

Examples

Read and Display Pixel Label Data

Read and Display 3-D Pixel Label Data

Tips

Version History

See Also

Apps

Functions

Objects

Topics

pixelLabelDatastore

Description

Creation

Syntax

Description

Input Arguments

gTruth — Ground truth data groundTruth object | array of groundTruth objects

location — Folder or image file names character vector | cell array of character vectors | string array

classNames — Class names cell array of character vectors | cell array of strings

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

IncludeSubfolders — Include subfolders false (default) | true

FileExtensions — File extensions character vector | cell array of character vectors | string scalar | string array

Properties

Files — Files included in datastore character vector | cell array of character vectors

ClassNames — Class names cell array of character vectors

ReadSize — Maximum number of image files 1 (default) | positive integer

AlternateFileSystemRoots — Alternate file system root paths string vector | cell array

ReadFcn — Function that reads pixel labeled image data @readDatastoreImage (default) | function handle

Object Functions

Examples

Read and Display Pixel Label Data

Read and Display 3-D Pixel Label Data

Tips

Version History

See Also

Apps

Functions

Objects

Topics

`gTruth` — Ground truth data
`groundTruth` object | array of `groundTruth` objects

`location` — Folder or image file names
character vector | cell array of character vectors | string array

`classNames` — Class names
cell array of character vectors | cell array of strings

`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

`IncludeSubfolders` — Include subfolders
`false` (default) | `true`

`FileExtensions` — File extensions
character vector | cell array of character vectors | string scalar | string array

`Files` — Files included in datastore
character vector | cell array of character vectors

`ClassNames` — Class names
cell array of character vectors

`ReadSize` — Maximum number of image files
`1` (default) | positive integer

`AlternateFileSystemRoots` — Alternate file system root paths
string vector | cell array

`ReadFcn` — Function that reads pixel labeled image data
`@readDatastoreImage` (default) | function handle