findNearestNeighbors

R2026b

Find nearest neighbors of a point in point cloud

Syntax

[indices,dists] = findNearestNeighbors(ptCloud,point,K)

[indices,dists] = findNearestNeighbors(___,Name,Value)

Description

[indices,dists] = findNearestNeighbors(ptCloud,point,K) returns the indices for the K-nearest neighbors of a query point in the input point cloud. ptCloud can be an unorganized or organized point cloud. The K-nearest neighbors of the query point are computed by using the Kd-tree based search algorithm. This function requires a Computer Vision Toolbox™ license.

Note

The object functions of the pointCloud object require Point Cloud Toolbox™

[indices,dists] = findNearestNeighbors(___,Name,Value) specifies options using one or more name-value arguments in addition to the input arguments in the preceding syntaxes.

Input Arguments

ptCloud — Point cloud

pointCloud object

Point cloud, specified as a pointCloud object.

point — Query point

three-element vector of form [x y z]

Query point, specified as a three-element vector of form [x y z].

K — Number of nearest neighbors

positive integer

Number of nearest neighbors, specified as a positive integer.

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: findNearestNeighbors(ptCloud,point,k,'Sort',true)

Sort — Sort indices

false (default) | true

Sort indices, specified as a comma-separated pair of 'Sort' and a logical scalar. When you set Sort to true, the returned indices are sorted in the ascending order based on the distance from a query point. To turn off sorting, set Sort to false.

MaxLeafChecks — Number of leaf nodes to check

Inf (default) | integer

Number of leaf nodes to check, specified as a comma-separated pair consisting of 'MaxLeafChecks' and an integer. When you set this value to Inf, the entire tree is searched. When the entire tree is searched, it produces exact search results. Increasing the number of leaf nodes to check increases accuracy, but reduces efficiency.

Note

The name-value argument 'MaxLeafChecks' is valid only with Kd-tree based search method.

Output Arguments

indices — Indices of stored points

column vector

Indices of stored points, returned as a column vector. The vector contains K linear indices of the nearest neighbors stored in the point cloud.

dists — Distances to query point

column vector

Distances to query point, returned as a column vector. The vector contains the Euclidean distances between the query point and its nearest neighbors.

References

[1] Muja, M. and David G. Lowe. "Fast Approximate Nearest Neighbors with Automatic Algorithm Configuration". In VISAPP International Conference on Computer Vision Theory and Applications. 2009. pp. 331–340.

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• For code generation in non-host platforms, the value for 'MaxLeafChecks' must be set to the default value Inf. If you specify values other than Inf, the function generates a warning and automatically assigns the default value for 'MaxLeafChecks'.

GPU Code Generation

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

Usage notes and limitations:

• For GPU code generation, the 'MaxLeafChecks' name-value pair option is ignored.

Version History

Introduced in R2020b

R2026b: Point cloud features require Point Cloud Toolbox

Toolbox requirement to use findNearestNeighbors object function changed from Computer Vision Toolbox to Point Cloud Toolbox.