detectRectangularPlanePoints

Detect rectangular plane of specified dimensions in point cloud

Since R2020b

Syntax

ptCloudPlanes = detectRectangularPlanePoints(ptCloudIn,planeDimensions)

[ptCloudPlanes,ptCloudUsed] = detectRectangularPlanePoints(ptCloudArray,planeDimensions)

[___] = detectRectangularPlanePoints(ptCloudFileNames,planeDimensions)

[ptCloudPlanes,ptCloudUsed,indicesCell] = detectRectangularPlanePoints(___)

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

Description

ptCloudPlanes = detectRectangularPlanePoints(ptCloudIn,planeDimensions) detects and extracts a rectangular plane, ptCloudPlanes, of specified dimensions, planeDimensions, from the input point cloud ptCloudIn.

[ptCloudPlanes,ptCloudUsed] = detectRectangularPlanePoints(ptCloudArray,planeDimensions) detects rectangular planes from a set of point clouds, ptCloudArray. In addition, the function returns a logical vector, ptCloudUsed, that indicates the point clouds in which it detected a rectangular plane.

[___] = detectRectangularPlanePoints(ptCloudFileNames,planeDimensions) detects rectangular planes from a set of point cloud files, ptCloudFileNames, and returns any combination of output arguments from previous syntaxes.

[ptCloudPlanes,ptCloudUsed,indicesCell] = detectRectangularPlanePoints(___) returns indices to the points within the detected rectangular plane in each point cloud, in addition to any previous combination of arguments.

[___] = detectRectangularPlanePoints(___,Name,Value) specifies options using one or more name-value pair arguments. For example, 'RemoveGround',true sets the 'RemoveGround' flag to true, which removes the ground plane from the input point cloud before processing.

Examples

Detect Checkerboard Plane in Point Cloud

Load point cloud data into the workspace. Visualize the input point cloud.

ptCloud = pcread('pcCheckerboard.pcd');
pcshow(ptCloud)
title('Input Point Cloud')
xlim([-5 10])
ylim([-5 10])

Set the search dimensions for the rectangular plane.

boardSize = [729 810];

Search for the rectangular plane in the point cloud. Visualize the detected rectangular plane.

lidarCheckerboardPlane = detectRectangularPlanePoints(ptCloud,boardSize, ...
    'RemoveGround',true);
hRect = figure;
panel = uipanel('Parent',hRect,'BackgroundColor',[0 0 0]);
ax = axes('Parent',panel,'Color',[0 0 0]); 
pcshow(lidarCheckerboardPlane,'Parent',ax)
title('Rectangular Plane Points')

Visualize the detected rectangular plane on the input point cloud.

figure
pcshowpair(ptCloud,lidarCheckerboardPlane)
title('Detected Rectangular Plane')
xlim([-5 10])
ylim([-5 10])

Input Arguments

ptCloudIn — Point cloud

pointCloud object

Point cloud, specified as a pointCloud object. The function searches within this point cloud for a rectangular plane.

ptCloudArray — Point cloud array

array of pointCloud objects

Point cloud array, specified as a P-by-1 array of pointCloud objects. P is the number of pointCloud objects in the array. The function searches within each point cloud for a rectangular plane.

ptCloudFileNames — Point cloud file names

character vector | cell array of character vectors

Point cloud file names, specified as a character vector or cell array of character vectors. If specifying multiple file names, you must use a cell array of character vectors.

Data Types: char | cell

planeDimensions — Rectangular plane dimensions

two-element vector

Rectangular plane dimensions, specified as a two-element vector of positive real numbers. The elements specify the width and length of the rectangular plane respectively, in millimeters. The function searches the input point cloud for a plane with the same dimensions as planeDimensions.

Data Types: single | double

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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'RemoveGround',true sets the 'RemoveGround' flag to true, which removes the ground plane from the input point cloud before processing.

MinDistance — Clustering threshold for two adjacent points

0.5 (default) | positive scalar

Clustering threshold for two adjacent points, specified as the comma-separated pair consisting of 'MinDistance' and a positive scalar in meters. The clustering process is based on the Euclidean distance between adjacent points. If the distance between two adjacent points is less than the clustering threshold, both points belong to the same cluster. Low resolution lidars require higher 'MinDistance' threshold and vice-versa.

Note

This value should be greater than the minimum distance between two scan lines of the checkerboard. Too small value for 'MinDistance' might result in incorrect detections.

Data Types: single | double

ROI — Region of interest for detection

vector of form [xmin, xmax, ymin, ymax, zmin, zmax]

Region of interest (ROI) for detection, specified as the comma-separated pair consisting of 'ROI' and a vector of the form [xmin, xmax, ymin, ymax, zmin, zmax]. The vector specifies the x, y, and z limits of the ROI as the pairs xmin and xmax, ymin and ymax, zmin and zmax respectively.

Data Types: single | double

DimensionTolerance — Tolerance for uncertainty in rectangular plane dimensions

0.05 (default) | positive scalar in the range [0 1]

Tolerance for uncertainty in the rectangular plane dimensions, specified as the comma-separated pair consisting of 'DimensionTolerance' and a positive scalar in the range [0 1]. This value indicates the range of allowable deviation from the rectangular plane dimensions specified using the planeDimensions argument. For example, the minimum and maximum limits for the width of a rectangular plane are: [width−width*DimensionTolerance﹐width＋width*DimensionTolerance]. Therefore, a higher 'DimensionTolerance' indicates a wider range for the rectangular plane dimensions.

Data Types: single | double

RemoveGround — Remove ground plane from point cloud

false or 0 (default) | true or 1

Remove the ground plane from the point cloud, specified as the comma-separated pair consisting of 'RemoveGround' and a logical 0 (false) or 1 (true).

The normal of the plane is assumed to be aligned with the positive direction of the z-axis with the reference vector [0 0 1].

Data Types: logical

Verbose — Display function progress

false or 0 (default) | true or 1

Display function progress, specified as the comma-separated pair consisting of 'Verbose' and a logical 0 (false) or 1 (true).

Data Types: logical

Output Arguments

ptCloudPlanes — Detected rectangular planes

pointCloud object | 1-by-P array of pointCloud objects

Detected rectangular planes, returned as a pointCloud object or 1-by-P array of pointCloud objects, where P specifies the number of input point clouds in which a rectangular plane was detected.

ptCloudUsed — Pattern detection flag

1-by-N logical vector

Pattern detection flag, returned as a 1-by-N logical vector. N is the number of input point clouds. A true value indicates that the function detected a rectangular plane in the corresponding point cloud. A false value indicates that the function did not detect a rectangular plane.

indicesCell — Indices of detected rectangular planes

1-by-P cell array

Indices of detected rectangular planes, returned as a 1-by-P cell array, where P is the number of input point clouds in which a rectangular plane was detected. Each cell contains a logical vector that specifies the indices of the corresponding point cloud at which the function detected a rectangular plane. The indices can be used to extract the detected plane from the point cloud data.

Version History

Introduced in R2020b