groundTruth

Ground truth label data

expand all in page

Description

The groundTruth object contains information about the data source, label definitions, and marked label annotations for a set of ground truth labels. You can export or import a groundTruth object from the Image Labeler and Video Labeler apps.

  • 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

To export a groundTruth object from a labeling app, on the app toolstrip, select Export Labels > To Workspace. The app exports the object to the MATLAB® workspace. To create a groundTruth object programmatically, use the groundTruth function (described here).

Syntax

gTruth = groundTruth(dataSource,labelDefs,labelData)

Description

example

gTruth = groundTruth(dataSource,labelDefs,labelData) returns an object containing ground truth labels that can be imported into the Image Labeler and Video Labeler apps.

  • dataSource specifies the source of the ground truth data and sets the DataSource property.

  • labelDefs specifies the label, sublabel, and attribute definitions of the ground truth data and sets the LabelDefinitions property.

  • labelData specifies the identifying information, position, and timestamps for marked labels and sets the LabelData property.

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. For more details, see Use Custom Image Source Reader for Labeling.

This property is read-only.

Label definitions, specified as a table. To create this table, use one of these options.

  • In one of the labeling apps, create label definitions, and then export them as part of a groundTruth object.

  • Use a labelDefinitionCreator object to generate a label definitions table. If you save this table to a MAT-file, you can then load the label definitions into a labeling app session by selecting Load > Label Definitions from the app toolstrip.

  • Create the label definitions table at the MATLAB command line.

This table describes the required and optional columns of the table specified in the LabelDefinitions property.

ColumnDescriptionRequired or Optional
NameStrings or character vectors specifying the name of each label definition.

Required

TypelabelType enumerations that specify the type of each label definition, such as Rectangle or Scene.

Required

LabelColor1-by-3 row vectors of RGB triplets that specify the colors of the label definitions. Values are in the range [0, 1]. The color of yellow (RGB triplet [1 1 0]) is reserved for the color of selected labels in the labeling apps.

Optional

When you define labels in a labeling app, you must specify a color. Therefore, the exported label definitions table always includes this column.

When you create label definitions using the labelDefinitionCreator object without specifying colors, the returned label definitions table includes this column, but all column values are empty.

PixelLabelIDScalars, column vectors, or M-by-3 matrices of integer-valued label IDs. PixelLabelID specifies the pixel label values used to represent a label definition. Pixel label ID values must be between 0 and 255.

Optional

When you define pixel labels in a labeling app or the labelDefinitionCreator object, the generated label definitions table includes this column.

When creating label definitions programmatically, if you set Type to labelType.PixelLabel for any label, then this column is required.

GroupStrings or character vectors specifying the group to which each label definition belongs.

Optional

If you create label definitions programmatically, you do not need to include a Group column.

If you export label definitions from a labeling app or create them using a labelDefinitionCreator object, the label definitions table includes this column, even if you did not specify groups. Each label definition is assigned a Group value of 'None'.

DescriptionStrings or character vectors that describe each label definition.

Optional

If you create label definitions programmatically, you do not need to include a Description column.

If you export label definitions from a labeling app or create them using a labelDefinitionCreator object, the label definitions table includes this column, even if you did not specify descriptions. The Description for these label definitions is an empty character vector.

HierarchyStructures containing sublabel and attribute data for each label definition. For an example of the Hierarchy format, see Get Started with the Image Labeler or Get Started with the Video Labeler.

Optional

In labeling apps, when you define sublabels or attributes, the exported groundTruth object includes this column.

For example, consider a table with label definitions named cars, sky, vegetation, road, signs, and lanes that was exported from the Video Labeler app.

  • The label definitions include pixel labels, so the table includes a PixelLabelID column.

  • Two of the labels contain attributes, so the app created a Hierarchy column that applies across all label definitions.

  • The label definitions do not have assigned groups, so the Group column is 'None' for all label definitions.

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 sequences. Each column of LabelData holds labels for a single label definition and corresponds to the Name value for each row in LabelDefinitions. These LabelData describes the elements of the table. The label categories are specified as labelType enumerations.

Label Definition TypeLabel 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 AppImage Labeler App
Data sourceVideo file, image sequence folder, custom readerImage files
Label definitionsRectangle, Line, PixelLabel, or Scene label typesRectangle, Line, PixelLabel, or Scene label types
Label dataTimetable of Rectangle, Line, PixelLabel, or Scene label typesTable (no timetable) for Rectangle, Line, 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

selectLabelsByGroupSelect ground truth labels by label group
selectLabelsByTypeSelect ground truth labels by label type
selectLabelsByNameSelect ground truth labels by label name
changeFilePathsChange file paths in ground truth data

Examples

collapse all

Open Live Script

Create a data source from a collection of images.

data = load('stopSignsAndCars.mat');
imageFilenames = data.stopSignsAndCars.imageFilename(1:2)
imageFilenames = 2×1 cell
    {'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×5 table
        Name          Type       LabelColor     Group      Description
    ____________    _________    __________    ________    ___________

    {'stopSign'}    Rectangle    {0×0 char}    {'None'}       {' '}   
    {'carRear' }    Rectangle    {0×0 char}    {'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   
    ____________    ____________

    {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×5 table]
           LabelData: [2×2 table]
Open Live Script

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=table
                Lane            
    ____________________________

    {2x2 double}    {3x2 double}

Create a groundTruth object.

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

          DataSource: [1x1 groundTruthDataSource]
    LabelDefinitions: [1x5 table]
           LabelData: [1x1 table]
Open Live Script

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×6 table
         Name            Type       LabelColor    PixelLabelID     Group      Description
    ______________    __________    __________    ____________    ________    ___________

    {'Person'    }    PixelLabel    {0×0 char}       {[1]}        {'None'}       {' '}   
    {'Background'}    PixelLabel    {0×0 char}       {[2]}        {'None'}       {' '}

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

dataFile = {'visionteamPixelLabels.png'}    
dataFile = 1×1 cell array
    {'visionteamPixelLabels.png'}

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

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

    {'visionteamPixelLabels.png'}

Create a groundTruth object.

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

          DataSource: [1×1 groundTruthDataSource]
    LabelDefinitions: [2×6 table]
           LabelData: [1×1 table]
Open Live Script

Create a data source from a video.

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

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

ldc = labelDefinitionCreator();
addLabel(ldc,'Cars',labelType.Rectangle);
addLabel(ldc,'LaneMarkers',labelType.Line);
labelDefs = create(ldc)
labelDefs=2×5 table
         Name            Type       LabelColor     Group      Description
    _______________    _________    __________    ________    ___________

    {'Cars'       }    Rectangle    {0×0 char}    {'None'}       {' '}   
    {'LaneMarkers'}    Line         {0×0 char}    {'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 a labeling app, select an option from the Open > Import Labels menu.

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

          DataSource: [1×1 groundTruthDataSource]
    LabelDefinitions: [2×5 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.

See Also

Apps

Functions

Objects

Topics

Introduced in R2017a

Computer Vision Toolbox Documentation
Support