gatherLabelData

Gather label data from ground truth

Since R2021a

Syntax

labelData = gatherLabelData(gTruth,typeOfLabel)

[labelData,timestamps] = gatherLabelData(___)

[___] = gatherLabelData(___,Name=Value)

Description

labelData = gatherLabelData(gTruth,typeOfLabel) returns label data gathered from ground truth data, gTruth. The function returns label data specified by typeOfLabel.

[labelData,timestamps] = gatherLabelData(___) additionally returns the image timestamps associated with the gathered label data, using the arguments from the previous syntax.

[___] = gatherLabelData(___,Name=Value) uses name-value arguments to specify how to gather data. For example, labelData = gatherLabelData(gTruth,typeofLabel,SampleFactor=5) specifies to drop every 5th frame.

Examples

Gather Polygon Labels

Gather all of the polygon labels from the groundtruth image.

data = load('groundtruthVisionTeam.mat');
gtruth = data.groundtruthVisionTeam;

Gather all of the polygon objects.

labelData = gatherLabelData(gtruth, labelType('Polygon'), 'GroupLabelData', 'LabelType');
 
polygons = labelData{1}.PolygonData{1}(:,1);
polygonLabels = labelData{1}.PolygonData{1}(:,2);

Visualize the polygon labels.

im = imread('visionteam.jpg');
imshow(im);
showShape('polygon', polygons, 'Label', polygonLabels);

Input Arguments

gTruth — Ground truth data

groundTruth object | vector of groundTruth objects

Ground truth data, specified as a groundTruth object or vector of groundTruth objects.

typeOfLabel — Label types

vector of labelType objects

Label types from which to gather label data, specified as a vector of labelType objects. The gatherLabelData function gathers label data from each groundTruth object specified by input gTruth The label data is grouped in columns either by label name or by label type, specified by the GroupLabelData name-value argument.

Valid Enumeration Types

You can specify one or more of these enumeration types.

• labelType.Rectangle — Rectangle ROI labels

• labelType.RotatedRectangle — Rotated Rectangle ROI labels

• labelType.Cuboid — Cuboid ROI labels (point clouds)

• labelType.ProjectedCuboid — Projected cuboid ROI labels (images and video data)

• labelType.Line — Line ROI labels

• labelType.PixelLabel — Pixel ROI labels

• labelType.Polygon — Pixel ROI labels

• labelType.Scene — Scene labels

To gather label data for scenes, you must specify labelTypes as the labelType.Scene enumeration scalar. You cannot specify any other label types with labelType.Scene.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: labelData = gatherLabelData(gTruth,typeofLabel,SampleFactor=5) specifies to drop every 5th frame.

SampleFactor — Sample factor

1 (default) | positive integer

Sample factor to subsample label data, specified as a positive integer. A sample factor of K includes every Kth frame. Increase the sample factor to drop redundant frames from signals with high sample rates, such as video.

GroupLabelData — Group columns from label data

'LabelName' (default) | 'LabelType'

Group columns from label data, specified as 'LabelName' or 'LabelType'.

• 'LabelName' — Groups the label data by label definitions.

• 'LabelType' — Groups the label data by label type. Use this option to gather label data with the region-of-interest (ROI) stacking order retained by the label type.

Group label data with the scene label type (labelType.Scene) by label definitions only.

Output Arguments

labelData — Label data

cell array of tables

Label data, returned as an M-by-1 cell array of tables, where M is the number of groundTruth objects in gTruth. The columns of the tables represent label data grouped by either label name or label type, specified by the GroupLabelData name-value argument.

For each cell in the table, the format of the returned label data depends on the type of label.

Label Type	Storage Format for Labels at Each Timestamp
labelType.Rectangle	M-by-4 numeric matrix of the form [x, y, w, h], where: M is the number of labels in the frame. x and y specify the upper-left corner of the rectangle. w specifies the width of the rectangle, which is its length along the x-axis. h specifies the height of the rectangle, which is its length along the y-axis.
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]. M is the number of rotated rectangles. xctr and yctr specify the center of the rectangle. w specifies the width of the rectangle, which is its length along the x-axis before rotation. h specifies the height of the rectangle, which is its length along the y-axis before rotation. yaw specifies the rotation angle in degrees. The rotation is clockwise-positive around the center of the rectangle.
labelType.Cuboid	M-by-9 numeric matrix with rows of the form [xctr, yctr, zctr, xlen, ylen, zlen, xrot, yrot, zrot], where: M is the number of labels in the frame. xctr, yctr, and zctr specify the center of the cuboid. xlen, ylen, and zlen specify the length of the cuboid along the x-axis, y-axis, and z-axis, respectively, before rotation has been applied. xrot, yrot, and zrot specify the rotation angles for the cuboid along the x-axis, y-axis, and z-axis, respectively. These angles are clockwise-positive when looking in the forward direction of their corresponding axes. The figure shows how these values determine the position of a cuboid.
labelType.ProjectedCuboid	M-by-8 vector of the form [x1, y1, w1, h1, x2, y2, w2, h2], where: M is the number of labels in the frame. x1, y1 specifies the x,y coordinates for the upper-left location of the front-face of the projected cuboid w1 specifies the width for the front-face of the projected cuboid. h1 specifies the height for the front-face of the projected cuboid. x2, y2 specifies the x,y coordinates for the upper-left location of the back-face of the projected cuboid. w2 specifies the width for the back-face of the projected cuboid. h2 specifies the height for the back-face of the projected cuboid. The figure shows how these values determine the position of a cuboid.
labelType.Line	M-by-1 vector of cell arrays, where M is the number of labels in the frame. Each cell array contains an N-by-2 numeric matrix of the form [x1 y1; x2 y2; ... ; xN yN] for N points in the polyline.
labelType.PixelLabel	Label data for all pixel label definitions is stored in a single M-by-1 PixelLabelData column for M images or frames. Each element contains a filename for a pixel label image. A pixel label image describes the label or labels contained in the corresponding image. The labels can be described as a 1- or 3- channel label matrix. To use PixelLabelData with any of the labeler apps, you must use a single-channel label matrix, where the values are of type uint8. You can convert a 3-channel pixel label data matrix to a single-channel label matrix programmatically to use with the labeler apps.
labelType.Polygon	M-by-1 vector of cell arrays, where M is the number of labels. Each cell array contains an N-by-2 numeric matrix of the form [x1 y1; x2 y2; ... ; xN yN] for N points in the polygon.
labelType.Scene	Logical 1 (true) if the scene label is applied, otherwise logical 0 (false)

timestamps — Timestamps

cell array of duration vectors

Timestamps, returned as an M-by-1 cell array of duration vectors, where:

• M is the number of groundTruth objects in gTruth.

• labelData{m} contains the timestamps that is in the mth groundTruth object of gTruth.

Limitations

• The gatherLabelData function does not gather label data for sublabels or attributes. If a label contains sublabels or attributes, in the labelData output, the function returns the position of the parent label only.

Version History

Introduced in R2021a

R2022b: Project cuboids from 3-D world coordinates to 2-D image coordinates

Updated to support 3-D projected cuboid labels.