semanticPointLabelTrainingData

R2026b

Create training data for 3-D point cloud semantic segmentation from labeled ground truth

Since R2026b

collapse all in page

Syntax

[pcds,splds] = semanticPointLabelTrainingData(gTruth)
[pcds,splds] = semanticPointLabelTrainingData(gTruth,Name=Value)

Description

The semanticPointLabelTrainingData function creates paired datastores for training 3-D point cloud semantic segmentation networks from ground truth data labeled in the Multi-Sensor Labeler app.

The function writes point cloud frames and their per-point semantic labels to disk and returns a fileDatastore for the point clouds and a semanticPointLabelDatastore for the labels. Combine these datastores using combine to create training input for networks such as RANDLA-Net using the trainRandlanet function.

[pcds,splds] = semanticPointLabelTrainingData(gTruth) creates paired datastores for training 3-D point cloud semantic segmentation networks from a groundTruthMultiSensor object, gTruth. The function returns a point cloud datastore, pcds, and a semantic point label datastore, splds. Each read from pcds returns a point cloud frame and the corresponding read from splds returns the per-point semantic labels for that frame.

[pcds,splds] = semanticPointLabelTrainingData(gTruth,Name=Value) specifies options using one or more name-value arguments. For example, SignalName="lidarSequence" specifies the point cloud signal to use from the ground truth object.

example

Examples

collapse all

Create paired datastores for training a 3-D semantic segmentation network from ground truth data exported from the Multi-Sensor Labeler app.

Load a groundTruthMultiSensor object that contains semantic point labels for a lidar point cloud sequence. This object was exported from the Multi-Sensor Labeler app after labeling point cloud frames with semantic classes such as ground, vegetation, and building.

load("groundTruthMultiSensor.mat");

Create training datastores from the ground truth data. Specify the point cloud signal name and a sampling factor of 5 to include every 5th frame. Write output files to a temporary directory.

[pcds,splds] = semanticPointLabelTrainingData(gTruth, ...
    SignalName="lidar", ...
    SamplingFactor=5, ...
    WriteLocation=fullfile(tempdir,"TrainingData"));

Preview the first point cloud frame and its corresponding per-point semantic labels.

ptCloud = read(pcds);
labels = read(splds);

Combine the datastores into a single datastore suitable for training. Use the combined datastore as input to a training function such as trainRandlanet.

cds = combine(pcds,splds);

Input Arguments

collapse all

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 with semantic classes and generate the ground truth data.

Note

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

Name-Value Arguments

collapse all

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: [pcds,splds] = semanticPointLabelTrainingData(gTruth,SignalName="lidar",SamplingFactor=5)

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 that have SemanticPointLabel data and combines the training data into the output datastores. 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"

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

Example: WriteLocation="C:\trainingData"

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

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.

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

  • "auto" — The function samples data sources with a factor of 1. 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

Set the sampling factor to 1 to create training data with all the point clouds in the input sequence.

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

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

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

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

collapse all

Point cloud datastore, returned as a fileDatastore object configured with pcread as the read function. Each call to read on this datastore returns a pointCloud object corresponding to a single frame.

To manually create an equivalent datastore for your own point cloud files, create a fileDatastore object by specifying ReadFcn=@pcread.

pcds = fileDatastore(location,ReadFcn=@pcread)

Semantic point label datastore, returned as a semanticPointLabelDatastore object. Each read from this datastore returns a categorical vector of per-point semantic labels corresponding to the point cloud frame from pcds. The class names and label IDs are derived from the LabelDefinitions property of the input gTruth object.

To create a datastore for training the network, combine the point cloud and semantic point label datastores by using combine(pcds, splds). Use the combined datastore to train deep learning networks for 3-D semantic segmentation, such as trainRandlanet.

Extended Capabilities

expand all

Version History

Introduced in R2026b

See Also

Objects

Functions

Apps

Topics