pcsegdist

Segment point cloud into clusters based on Euclidean distance

Syntax

labels = pcsegdist(ptCloud,minDistance)

[labels,numClusters] = pcsegdist(ptCloud,minDistance)

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

Description

labels = pcsegdist(ptCloud,minDistance) segments a point cloud into clusters, with a minimum Euclidean distance of minDistance between points from different clusters. pcsegdist assigns an integer cluster label to each point in the point cloud, and returns the labels of all points.

[labels,numClusters] = pcsegdist(ptCloud,minDistance) also returns the number of clusters.

[___] = pcsegdist(___,Name=Value) sets properties using name-value arguments. For example, labels = pcsegdist(ptCloud,minDistance,NumClusterPoints=[1,Inf]) sets the minimum and maximum number of points in each cluster to [1,Inf].

Examples

Cluster Point Cloud Based on Euclidean Distance

Create two concentric spheres and combine them.

[X,Y,Z] = sphere(100);
loc1 = [X(:),Y(:),Z(:)];
loc2 = 2*loc1;
ptCloud = pointCloud([loc1;loc2]);
pcshow(ptCloud)
title('Point Cloud')

Set the minimum Euclidean distance between clusters.

minDistance = 0.5;

Segment the point cloud.

[labels,numClusters] = pcsegdist(ptCloud,minDistance);

Plot the labeled results. The points are grouped into two clusters.

pcshow(ptCloud.Location,labels)
colormap(hsv(numClusters))
title('Point Cloud Clusters')

Cluster Lidar Point Cloud Based on Euclidean Distance

Load an organized lidar point cloud to the workspace.

ld = load('drivingLidarPoints.mat');

Detect the ground plane. Distance is measured in meters.

maxDistance = 0.9;
referenceVector = [0 0 1];
[~,inliers,outliers] = pcfitplane(ld.ptCloud,maxDistance,referenceVector);

Remove the ground plane points.

ptCloudWithoutGround = select(ld.ptCloud,outliers);

Cluster the point cloud with a minimum of 10 points per cluster using the exhaustive method.

minDistance = 2;
minPoints = 10;
[labels,numClusters] = pcsegdist(ptCloudWithoutGround,minDistance,Method="exhaustive",...
    NumClusterPoints=minPoints);

Remove the points with a label value of 0.

idxValidPoints = find(labels);
labelColorIndex = labels(idxValidPoints);
segmentedPtCloud = select(ptCloudWithoutGround,idxValidPoints);

Plot the labeled results.

figure
colormap(hsv(numClusters))
pcshow(segmentedPtCloud.Location,labelColorIndex)
title('Point Cloud Clusters')

Input Arguments

ptCloud — Point cloud

pointCloud object

Point cloud, specified as a pointCloud object.

minDistance — Minimum Euclidean distance

positive scalar

Minimum Euclidean distance between points from two different clusters, specified as a positive scalar.

Data Types: single | double

Name-Value Arguments

Example: ParallelNeighborSearch=false sets the ParallelNeighborSearch to false.

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.

NumClusterPoints — Minimum and maximum number of points in each cluster

[1,Inf] (default) | 2-element vector | scalar

Minimum and maximum number of points in each cluster, specified as a scalar or a 2-element vector of the form [minPoints,maxPoints]. When you specify NumClusterPoints as a scalar, the maximum number of points in the cluster is unrestricted. The function sets labels to 0 when clusters are outside of the specified range.

Method — Method to segment the point cloud

"approximate" (default) | "exhaustive"

Method to segment the point cloud, specified as "approximate" or "exhaustive". Set Method to "exhaustive" to ensure that no points outside of each cluster are less than minDistance away. This approach uses the density-based spatial clustering of applications with noise (DBSCAN) algorithm. Set Method to "approximate" for faster segmentation, but at the expense of accuracy.

ParallelNeighborSearch — Parallel neighbor search to segment point cloud data

false (default) | true

Parallel neighbor search to segment point cloud data, specified as true or false. Set this property to true when you expect there to be approximately 50 clusters or more with fewer than 100 points per cluster.

A parallel neighbor search can improve segmentation speed for some datasets. Improved speed depends on the dataset and the value of the minDistance input. This argument is not supported when you set the Method name-value argument to "exhaustive".

Output Arguments

labels — Cluster labels

M-by-1 vector | M-by-N matrix

Cluster labels, returned as one of the following.

• If the point cloud, ptCloud, stores point locations as an unorganized M-by-3 matrix, then labels is an M-by-1 vector.

• If the point cloud, ptCloud, stores point locations as an organized M-by-N-by-3 matrix, then labels is an M-by-N matrix.

Each point in the point cloud has a cluster label, specified by the corresponding element in labels. The value of each label is an integer from 0 to the number of clusters of valid points, numClusters. The value 0 is reserved for invalid points, such as points with Inf or NaN coordinates.

Data Types: uint32

numClusters — Number of clusters

positive integer

Number of clusters, returned as a positive integer. The number of clusters excludes the label value 0, which is reserved for invalid points. The function returns numClusters as a single data type when the value of the Location property of the ptCloud object is single. Otherwise, the function returns the value as a double data type.

Data Types: single | double

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

The "exhaustive" segmentation method, which can be set by using the Method name-value argument, does not support C/C++ code generation.

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Usage notes and limitations:

• The generated CUDA^® code segments the point cloud into clusters by using a combination of algorithms described in [1] and [2]. The output from the generated code can differ slightly with results from MATLAB^® simulation.

• The NumClusterPoints name-value argument is not supported for GPU code generation.

• The "exhaustive" segmentation method, which can be set by using the Method name-value argument, does not support GPU code generation.

References

[1] Andrade, Guilherme, Gabriel Ramos, Daniel Madeira, Rafael Sachetto, Renato Ferreira, and Leonardo Rocha. “G-DBSCAN: A GPU Accelerated Algorithm for Density-Based Clustering.” Procedia Computer Science 18 (2013): 369–78. https://doi.org/10.1016/j.procs.2013.05.200.

[2] Kalentev, Oleksandr, Abha Rai, Stefan Kemnitz, and Ralf Schneider. “Connected Component Labeling on a 2D Grid Using CUDA.” Journal of Parallel and Distributed Computing 71, no. 4 (April 2011): 615–20. https://doi.org/10.1016/j.jpdc.2010.10.012.

Version History

Introduced in R2018a

R2024b: New Method name-value argument for segmenting point cloud

Configure the Method name-value argument to choose between "exhaustive" or "approximate" segmentation methods. The ParallelNeighborhood name-value argument does not support the "exhaustive" method.