groundTruth

Object for storing ground truth labels

Description

The groundTruth object contains information about the data source, the list of label definitions, and all marked labels for a set of ground truth labels. You can export or import a groundTruth object from the Image Labeler, Video Labeler, and Ground Truth Labeler apps. Use of the Ground Truth Labeler requires Automated Driving Toolbox™.

• To create training data for an object detector from arrays of groundTruth objects, use the objectDetectorTrainingData function.

• To create training data for a semantic segmentation network from arrays of groundTruth objects, use the pixelLabelTrainingData function.

Creation

Syntax

gTruth = groundTruth(dataSource,labelDefs,labelData)

Description

gTruth = groundTruth(dataSource,labelDefs,labelData) returns an object containing ground truth labels that can be imported into the Image Labeler, Video Labeler, and Ground Truth Labeler apps. The dataSource, labelDefinitions, and labelData inputs set the properties. Label definitions describe the labels, sublabels, and attributes. Label data contains the identifying information, position, and timestamps for the labels.

Properties

DataSource — Source of ground truth data

groundTruthDataSource object

Source of ground truth data, specified as a groundTruthDataSource object. The object contains information that describes the video, image sequence, or custom data source from which ground truth data was labeled.

To access images from the original data source, use VideoReader or imageDatastore. You can also use a custom reader function. See Use Custom Data Source Reader for Ground Truth Labeling.

LabelDefinitions — Label definitions

table

This property is read-only.

Label definitions, specified as a table with up to five columns. The possible columns are Name, Type, PixelLabelID, Description, and Hierarchy.

The table includes the PixelLabelID column when you use pixel labels and includes the Hierarchy column when you create sublabels and/or attributes. The table always contains the Name, Type, and Description columns. Descriptions for labels are optional, so that column can be empty.

Label Definition	Description
Name	Character vector specifying the name of the label category.
Type	labelType enumeration that specifies the label category type.
PixelLabelID	A scalar, column vector, or an M-by-3 matrix of integer-valued label IDs. PixelLabelID specifies the pixel label values used to represent a label category. This value is required when you set Type to labelType.PixelLabel. Pixel label ID values must be between 0 and 255.
Description	Character vector that describes the label category. The description label definition is optional.
Hierarchy	A structure containing sublabel and attribute data. The app populates the hierarchy column when you create a sublabel or attribute. This label definition applies only to the Video Labeler and Ground Truth Labeler apps. See Get Started with the Video Labeler and Get Started with the Ground Truth Labeler (Automated Driving Toolbox).

For example, this definition table contains six label categories: cars, sky, vegetation, road, Signs, and laneMarkers.

Note

Attributes and sublabels are only available in the Video Labeler and Ground Truth Labeler. In the example above, two of the labels contain attributes. Therefore, a Hierarchy column was created for all labels.

The following code below represents a table with two label categories:

defs = table({'Cars';'Lanes'}, ...
	[labelType.Rectangle;labelType.Line], ...
	'VariableNames',{'Name','Type'})

LabelData — Label data for each ROI and scene label

table | timetable

This property is read-only.

Label data for each ROI and scene label, specified as a table for image collections or a timetable for videos or image sequence. Each column of the table or timetable holds labels for a single label category. LabelData describes the elements of the table. The label categories are specified as labelType enumerations.

Label Category	Label Values
labelType.Rectangle	Labels in each row are stored as M-by-4 matrices of [x,y,width,height] bounding box locations. If the labels contain sublabels, attributes, or both, then the labels are stored as structures. These structures contain the bounding box locations and the sublabel and attribute information.
labelType.Line	Labels in each row are stored as M-by-1 cell arrays. Each element of the cell array holds [x,y] locations for the points used to mark the polyline. If the labels contain sublabels, attributes, or both, then the labels are stored as structures. These structures contain the line locations and the sublabel and attribute information.
labelType.PixelLabel	Label data for all label categories is represented by a single label matrix. The matrix must be stored on disk as a uint8 image. The image file name must be specified as a character vector in the LabelData table. The label matrix must contain 1 or 3 channels. For a 3-channel matrix, the RGB pixel values represent label IDs.
labelType.Scene	Labels in each row are stored as logical values representing the presence or absence of the scene label for the image.
labelType.Custom	Labels in each row are stored in the way they are provided in the table. These labels are not imported into the labeling app.

Supported GroundTruth Objects

	Video Labeler or Ground Truth Labeler App	Image Labeler App
Data source	Video file, image sequence folder, custom reader	Image files
Label definitions	Rectangle, Line, PixelLabel, or Scene label types	Rectangle, PixelLabel or Scene label types
Label data	Timetable of Rectangle, Line, PixelLabel, or Scene label types	Table (no timetable) for Rectangle, PixelLabel, or Scene label types

To add ground truth data that is not an ROI (Rectangle, Line, PixelLabel) or Scene label category to a groundTruth object, provide a label definition with a labelType that is Custom. The custom data is not visible when you load it into the labeling app.

Object Functions

selectLabelsByGroup	Select ground truth data for set of labels by group
selectLabelsByType	Select ground truth data for a set of labels by type
selectLabelsByName	Select ground truth data by name
changeFilePaths	Change file paths in data source and pixel label data of ground truth object

Examples

Create Ground Truth for Stop Signs and Cars

Create a data source from a collection of images.

data = load('stopSignsAndCars.mat');
imageFilenames = data.stopSignsAndCars.imageFilename(1:2)

imageFilenames = 2x1 cell array
    {'stopSignImages/image001.jpg'}
    {'stopSignImages/image002.jpg'}

imageFilenames = fullfile(toolboxdir('vision'),'visiondata',imageFilenames);
dataSource = groundTruthDataSource(imageFilenames);

Define labels used to specify the ground truth. Use labelDefinitionCreator to create the label definitions table.

ldc = labelDefinitionCreator();
addLabel(ldc,'stopSign',labelType.Rectangle);
addLabel(ldc,'carRear',labelType.Rectangle);
labelDefs = create(ldc)

labelDefs=2×4 table
       Name         Type       Group     Description
    __________    _________    ______    ___________

    'stopSign'    Rectangle    'None'        ' '    
    'carRear'     Rectangle    'None'        ' '    

Initialize label data for rectangle ROIs.

stopSignTruth = {[856   318    39    41];[445   523    52    54]};
carRearTruth = {[398   378   315   210];[332   633   691   287]};

Construct a table of label data.

labelNames = {'stopSign';'carRear'};
labelData = table(stopSignTruth,carRearTruth,'VariableNames',labelNames)

labelData=2×2 table
      stopSign        carRear   
    ____________    ____________

    [1x4 double]    [1x4 double]
    [1x4 double]    [1x4 double]

Create a ground truth object.

gTruth = groundTruth(dataSource,labelDefs,labelData)

gTruth = 
  groundTruth with properties:

          DataSource: [1x1 groundTruthDataSource]
    LabelDefinitions: [2x4 table]
           LabelData: [2x2 table]

Create Ground Truth Data of Road Lanes

Create a groundTruth object to store data representing marked road lanes.

Create a data source from an image.

dataSource = groundTruthDataSource({'stopSignTest.jpg'});

Define labels used to specify ground truth. Use labelDefinitionCreator to create label definitions table.

ldc = labelDefinitionCreator();
addLabel(ldc,'Lane',labelType.Line);
labelDefs = create(ldc);

Assign two lane markers in the image.

laneMarkerTruth = {[257 254;311 180] [327 183;338 205;374 250]};

Construct a table of label data.

labelNames = {'Lane'};
labelData = table(laneMarkerTruth,'VariableNames',labelNames)

labelData=1×1 table
                Lane            
    ____________________________

    [2x2 double]    [3x2 double]

Create a groundTruth object.

gTruth = groundTruth(dataSource,labelDefs,labelData)

gTruth = 
  groundTruth with properties:

          DataSource: [1x1 groundTruthDataSource]
    LabelDefinitions: [1x4 table]
           LabelData: [1x1 table]

Create Ground Truth Data For Pixel Labels

Create a groundTruth object to store data representing parts of a scene.

Create a data source.

dataSource = groundTruthDataSource({'visionteam.jpg'});

Use labelDefinitionCreator to create the label definitions table. Define labels, 'Person' and 'Background'. Assign their corresponding label type as PixelLabel.

ldc =labelDefinitionCreator();
addLabel(ldc,'Person',labelType.PixelLabel);
addLabel(ldc,'Background',labelType.PixelLabel);
labelDefs = create(ldc)             

labelDefs=2×5 table
        Name           Type       PixelLabelID    Group     Description
    ____________    __________    ____________    ______    ___________

    'Person'        PixelLabel        [1]         'None'        ' '    
    'Background'    PixelLabel        [2]         'None'        ' '    

Specify the location of the pixel label data for the image.

dataFile = {'pixelLabeledVisionTeam.jpg'}    

dataFile = 1x1 cell array
    {'pixelLabeledVisionTeam.jpg'}

Construct a table of label data for the pixel label data.

labelData = table(dataFile,'VariableNames',{'PixelLabelData'})

labelData=1×1 table
           PixelLabelData       
    ____________________________

    'pixelLabeledVisionTeam.jpg'

Create a groundTruth object.

gTruth = groundTruth(dataSource,labelDefs,labelData)

gTruth = 
  groundTruth with properties:

          DataSource: [1x1 groundTruthDataSource]
    LabelDefinitions: [2x5 table]
           LabelData: [1x1 table]

Create Ground Truth for Car and Lane Markers

Create a data source from a video.

videoName = 'caltech_cordova1.avi';
dataSource = groundTruthDataSource(videoName);

Define labels used to specify the ground truth. Use labelDefinitionCreator to create the label definitions table.

ldc = labelDefinitionCreator();
addLabel(ldc,'Cars',labelType.Rectangle);
addLabel(ldc,'LaneMarkers',labelType.Line);
labelDefs = create(ldc)

labelDefs=2×4 table
        Name           Type       Group     Description
    _____________    _________    ______    ___________

    'Cars'           Rectangle    'None'        ' '    
    'LaneMarkers'    Line         'None'        ' '    

Create label data for cars and lane markers.

numRows = numel(dataSource.TimeStamps);
carsTruth = cell(numRows,1);
laneMarkerTruth = cell(numRows,1);

Add two car labels and two lane markers to the first frame.

carsTruth{1} = [182 186 31 22;404 191 53 34];
laneMarkerTruth{1} = {[257 254;311 180] [327 183;338 205;374 250]};

Create a table of label data.

labelNames = {'Cars','LaneMarkers'};
labelData = table(carsTruth,laneMarkerTruth,'VariableNames',labelNames);

Create a groundTruth object. To import this object into the Ground Truth Labeler app, click Import Labels.

gTruth = groundTruth(dataSource,labelDefs,labelData)

gTruth = 
  groundTruth with properties:

          DataSource: [1x1 groundTruthDataSource]
    LabelDefinitions: [2x4 table]
           LabelData: [250x2 timetable]

Tips

• groundTruth objects for video-based data sources rely on the video reading capabilities of your operating system. A groundTruth object created using a video data source remains consistent only for the same platform that was used to create it. To create a platform-specific groundTruth object, convert the video into a sequence of images.