PixelLabelDatastore - Datastore for pixel label data - MATLAB (original) (raw)

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 theread 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 thepixelLabelDatastore 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](#butueui-1-ReadSize) and [ReadFcn](#butueui-1-ReadFcn) properties.

Syntax

Description

pxds = pixelLabelDatastore([gTruth](#d126e115123)) creates a PixelLabelDatastore object from a groundTruth object or an array ofgroundTruth objects.

example

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

pxds = pixelLabelDatastore(___,[Name=Value](#namevaluepairarguments)) creates a PixelLabelDatastore object using name-value arguments to set one or both of the ReadSize orAlternateFileSystemRoots properties. For image file input, you can also use name-value pair arguments to set theReadFcn 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 containuint8 data.

pixelLabelDatastore expands the file names and stores the full file paths in the [Files](#butueui-1-Files) property.

You can use the wildcard character (*) when specifyinglocation. 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 ashdfs://_`hostname`_:_`portnumber`_/_`pathtofile`_. 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](#butueui-1-ClassNames) property.

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

IDs to map pixel labels to [ClassNames](#butueui-1-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.

Name-Value Arguments

expand all

Specify optional pairs of arguments asName1=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: pixelLabelDatastore(IncludeSubfolders=true) specifies to include all files and subfolders within each folder.

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

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

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

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

Properties

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 thelocation 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,
  ["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

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

Examples

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 = 4×1 cell {'sky' } {'grass' } {'building'} {'sidewalk'}

Overlay and display the pixel label data onto the image.

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

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

See Also

Apps

• Image Labeler | Video Labeler | Medical Image Labeler (Medical Imaging Toolbox)

Functions

• evaluateSemanticSegmentation | semanticseg

Objects

• ImageDatastore | groundTruth | semanticSegmentationMetrics | randomPatchExtractionDatastore

Topics

• 3-D Brain Tumor Segmentation Using Deep Learning
• Get Started with Semantic Segmentation Using Deep Learning
• Datastores for Deep Learning (Deep Learning Toolbox)
• Deep Learning in MATLAB (Deep Learning Toolbox)
• Training Data for Object Detection and Semantic Segmentation