How Labeler Apps Store Exported Pixel Labels

When you create and export pixel labels from the Image Labeler, Video Labeler, or Ground Truth Labeler (Automated Driving Toolbox) (requires Automated Driving Toolbox™) app, two sets of data are saved.

A folder named PixelLabelData, which contains the PNG files of pixel label information. These labels are encoded as indexed values.
A MAT-file containing the pixel label data, along with any other label data. This data is stored in a groundTruth object, or, if you are using the Ground Truth Labeler app, a groundTruthMultisignal (Automated Driving Toolbox) object. For pixel label data, the object also stores correspondences between image or video frames and the PNG files.

The PNG files within the PixelLabelData folder are stored as a categorical matrix. The categorical matrices contain values assigned to categories. Categorical is a data type. A categorical matrix provides efficient storage and convenient manipulation of nonnumeric data, while also maintaining meaningful names for the values. These matrices are natural representations for semantic segmentation ground truth, where each pixel is one of a predefined category of labels.

Location of Pixel Label Data Folder

The ground truth object stores the folder path and name for the pixel label data folder. The LabelData property of the groundTruth object or ROILabelData property of the groundTruthMultisignal object contains the information in the 'PixelLabelData' column. If you change the location of the pixel data file, you must also update the related information in the ground truth object. You can use the changeFilePaths function to update the information.

View Exported Pixel Label Data

The labeler apps store the semantic segmentation ground truth as lossless PNG files, with a uint8 value representing each category. The app uses the categorical function to associate the uint8 values to a category. To view your pixel data, you can either overlay the categories on images or create a datastore from the labeled images.

View Exported Pixel Label Data By Overlaying Categories on Images

Use the imread function with the categorical and labeloverlay functions. You cannot view the pixel data directly from the categorical matrix. See View Exported Pixel Label Data.

View Exported Pixel Label Data from Datastore of Labeled Images

Use the pixelLabelDatastore function to create a datastore from a set of labeled images. Use the read function to read the pixel label data. See Read and Display Pixel Label Data.

Examples

View Exported Pixel Label Data

Open Live Script

Read image and corresponding pixel label data that was exported from a labeler app.

visiondatadir = fullfile(toolboxdir('vision'),'visiondata');
 
buildingImage = imread(fullfile(visiondatadir,'building','building1.JPG'));
buildingLabels = imread(fullfile(visiondatadir,'buildingPixelLabels','Label_1.png'));

Define categories for each pixel value in buildingLabels.

labelIDs = [1,2,3,4];
labelcats = ["sky" "grass" "building" "sidewalk"];

Construct a categorical matrix using the image and the definitions.

buildingLabelCats = categorical(buildingLabels,labelIDs,labelcats);

Display the categories overlaid on the image.

figure
imshow(labeloverlay(buildingImage,buildingLabelCats))

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

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.