Main Content

groundTruthLidar

Lidar ground truth label data

Since R2020b

expand all in page

Description

The groundTruthLidar object contains information about lidar ground truth labels. The data source used to create the object is a collection of lidar point cloud data. You can create, export, or import a groundTruthLidar object from the Lidar Labeler app.

Creation

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

Syntax

gTruth = groundTruthLidar(dataSource,labelDefs,labelData)

Description

gTruth = groundTruthLidar(dataSource,labelDefs,labelData) returns an object containing lidar ground truth labels that can be imported into the Lidar Labeler app.

  • dataSource specifies the source of the lidar point cloud data and sets the DataSource property.

  • labelDefs specifies the definitions of region of interest (ROI) and scene labels containing information such as Name, Type, and Group, and sets the LabelDefinitions property.

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

example

Properties

expand all

Source of ground truth lidar data, specified as a PointCloudSequenceSource, VelodyneLidarSource, LasFileSequenceSource, CustomPointCloudSource, or RosbagSource object. This object contains the information that describes the source from which the ground truth lidar data was labeled. This table provides more details about the type of objects that you can specify.

Object NameData SourceClass Reference
PointCloudSequenceSourcePoint cloud sequence foldervision.labeler.loading.PointCloudSequenceSource
VelodyneLidarSourceVelodyne® packet capture (PCAP) filevision.labeler.loading.VelodyneLidarSource
LasFileSequenceSourceLAS or LAZ file sequence folderlidar.labeler.loading.LasFileSequenceSource
CustomPointCloudSourcePoint cloud data from custom sourceslidar.labeler.loading.CustomPointCloudSource
RosbagSourceRosbag filelidar.labeler.loading.RosbagSource

This property is read-only.

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

  • In the Lidar Labeler app, create label definitions, and then export them as part of a groundTruthLidar object.

  • Use a labelDefinitionCreatorLidar 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 Lidar Labeler app session by selecting Open > 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

Type

labelType enumerations that specify the type of each label definition.

  • For ROI label definitions, the only valid labelType enumeration is labelType.Cuboid.

  • For scene label definitions, the only valid labelType enumeration is labelType.Scene.

Required

LabelColorRGB 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 Lidar Labeler app.

Optional

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

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

GroupStrings 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 Group column.

If you export label definitions from the Lidar Labeler app or create them using a labelDefinitionCreatorLidar object, the label definitions table includes this column, even if you did not specify groups. The app assigns each label definition a Group value of 'None'.

DescriptionStrings 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 Description column.

If you export label definitions from the Lidar Labeler app or create them using a labelDefinitionCreatorLidar 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.

Hierarchy

Structures containing attribute information for each label definition.

FieldDescription
AttributeName1,...,AttributeNameN

Attribute information

Each defined attribute has its own field, where the name of the field corresponds to the attribute name. The attribute value is a structure containing these fields:

  • DefaultValue — Default value of the attribute, specified as a numeric scalar for Numeric attributes, a string for String attributes, or a logical scalar or empty array for Logical attributes. List attributes do not contain this field.

  • ListItems — List items of the attribute, specified as a cell array of character vectors. Only List attributes contain this field.

  • Description — Description of the attribute, specified as a character vector.

TypeType of parent label for the attributes, specified as a string or character vector.
DescriptionDescription of parent label for the attributes, specified as a string or character vector.

If a label definition does not contain attributes, then the table entry for that label definition is empty.

Optional

When you define sublabels or attributes in the Lidar Labeler app or the labelDefinitionCreatorMultisignal object, the generated label definitions table includes this column.

This property is read-only.

Label data for each ROI and scene label, specified as a timetable. Each column of LabelData holds labels for a single label definition and corresponds to the Name value for each row in LabelDefinitions. The storage format for the label data depends on the label type.

Label TypeStorage Format for Labels at Each Timestamp

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.

Cuboid with center point, lengths, and rotation angles labeled

labelType.Scene

Logical vector, where true indicates the presence of the label at that timestamp.

If the Cuboid ROI label data includes attributes, then the labels at each timestamp must be specified as structures instead. The structure includes these fields.

Label Structure FieldDescription
Position

Positions of the parent labels at the given timestamp

The format of Position for labels of type Cuboid is described in the previous table.

AttributeName1,...,AttributeNameN

Attributes of the parent labels

Each defined attribute has its own field, where the name of the field corresponds to the attribute name. The attribute value is a character vector for a List or String attribute, a numeric scalar for a Numeric attribute, or a logical scalar for a Logical attribute. If the attribute is unspecified, then the attribute value is an empty vector.

Object Functions

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

Examples

collapse all

Open Live Script

Create ground truth data for a Velodyne lidar source that captures a car on the road. Specify the signal sources, label definitions, and ROI label data.

Create a Velodyne data source.

sourceName = fullfile(toolboxdir('vision'),'visiondata', ...
    'lidarData_ConstructionRoad.pcap');
sourceParams = struct();
sourceParams.DeviceModel = 'HDL32E';
sourceParams.CalibrationFile = fullfile(matlabroot,'toolbox','shared', ...
    'pointclouds','utilities','velodyneFileReaderConfiguration', ...
    'HDL32E.xml');

Load the data source.

dataSource = vision.labeler.loading.VelodyneLidarSource;
dataSource.loadSource(sourceName,sourceParams);

Create label definitions.

ldc = labelDefinitionCreatorLidar;
addLabel(ldc,'Car','Cuboid');
labelDefs = ldc.create;

Create ground truth data for lidar sequence.

numPCFrames = numel(dataSource.Timestamp{1});
carData = cell(numPCFrames,1);
carData{1} = [1.0223 13.2884 1.1456 8.3114 3.8382 3.1460 0 0 0];
lidarData = timetable(dataSource.Timestamp{1},carData, ...
    'VariableNames',{'Car'});

Create the ground truth lidar object.

gTruth = groundTruthLidar(dataSource,labelDefs,lidarData)
gTruth = 
  groundTruthLidar with properties:

          DataSource: [1x1 vision.labeler.loading.VelodyneLidarSource]
    LabelDefinitions: [1x5 table]
           LabelData: [40x1 timetable]

Version History

Introduced in R2020b

See Also

Objects