Main Content

gatherLabelData

Gather label data from ground truth

Description

example

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 pair arguments to specify how to gather data.

Examples

collapse all

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

collapse all

Ground truth data, specified as a groundTruth object or vector of groundTruth 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.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 Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: SampleFactor=5 drops every 5th frame.

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.

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. This option can be used to gather label data with the region-of-interest (ROI) stacking order retained by the label type.

Output Arguments

collapse all

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 labe 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 TypeStorage 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.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.

Labeled projected 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.SceneLogical 1 (true) if the scene label is applied, otherwise logical 0 (false)

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.

Introduced in R2021a