segmentObjects

Segment point cloud using RandLA-Net semantic segmentation

Since R2024a

Syntax

labels = segmentObjects(segmenter,ptCloud)

[labels,scores] = segmentObjects(segmenter,ptCloud)

plds = segmentObjects(segmenter,ds)

[___] = segmentObjects(___,Name=Value)

Description

labels = segmentObjects(segmenter,ptCloud) segments the point cloud ptCloud using the trained RandLA-Net network segmenter and returns the labels of all points in the point cloud.

[labels,scores] = segmentObjects(segmenter,ptCloud) returns the segmentation confidence score for each point in the point cloud. Each confidence score is in the range of [0, 1] and a higher score indicates greater confidence in the segmentation.

plds = segmentObjects(segmenter,ds) segments each point cloud in the datastore ds and returns the segmentation results in the datastore plds.

[___] = segmentObjects(___,Name=Value) specifies options using one or more name-value arguments in addition to any combination of arguments from previous syntaxes. For example, segmentObjects(segmenter,ptCloud,ExecutionEnvironment="gpu") utilizes a GPU for processing, if available.

Examples

Segment Large Point Cloud Using RandLA-Net Deep Learning

Read a point cloud to segment from a LAS file into the workspace.

filename = fullfile(toolboxdir("lidar"),"lidardata","las","aerialLidarData.laz");
lasReader = lasFileReader(filename);
ptCloud = readPointCloud(lasReader);

Visualize the point cloud.

figure
pcshow(ptCloud)
title("Point Cloud")
axis off

For efficient memory processing, divide the point cloud into small, non-overlapping blocks. Create a blocked point cloud by specifying the block size.

bpc = blockedPointCloud(ptCloud,[50 50]);

Create a blocked point cloud datastore that contains the blocked point cloud.

bpcds = blockedPointCloudDatastore(bpc);

Create a pretrained RandLA-Net semantic segmentation network trained on the Dayton Annotated Lidar Earth Scan (DALES) data set.

segmenter = randlanet("dales") 

segmenter = 
  randlanet with properties:

         GridStep: 0.0400
          Network: [1×1 dlnetwork]
       ClassNames: [ground    vegetation    cars    trucks    powerlines    fences    poles    buildings]
        NumPoints: 45056
    PointProperty: {'location'}
        ModelName: 'dales'

classNames = cellstr(segmenter.ClassNames);
numClasses = numel(classNames);

Initialize empty placeholders for predictions.

labels = [];
pc = [];

Segment the large point cloud using the pretrained network.

while hasdata(bpcds)
    % Read a block of the point cloud.
    ptCloudBlock = read(bpcds);
    % Get the output predictions.
    labelsBlock = segmentObjects(segmenter,ptCloudBlock{1});
    % Concatenate the predicted labels from the blocks.
    labels = vertcat(labels,labelsBlock);
    % Concatenate the blocks of the point cloud to form a point cloud array for visualization.
    pc = [pc; ptCloudBlock{1}];
end

Convert the labels from categorical to numeric values for ease of visualization.

labels = single(categorical(labels,segmenter.ClassNames,cellstr(string(1:numClasses))));

Concatenate the point clouds in the point cloud array.

pc = pccat(pc);

Visualize the segmentation by displaying the labels.

figure
ax = pcshow(pc.Location,labels);
title("Semantic Segmentation of Point Cloud")
helperLabelColorbar(ax,classNames)

Supporting Function

function helperLabelColorbar(ax,classNames)

numClasses = numel(classNames);
% Colormap for the original classes.
cmap = [[0 0 255];     % ground
        [0 255 0];     % vegetation
        [255 192 203]; % cars
        [255 255 0];   % trucks
        [255 0 255];   % powerlines
        [255 165 0];   % fences
        [139 0 150];   % poles
        [255 0 0]];    % buildings
 
cmap = cmap./255;
cmap = cmap(1:numClasses,:);
colormap(ax,cmap);
 
% Add colorbar to current figure.
c = colorbar(ax);
c.Color = "white";
 
% Center tick labels and use class names for tick marks.
c.Ticks = 1:1:numClasses;
c.TickLabels = classNames;
 
% Remove tick mark.
c.TickLength = 0;

end

Input Arguments

segmenter — RandLA-Net semantic segmentation network

randlanet object

RandLA-Net semantic segmentation network, specified as a randlanet object. The network must be a trained network.

ptCloud — Input point cloud

pointCloud object | array of pointCloud objects | cell array of pointCloud objects

Input point cloud, specified as a pointCloud object, an array of pointCloud objects, or a cell array of pointCloud objects. The point clouds can be unorganized or organized.

ds — Datastore of point clouds

valid datastore object

Datastore of point clouds, specified as a valid datastore object. The datastore must be set up such that using the read function on the datastore object returns a cell array of point clouds. For more information on creating datastore objects, see the datastore function.

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: segmentObjects(segmenter,ptCloud,ExecutionEnvironment="gpu") utilizes a GPU for processing, if available.

ExecutionEnvironment — Hardware resource for execution

"auto" (default) | "gpu" | "cpu"

Hardware resource for execution, specified as "auto", "gpu", or "cpu". Using a GPU execution environment requires the Parallel Computing Toolbox™ and a CUDA^® enabled NVIDIA^® GPU. For more information about the supported capabilities, see GPU Computing Requirements (Parallel Computing Toolbox).

Execution Environment	Description
"auto"	Use a GPU if available, otherwise use the CPU.
"gpu"	Use the GPU. If a suitable GPU is not available, the function returns an error message.
"cpu"	Use the CPU.

Data Types: char | string

Acceleration — Performance optimization

"auto" (default) | "none"

Performance optimization, specified as "auto" or "none".

Acceleration	Description
"auto"	Automatically selects the optimizations suitable for the input network and environment. These optimizations improve performance at the expense of some overhead on the first call and possible additional memory usage.
"none"	Turns off all acceleration.

Data Types: char | string

WriteLocation — Folder location to write segmentation results

fullfile(pwd,"SegmentObjectResults") (default) | string scalar | character vector

Folder location to write segmentation results, specified as a string scalar or character vector. The specified folder must exist and have write permissions.

Note

This argument is applicable only when the input is a datastore ds. Otherwise, the function ignores this argument.

Data Types: char | string

NamePrefix — Prefix for segmentation result filenames

"segmentObj" (default) | string scalar | character vector

Prefix for segmentation result filenames, specified as a string scalar or character vector. The name of a segmentation result file is NamePrefix_<i>.mat, where <i> is the index of the corresponding point cloud in the input datastore ds.

Note

This argument is applicable only when the input is a datastore ds. Otherwise, the function ignores this argument.

Data Types: char | string

Verbose — Progress information display

true or 1 (default) | false or 0

Progress information display, specified as a logical 1 (true) or l0 (false).

Note

This argument is applicable only when the input is a datastore ds. Otherwise, the function ignores this argument.

Data Types: logical

Output Arguments

labels — Segmentation labels

categorical array | cell array

Segmentation labels, returned as a categorical array or cell array. The format of labels depends on the input ptCloud.

Input Point Cloud ptCloud	Segmentation Labels labels
Unorganized point cloud with M points	M-by-1 categorical vector.
Organized point cloud with M-by-N points	M-by-N categorical matrix.
B-by-1 array or cell array of B point clouds	B-by-1 cell array, where each cell is an M-by-1 categorical vector or M-by-N categorical matrix, depending on whether the input point clouds are unorganized or organized, respectively.

scores — Segmentation confidence score

numeric array | cell array

Segmentation confidence scores, returned as a numeric array or cell array. The function returns the segmentation confidence score for each point in the point cloud. The value of the confidence score is in the range of [0, 1]. A higher score indicates greater confidence in the segmentation. The format of scores depends on the input ptCloud.

Input Point Cloud ptCloud	Segmentation Confidence Score scores
Unorganized point cloud with M points	M-by-1 numeric vector.
Organized point cloud with M-by-N points	M-by-N numeric matrix.
B-by-1 array or cell array of B point clouds	B-by-1 cell array, where each cell is an M-by-1 numeric vector or M-by-N numeric matrix, depending on whether the input point clouds are unorganized or organized, respectively.

plds — Segmentation results for datastore

fileDatastore object

Segmentation results for the datastore, returned as a fileDatastore object. The function saves the segmentation result of each point cloud as a MAT file. Use the read function on this output to obtain the labels for each point cloud in ds. You can evaluate the segmentation plds using the evaluateSemanticSegmentation function.

Version History

Introduced in R2024a