This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English version of the page.

Note: This page has been translated by MathWorks. Click here to see
To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

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

expand all

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.

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 DefinitionDescription
NameCharacter vector specifying the name of the label category.
TypelabelType enumeration that specifies the label category type.
PixelLabelIDA 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.
DescriptionCharacter vector that describes the label category. The description label definition is optional.
HierarchyA 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 System 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'})

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 CategoryLabel Values
labelType.RectangleLabels 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.LineLabels 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.PixelLabelLabel 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.SceneLabels in each row are stored as logical values representing the presence or absence of the scene label for the image.
labelType.CustomLabels 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 AppImage Labeler App
Data sourceVideo file, image sequence folder, custom readerImage files
Label definitionsRectangle, Line, PixelLabel, or Scene label typesRectangle, PixelLabel or Scene label types
Label dataTimetable of Rectangle, Line, PixelLabel, or Scene label typesTable (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

selectLabelsSelect ground truth data for a set of labels
changeFilePathsChange file paths in data source and pixel label data of ground truth object

Examples

collapse all

Create a data source from a collection of images.

data = load('stopSignsAndCars.mat');
imageFilenames = data.stopSignsAndCars.imageFilename(1:2)
imageFilenames = 2×1 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×3 table
       Name         Type       Description
    __________    _________    ___________

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

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

    [1×4 double]    [1×4 double]
    [1×4 double]    [1×4 double]

Create a ground truth object.

gTruth = groundTruth(dataSource,labelDefs,labelData)
gTruth = 
  groundTruth with properties:

          DataSource: [1×1 groundTruthDataSource]
    LabelDefinitions: [2×3 table]
           LabelData: [2×2 table]

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            
    ____________________________

    [2×2 double]    [3×2 double]

Create a groundTruth object.

gTruth = groundTruth(dataSource,labelDefs,labelData)
gTruth = 
  groundTruth with properties:

          DataSource: [1×1 groundTruthDataSource]
    LabelDefinitions: [1×3 table]
           LabelData: [1×1 table]

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×4 table
        Name           Type       PixelLabelID    Description
    ____________    __________    ____________    ___________

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

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

dataFile = {'pixelLabeledVisionTeam.jpg'}    
dataFile = 1×1 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: [1×1 groundTruthDataSource]
    LabelDefinitions: [2×4 table]
           LabelData: [1×1 table]

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×3 table
        Name           Type       Description
    _____________    _________    ___________

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

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: [1×1 groundTruthDataSource]
    LabelDefinitions: [2×3 table]
           LabelData: [250×2 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.

Introduced in R2017a