pointCloudObjectDetectorTrainingData

R2026b

Create training data for 3-D point cloud object detection

Since R2026b

Syntax

trainingData = pointCloudObjectDetectorTrainingData(gTruth)

[pcds,blds] = pointCloudObjectDetectorTrainingData(___)

___ = pointCloudObjectDetectorTrainingData(gTruth,Name=Value)

Description

The pointCloudObjectDetectorTrainingData function creates training data for 3-D object detection from cuboid labels in ground truth data exported from the Multi-Sensor Labeler app.

Use the training data to train deep learning networks for lidar object detection, such as trainPointPillarsObjectDetector. The function extracts point cloud frames and their corresponding cuboid bounding box labels from a single or an array of groundTruthMultiSensor objects.

trainingData = pointCloudObjectDetectorTrainingData(gTruth) creates a training data table for 3-D object detection from cuboid labels in a groundTruthMultiSensor object, gTruth. The output table contains point cloud file paths and corresponding cuboid bounding box labels suitable for training 3-D point cloud object detection networks such as PointPillars.

[pcds,blds] = pointCloudObjectDetectorTrainingData(___) returns a point cloud datastore, pcds, and a box label datastore, blds, instead of a training data table. Use this syntax to create datastores suitable for training 3-D object detection networks.

___ = pointCloudObjectDetectorTrainingData(gTruth,Name=Value) specifies options using one or more name-value arguments. For example, SignalName="lidarSequence" specifies the point cloud signal to use.

Examples

Generate Training Data for Point Cloud Object Detection

This example shows how to generate training data to train a deep learning network for point cloud object detection.

Step 1: Create Ground Truth from Data Source

Specify the name of the file containing the point cloud data. The input file is a Velodyne® packet capture (PCAP) file.

sourceName = fullfile(toolboxdir("pointcloud"),"pcdata",...
    "lidarData_ConstructionRoad.pcap");

Specify the parameters for loading the point cloud sequence from the data source.

sourceParams = struct();
sourceParams.DeviceModel = "HDL32E";
sourceParams.CalibrationFile = fullfile(matlabroot,"toolbox","shared",...
    "pointclouds","utilities","velodyneFileReaderConfiguration",...
    "HDL32E.xml");

Load the point cloud data from the specified source file by using the vision.labeler.loading.VelodyneLidarSource function.

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

Define class labels to specify the names of the objects in the input point cloud.

ldc = labelDefinitionCreatorMultiSensor();
addLabel(ldc,"Car","Cuboid");
labelDefs = ldc.create();

Define bounding boxes to specify the location of each object in the point cloud sequence, at each timestamp. Store information about bounding boxes and timestamp to a table.

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");
lidarROIData = lidar.labeler.labeldata.ROILabelData(dataSource.SignalName,{lidarData});

Create ground truth object.

gTruth = groundTruthMultiSensor(dataSource,labelDefs,lidarROIData,{});

Step 2: Generate Training Data

Create point cloud and box label datastores from the labeled ground truth by using the lidarObjectDetectorTrainingData function.

[pcds,bxds] = pointCloudObjectDetectorTrainingData(gTruth);

Processing ALL point cloud signals: lidarData_ConstructionRoad

--- Processing signal: lidarData_ConstructionRoad ---
Processing point cloud source type: Velodyne.Number of frames to process: 1.Successfully processed 1 point cloud files.
=== Summary ===
Total frames: 1
Signals processed: 1

Generate training data by combining the point cloud and box label datastores.

trainingData = combine(pcds,bxds);

Step 3: Configure Object Detector

Specify the class names, anchor boxes, point cloud range, and the voxel size. Configure the PointPillars object detector for training and inference.

classNames = "Car";
anchorBoxes = {[1.9,4.5,1.7,-1.78,0; 1.9,4.5,1.7,-1.78,1.57]};
pcRange = [0,69.12,-39.68,39.68,-5,5];
voxSize = [0.16,0.16];
detector = pointPillarsObjectDetector(pcRange,classNames,anchorBoxes,...
    VoxelSize=voxSize);

Step 4: Train Object Detector

Specify training options.

options = trainingOptions("adam",...
    Plots="none",...
    MaxEpochs=2,...
    MiniBatchSize=1,...
    GradientDecayFactor=0.9,...
    SquaredGradientDecayFactor=0.999,...
    InitialLearnRate=0.0002,...
    LearnRateDropPeriod=15,...
    LearnRateDropFactor=0.8,...
    ExecutionEnvironment="cpu",...
    DispatchInBackground=false,...
    BatchNormalizationStatistics="moving",...
    ResetInputNormalization=false);

Train the PointPillars object detector to detect classes specified in the input training data. You can use the trained detector to detect objects in a test point cloud by using the detect function.

[detector,info] = trainPointPillarsObjectDetector(trainingData,detector,options);

*************************************************************************
Processing data in minibatchqueue....

*************************************************************************
Data processing complete.

*************************************************************************
Training a PointPillars Object Detector for the following object classes:

* Car

 
    Epoch    Iteration    TimeElapsed    LearnRate    TrainingLoss
    _____    _________    ___________    _________    ____________

*************************************************************************
Detector training complete.
*************************************************************************

Input Arguments

gTruth — Multi-sensor ground truth data

groundTruthMultiSensor object | vector of groundTruthMultiSensor objects

Multi-sensor ground truth data, specified as a groundTruthMultiSensor object or vector of groundTruthMultiSensor objects. To create ground truth objects from existing ground truth data, use the groundTruthMultiSensor object. You can also use the Multi-Sensor Labeler app to label point cloud data and generate the ground truth data.

Note

The pointCloudObjectDetectorTrainingData function imports only the ground truth data with cuboid ROI labels for point cloud signals. Ground truth data with other label types is ignored.

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: trainingData = pointCloudObjectDetectorTrainingData(gTruth,PointCloudFormat="ply")

SignalName — Name of point cloud signal

string scalar | character vector

Name of the point cloud signal from which to extract training data, specified as a string scalar or character vector. If gTruth contains multiple point cloud signals and you do not specify this argument, the function processes all point cloud signals and combines the training data into a single output. Specify this argument to limit extraction to a single point cloud signal.

You can find the signal names from the DataSource property of the groundTruthMultiSensor object.

Example: SignalName="lidarSequence"

WriteLocation — Folder location for writing point cloud data

current working directory (default) | string scalar | character vector

Folder name to write extracted point cloud samples to, specified as a string scalar or character vector. The specified folder must exist and have write permissions.

Example: WriteLocation="C:\trainingData"

PointCloudFormat — File format for point cloud data

"pcd" (default) | "ply"

Point cloud file format, specified as "pcd" or "ply". File formats must be supported by pcwrite.

NamePrefix — File name prefix

signal name (default) | string scalar | character vector

Prefix for output point cloud file names, specified as a string scalar or character vector. The point cloud files are named as:

<prefix>_<pointcloud_number>.<pointcloud_format>

When gTruth is a vector of multiple groundTruthMultiSensor objects, the ground truth index is appended to the prefix:

<prefix><ground_truth_index>_<pointcloud_number>.<pointcloud_format>

By default, the prefix is the name of the signal from which the point clouds are extracted.

SamplingFactor — Factor for subsampling point clouds

"auto" (default) | positive integer | vector of positive integers

Factor for subsampling point clouds in the ground truth data source, specified as one of these values:

• "auto" — The function samples data sources with timestamps, such as a point cloud sequence, with a factor of 5. This is the default value.

• positive integer — Uniform sampling factor applied to all the point cloud samples in the data source. If gTruth is a vector of groundTruthMultiSensor objects, the same factor is applied to each object.

• vector of positive integers — The kth element in the vector is applied as the sampling factor for data sources in the kth ground truth object in the array.

For a sampling factor of N, the returned training data includes every Nth point cloud sample in the ground truth data source. The function ignores ground truth samples with empty label data.

Use sampled data to reduce repeated data, such as a sequence of point clouds with the same scene and labels. It can also help in reducing training time.

Note

For a sequence of point clouds, set the sampling factor to 1 to create training data with all the point clouds in the input sequence.

Verbose — Display progress information

true (default) | false

Flag to display writing progress in the command window, specified as one of these values:

• true — Displays information about the write progress, including which signals are being processed and the total number of frames extracted.

• false — Does not display information about the write progress.

UseParallel — Use parallel computing

false (default) | true

Option to perform computations in parallel using a parallel pool of workers, specified as one of these values:

• false — Run in serial.

• true — Use a parallel pool if one is open or if MATLAB can automatically create one. If a parallel pool is not available, run in serial.

To use a parallel pool to run computations, you must have Parallel Computing Toolbox™.

Example: UseParallel=true

Output Arguments

trainingData — Training data table

table

Labeled data for training the network, returned as a table with two or more columns. The first column of the table contains point cloud file names with paths. Each of the remaining columns corresponds to a cuboid ROI label and contains the locations of bounding boxes in the point cloud sample (specified in the first column), for that label. The bounding boxes are specified as a

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.

Use this table as input for training 3-D object detection networks. For example, use the training data with trainPointPillarsObjectDetector.

pcds — Point cloud datastore

fileDatastore object

Extracted point cloud data, returned as a fileDatastore object. The point cloud data contains only frames with at least one cuboid label. The function ignores unlabeled point cloud frames.

To create a datastore for training the network, combine the file and box label datastores by using combine(pcds, blds). Use the combined datastore to train deep learning networks for 3-D object detection.

blds — Box label datastore

boxLabelDatastore object

Extracted ROI labels, returned as a boxLabelDatastore (Computer Vision Toolbox) object. The datastore contains M-by-9 matrices of M bounding boxes and categorical vectors of cuboid ROI label names.

The bounding boxes are specified as a

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.

Extended Capabilities

Automatic Parallel Support

Accelerate code by automatically running computation in parallel using Parallel Computing Toolbox™.

The pointCloudObjectDetectorTrainingData function has automatic parallel support. To run computations in parallel, set the UseParallel name-value argument to true.

For more information about parallel computing, see Run MATLAB Functions with Automatic Parallel Support (Parallel Computing Toolbox).

Version History

Introduced in R2026b