pcdownsample

Downsample 3-D point cloud

Syntax

ptCloudOut = pcdownsample(ptCloudIn,"random",percentage)

ptCloudOut = pcdownsample(ptCloudIn,"gridAverage",gridStep)

ptCloudOut = pcdownsample(ptCloudIn,"gridNearest",gridStep)

ptCloudOut = pcdownsample(ptCloudIn,"nonuniformGridSample",maxNumPoints)

[ptCloudOut,indices] = pcdownsample(___)

___ = pcdownsample(___,Name=Value)

Description

ptCloudOut = pcdownsample(ptCloudIn,"random",percentage) returns a downsampled point cloud. Use this syntax for random sampling without replacement. The percentage input specifies the portion of the input to return to the output.

ptCloudOut = pcdownsample(ptCloudIn,"gridAverage",gridStep) returns a downsampled point cloud using a box grid filter. The gridStep input specifies the size of a 3-D box.

ptCloudOut = pcdownsample(ptCloudIn,"gridNearest",gridStep) returns a downsampled point cloud by selecting points closest to the centroid in each grid, using a box grid filter. The gridStep input specifies the size of a 3-D box.

ptCloudOut = pcdownsample(ptCloudIn,"nonuniformGridSample",maxNumPoints) returns a downsampled point cloud using nonuniform box grid filter. You must set the maximum number of points in the grid box, maxNumPoints, to at least 6.

[ptCloudOut,indices] = pcdownsample(___) returns the linear indices for the points that are included in the downsampled point cloud. This syntax applies only when you use the "random", "gridNearest", or "nonuniformGridSample" downsampling methods.

___ = pcdownsample(___,Name=Value) specifies options using one or more name-value arguments in addition to any combination of arguments from previous syntaxes. For example, pcdownsample(PtCloud,"random",percentage,PreserveStructure=true) preserves the organized structure of a point cloud.

Examples

Downsample Point Cloud Using Box Grid Filter

Read a point cloud.

ptCloud = pcread("teapot.ply");

Set the 3-D resolution to be (0.1 x 0.1 x 0.1).

gridStep = 0.1;
ptCloudA = pcdownsample(ptCloud,'gridAverage',gridStep);

Visualize the downsampled data.

figure
pcshow(ptCloudA);

Compare the point cloud to data that is downsampled using a fixed step size.

stepSize = floor(ptCloud.Count/ptCloudA.Count);
indices = 1:stepSize:ptCloud.Count;
ptCloudB = select(ptCloud,indices);

Visualize the downsampled point cloud.

figure
pcshow(ptCloudB);

Remove Redundant Points from Point Cloud

Create a point cloud with all points sharing the same coordinates.

ptCloud = pointCloud(ones(100,3));

Set the 3-D resolution to a small value.

gridStep = 0.01;

The output now contains only one unique point.

ptCloudOut = pcdownsample(ptCloud,'gridAverage',gridStep)

ptCloudOut = 
  pointCloud with properties:

     Location: [1 1 1]
        Count: 1
      XLimits: [1 1]
      YLimits: [1 1]
      ZLimits: [1 1]
        Color: [0×3 uint8]
       Normal: [0×3 double]
    Intensity: [0×1 double]

Preserve Organized Structure of Point Cloud After Downsampling

Load an organized point cloud from a saved MAT file.

ld = load('drivingLidarPoints.mat');
orgPtCloud = ld.ptCloud;

Downsample the point cloud. The output point cloud preserves the organized structure. Its location property is of size M-by-N-by-3.

gridStep = 2;
orgPtCloudOut = pcdownsample(orgPtCloud,'gridNearest',gridStep,PreserveStructure=true)

orgPtCloudOut = 
  pointCloud with properties:

     Location: [32×1083×3 double]
        Count: 34656
      XLimits: [-86.7523 90.5514]
      YLimits: [-85.8353 70.7870]
      ZLimits: [-8.2440 13.9009]
        Color: []
       Normal: []
    Intensity: [32×1083 double]

Visualize the downsampled point cloud.

figure
pcshow(orgPtCloudOut)

Input Arguments

ptCloudIn — Point cloud

pointCloud object

Point cloud, specified as a pointCloud object.

"random" — Random downsample method

"random"

Random downsample method, specified as "random". The "random" method is more efficient than the "gridAverage" downsample method, especially when it is applied before point cloud registration.

percentage — Percentage of input

nonnegative scalar

Percentage of input, specified as a nonnegative scalar in the range [0, 1]. The percentage input specifies the portion of the input for the function to return.

"gridAverage" — Grid average downsample method

"gridAverage"

Grid average downsample method, specified as "gridAverage". Points within the same voxel are merged to a single point in the output voxel. Their color and normal properties are averaged accordingly. This method preserves the shape of the point cloud better than the "random" downsample method.

The function computes the axis-aligned bounding box for the entire point cloud. The bounding box is divided into a grid of voxels of size specified by gridStep. Points within each voxel are merged by averaging their locations, colors, and normals.

"gridNearest" — Nearest to centroid downsample method

"gridNearest"

Nearest to centroid downsample method, specified as "gridNearest". Points are selected that are closest to the centroid in each voxel. Use the gridNearest downsampling technique to achieve a more precise depiction of color, intensity, and normal data in the downsampled point cloud.

The function computes the axis-aligned bounding box for the entire point cloud. The bounding box is divided into grid of voxels of size specified by gridStep.

gridStep — Size of 3-D box for grid filter

numeric value

Size of 3-D box for grid filter, specified as a numeric value. Increase the size of gridStep when there are not enough resources to construct a large fine-grained grid of voxels.

Data Types: single | double

"nonuniformGridSample" — Nonuniform grid sample method

"nonuniformGridSample"

Nonuniform grid sample method, specified as "nonuniformGridSample". When you use the "nonuniformGridSample" algorithm, the normals are computed on the original data prior to downsampling. The downsampled output preserves more accurate normals.

maxNumPoints — Maximum number of points in grid box

integer

Maximum number of points in grid voxel, specified as an integer greater than 6. The method randomly selects a single point from each voxel. If the normal was not provided in the input point cloud, this method automatically fills in the normal property in the ptCloudOut output.

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: PreserveStructure=true preserves the organized structure of a point cloud.

PreserveStructure — Preserve the organized structure of a point cloud

false (default) | true

Preserve the organized structure of a point cloud, specified as true or false. The table describes the point cloud structure according to the value of PreserveStructure.

PreserveStructure	The function returns
true	An organized, downsampled, point cloud. The Location property that describes the structure of the point cloud, contains an M-by-N-by-3 matrix. Points that are not selected in the downsampled point cloud are filled with NaN, and the corresponding color is set to [0 0 0]. To return an organized point cloud, the input must be an organized point cloud, and the downsampling method must be "random", "nonuniformGridSample", or "gridNearest".
false	An unorganized, downsampled, point cloud. The Location property that describes the structure of the point cloud, contains an M-by-3 matrix.

Output Arguments

ptCloudOut — Downsampled point cloud

pointCloud object

Downsampled point cloud, returned as a pointCloud object.

indices — Indices of points in the downsampled point cloud

N-element vector

Indices of points in the downsampled point cloud, returned as a N-element vector.

References

[1] Pomerleau, F., F. Colas, R. Siegwart, and S. Magnenat. “Comparing ICP variants on real-world data sets.” Autonomous Robots. Vol. 34, Issue 3, April 2013, pp. 133–148.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation

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

Usage notes and limitations:

• GPU code generation for nonuniform grid sample method is not optimized.

• For the random downsample method, GPU Coder™ uses the NVIDIA^® CUDA^® random library (cuRAND) to generate the random numbers. Because of architectural and implementation differences between the random number generators on the GPU and CPU, numerical verification does not always match.

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

• GPU code generation does not support the "gridNearest" method for downsampling point clouds.

Version History

Introduced in R2015a

R2025a: Generate C/C++ code for "gridNearest" method

The function now supports C/C++ code generation for the "gridNearest" method for downsampling point clouds.

R2024b: Specify gridNearest downsampling method

Use the gridNearest downsampling method, which selects the nearest point to the centroid of each grid.