trainPointPillarsObjectDetector

Train PointPillars object detector

Since R2021b

Syntax

detector = trainPointPillarsObjectDetector(trainingData,detector,options)

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

___ = trainPointPillarsObjectDetector(___,Name=Value)

detector = trainPointPillarsObjectDetector(trainingData,checkpoint,options)

Description

Train a Detector

detector = trainPointPillarsObjectDetector(trainingData,detector,options) trains a PointPillars object detector using deep learning and the specified training options for the detection network.

[detector,info] = trainPointPillarsObjectDetector(trainingData,detector,options) returns information on the training progress of the object detector, such as the training accuracy for each iteration.

___ = trainPointPillarsObjectDetector(___,Name=Value) uses additional options specified by one or more name-value arguments and any of the previous inputs.

Resume Training a Detector

detector = trainPointPillarsObjectDetector(trainingData,checkpoint,options) resumes training from the saved detector checkpoint.

You can use this syntax to:

• Add more training data and continue the training.

• Improve training accuracy by increasing the maximum number of iterations.

Input Arguments

trainingData — Input training data

valid datastore object | table

Training data, specified as a valid datastore object or table.

• If you use a datastore object, your data must be set up such that using the read function on the datastore object returns a cell array or table with three columns. Each row corresponds to a point cloud, and the columns must follow this format.

  • First column — Organized or unorganized point cloud data, specified as a pointCloud object.

  • Second column — Bounding boxes, specified as a cell array containing an M-by-9 matrix. Each row of the matrix is of the form [x y z length width height roll pitch yaw], representing the location and dimension of a bounding box. M is the number of bounding boxes.

  • Third column — Labels, specified as a cell array containing an M-by-1 categorical vector with object class names. All categorical data returned by the datastore must use the same pool of categories.

  You can use the combine function to combine two or more datastores. For more information on creating datastore objects, see the datastore function.

• If you use a table, the table must have two or more columns. The first column must contain point cloud file names. The point cloud files can be in any format supported by pcread function. Each of the remaining columns represent a single object class such as Car, or Truck containing cell vectors. Each cell contains an M-by-9 matrix, M is the number of bounding boxes. The columns of the each matrix are of the form [x y z length width height roll pitch yaw], specifying the location and dimensions of the bounding box in the corresponding point cloud.

You can generate the input training data from labeled ground truth samples by using the lidarObjectDetectorTrainingData function.

detector — PointPillars object detector

pointPillarsObjectDetector object

PointPillars object detector, specified as a pointPillarsObjectDetector object.

• You can train an untrained object detector using the training options.

• You can continue training a pretrained detector with additional training data, or perform more training iterations to improve detector accuracy.

options — Training options

TrainingOptionsSGDM object | TrainingOptionsRMSProp object | TrainingOptionsADAM object

Training options, specified as a TrainingOptionsSGDM, TrainingOptionsRMSProp, or TrainingOptionsADAM object returned by the trainingOptions (Deep Learning Toolbox) function. To specify the solver name and other options for network training, use the trainingOptions (Deep Learning Toolbox) function.

Note

The trainPointPillarsObjectDetector function supports these training options.

Name-Value Arguments	Supported Options
ExecutionEnvironment	"auto", "gpu", "cpu" For "multi-gpu", "parallel" set the DispatchInBackground argument to false.
ResetInputNormalization	false
BatchNormalizationStatistics	"moving"
OutputNetwork	"last-iteration"

checkpoint — Saved detector checkpoint

pointPillarsObjectDetector object

Saved detector checkpoint, specified as a pointPillarsObjectDetector object. To periodically save a detector checkpoint during training, specify CheckpointPath. To control how frequently check points are saved see the CheckPointFrequency and CheckPointFrequencyUnit training options.

To load a checkpoint for a previously trained detector, first load the corresponding MAT file from the checkpoint path. Then extract the object detector from the loaded data. For example, if the CheckpointPath property of your options object is '/checkpath', you can load a checkpoint MAT file by using this code.

data = load("/checkpath/pointpillars_checkpoint__216__2018_11_16__13_34_30.mat");
checkpoint = data.detector;

The name of the MAT file includes the iteration number and timestamp of when the detector checkpoint was saved. The MAT file saves the detector in the detector variable. Use the trainPointPillarsObjectDetector function to train the detector.

pointPillarsDetector = trainPointPillarsObjectDetector(trainingData,checkpoint,options);

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: trainPointPillarsObjectDetector(data,detector,ExperimentManager=expMonitorObj) specifies the ExperimentManger value by using an experiments.Monitor (Deep Learning Toolbox) object, expMonitorObj.

ExperimentManager — Detector training experiment monitoring

'none' (default) | experiments.Monitor object

Detector training experiment monitoring, specified as an experiments.Monitor (Deep Learning Toolbox) object for use with the Experiment Manager (Deep Learning Toolbox) app. You can use this object to track the progress of training, update information fields in the training results table, record values of the metrics used by the training, and to produce training plots. For an example using this app, see Train Object Detectors in Experiment Manager.

Information monitored during training:

• Training loss at each iteration.

• Learning rate at each iteration.

Validation information when the training options input contains validation data:

• Validation loss at each iteration.

Output Arguments

detector — Trained PointPillars object detector

pointPillarsObjectDetector object

Trained PointPillars object detector, returned as pointPillarsObjectDetector object.

info — Training progress information

structure array

Training progress information, returned as a structure array with these fields. Each field corresponds to a stage of training.

• TrainingLoss — Training loss at each iteration. The training loss is the mean squared error (MSE), calculated as the sum of the localization error, confidence loss, and classification loss.

• BaseLearnRate — Learning rate at each iteration.

• OutputNetworkIteration — Iteration number of the returned network.

• ValidationLoss — Validation loss at each iteration.

• FinalValidationLoss — Final validation loss at the end of the training.

Each field is a numeric vector with one element per training iteration. If the function does not calculate a value at a specific iteration, it returns a value of NaN for that iteration. The structure contains ValidationLoss and FinalValidationLoss fields only when options specifies validation data.

Version History

Introduced in R2021b

R2022b: Support for Experiment Manager App

You can now specify the ExperimentManager value by using an experiments.Monitor (Deep Learning Toolbox) object as a name-value argument to the function. You can use the experiments.Monitor (Deep Learning Toolbox) object with the Experiment Manager (Deep Learning Toolbox) app.

For more information on using this app, see Train Object Detectors in Experiment Manager.