pcdownsample

Downsample 3-D point cloud

collapse all in page

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.

example

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

collapse all

Open Live Script

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);

Figure contains an axes object. The axes object contains an object of type scatter.

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);

Figure contains an axes object. The axes object contains an object of type scatter.

Open Live Script

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]
Open Live Script

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)

Figure contains an axes object. The axes object contains an object of type scatter.

Input Arguments

collapse all

Point cloud, specified as a pointCloud object.

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 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.

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.

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.

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

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.

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

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.

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.

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.

PreserveStructureThe 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

collapse all

Downsampled point cloud, returned as a pointCloud object.

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

expand all

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

Version History

Introduced in R2015a

expand all

See Also

Functions

Objects

Topics