groundTruthLidar

Object for storing labeled lidar data

Since R2020b

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.

Properties

DataSource — Source of ground truth lidar data

PointCloudSequenceSource object | VelodyneLidarSource object | LasFileSequenceSource object | CustomPointCloudSource object | RosbagSource object

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 Name	Data Source	Class Reference
PointCloudSequenceSource	Point cloud sequence folder	vision.labeler.loading.PointCloudSequenceSource
VelodyneLidarSource	Velodyne® packet capture (PCAP) file	vision.labeler.loading.VelodyneLidarSource
LasFileSequenceSource	LAS or LAZ file sequence folder	lidar.labeler.loading.LasFileSequenceSource
CustomPointCloudSource	Point cloud data from custom sources	lidar.labeler.loading.CustomPointCloudSource
RosbagSource	Rosbag file	lidar.labeler.loading.RosbagSource

LabelDefinitions — Label definitions

Read-only: table

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.

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. 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
LabelColor	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 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.
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 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'.
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 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. Field Description 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. Type Type of parent label for the attributes, specified as a string or character vector. Description Description 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.

LabelData — Label data for each ROI and scene label

Read-only: timetable

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 Type	Storage 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.
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 Field	Description
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

changeFilePaths	Change file paths in ground truth data
selectLabels	Select ground truth data by label name or type
selectLabelsByGroup	Select ground truth data by label group name
selectLabelsByName	Select ground truth data by label name
selectLabelsByType	Select ground truth data by label type

Examples

Create Ground Truth Lidar Object

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: [1×1 vision.labeler.loading.VelodyneLidarSource]
    LabelDefinitions: [1×5 table]
           LabelData: [40×1 timetable]

Version History

Introduced in R2020b