groundTruth
Ground truth label data
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. For a summary about the data stored in the groundTruth
object,
see Elements of Ground Truth Objects.
To create training data for an object detector from arrays of
groundTruth
objects, use theobjectDetectorTrainingData
function.To create training data for a semantic segmentation network from arrays of
groundTruth
objects, use thepixelLabelTrainingData
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).
Description
returns an object containing ground truth labels that can be imported into the
Image
Labeler and Video
Labeler apps.gTruth
= groundTruth(dataSource
,labelDefs
,labelData
)
dataSource
specifies the source of the ground truth data and sets theDataSource
property.labelDefs
specifies the label, sublabel, and attribute definitions of the ground truth data and sets theLabelDefinitions
property.labelData
specifies the identifying information, position, and timestamps for marked labels and sets theLabelData
property.
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 read function. For more details, see Use Custom Image Source Reader for Labeling.
LabelDefinitions
— Label definitions
table
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.
Column | Description | Required or Optional |
---|---|---|
Name | Strings or character vectors specifying the name of each label definition. | Required |
Type | labelType
enumerations that specify the type of each label
definition, such as Rectangle or
Scene . | Required |
LabelColor | 1-by-3 row vectors of RGB triplets that specify the colors of the label definitions. Values are in the range [0, 1]. The color 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, an exported label definitions table always includes this column. When you create label
definitions using the
|
PixelLabelID | Scalars, 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
When creating a label
definitions table at the MATLAB command line, if you set
|
Group | Strings or character vectors specifying the group to which each label definition belongs. | Optional If you create the label definitions table at the
MATLAB command line, you do not need to
include a If you export label definitions
from a labeling app or create them using a
|
Description | Strings or character vectors that describe each label definition. | Optional If you create the label definitions table at the
MATLAB command line, you do not need to
include a If you export label definitions
from a labeling app or create them using a
|
Hierarchy | Structures 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
|
For example, consider a table with label definitions named Sky
,
Vegetation
, Lanes
,
StopSign
, and Vehicle
, and 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.
Note
Labeler apps can only load pixel data that have pixel IDs between 1 and 255.
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
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.
Alternatively, for ROI label data that is grouped by label type, a single
column labeled ROILabelData
, can be used and specified as
a structure containing at least one label type,
RectangleData
, PolygonData
,
LineData
, or ProjCuboidData
.
The storage format for each label type is described in the table.
Label Type | Storage Format for Labels at Each Timestamp |
---|---|
labelType.Rectangle |
|
labelType.RotatedRectangle |
For one or more rotated rectangles, specify in spatial coordinates as an M-by-5 numeric matrix, where each row specifies a rotated rectangle of the form [xctr yctr w h yaw].
|
|
The figure shows how these values determine the position of a cuboid. |
|
The figure shows how these values determine the position of a cuboid. |
labelType.Line |
|
labelType.PixelLabel | Label data for all pixel label definitions is stored in a
single M-by-1 |
labelType.Polygon |
|
labelType.Custom | Labels are stored exactly as they are specified in the
timetable. If you import a
groundTruthMultisignal object
containing custom label data into the Ground Truth
Labeler app, this data is not imported into the
app. Use custom data when gathering label data for training
and combining it with data labeled in the app. |
labelType.Scene | Stored as a logical . |
To add ground truth data that is not in one of the native supported ROIs or a
Scene
label category to a groundTruth
object, you must 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 labels by label group |
selectLabelsByType | Select ground truth labels by label type |
selectLabelsByName | Select ground truth labels by label name |
changeFilePaths | Change file paths in ground truth data |
gatherLabelData | Gather label data from ground truth |
merge | Merge two or more ground truth objects |
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
{'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 {0x0 char} {'None'} {' '}
{'carRear' } Rectangle {0x0 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
_________________ ___________________
{[856 318 39 41]} {[398 378 315 210]}
{[445 523 52 54]} {[332 633 691 287]}
Create a ground truth object.
gTruth = groundTruth(dataSource,labelDefs,labelData)
gTruth = groundTruth with properties: DataSource: [1x1 groundTruthDataSource] LabelDefinitions: [2x5 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=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]
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×6 table
Name Type LabelColor PixelLabelID Group Description
______________ __________ __________ ____________ ________ ___________
{'Person' } PixelLabel {0x0 char} {[1]} {'None'} {' '}
{'Background'} PixelLabel {0x0 char} {[2]} {'None'} {' '}
Specify the location of the pixel label data for the image.
dataFile = {'visionteamPixelLabels.png'}
dataFile = 1x1 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: [1x1 groundTruthDataSource] LabelDefinitions: [2x6 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 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 {0x0 char} {'None'} {' '}
{'LaneMarkers'} Line {0x0 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: [1x1 groundTruthDataSource] LabelDefinitions: [2x5 table] LabelData: [250x2 timetable]
Tips
groundTruth
objects for video-based data sources rely on the video reading capabilities of your operating system. AgroundTruth
object created using a video data source remains consistent only for the same platform that was used to create it. To create a platform-independentgroundTruth
object, convert the video into a sequence of images and include the associated timestamps with the image sequence.
Version History
Introduced in R2017a
See Also
Apps
Functions
Objects
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)