Nearest neighbour search interface, templatized on scalar type. More...

#include <nabo.h>

Inheritance diagram for Nabo::NearestNeighbourSearch< T, Cloud_T >:

Public Types
enum	SearchType { BRUTE_FORCE = 0 , KDTREE_LINEAR_HEAP , KDTREE_TREE_HEAP , KDTREE_CL_PT_IN_NODES , KDTREE_CL_PT_IN_LEAVES , BRUTE_FORCE_CL , SEARCH_TYPE_COUNT }
	type of search More...

enum	CreationOptionFlags { TOUCH_STATISTICS = 1 }
	creation option More...

enum	SearchOptionFlags { ALLOW_SELF_MATCH = 1 , SORT_RESULTS = 2 }
	search option More...

typedef Eigen::Matrix< T, Eigen::Dynamic, 1 >	Vector
	an Eigen vector of type T, to hold the coordinates of a point

typedef Eigen::Matrix< T, Eigen::Dynamic, Eigen::Dynamic >	Matrix
	a column-major Eigen matrix in which each column is a point; this matrix has dim rows

typedef Cloud_T	CloudType
	a column-major Eigen matrix in which each column is a point; this matrix has dim rows

typedef int	Index
	an index to a Vector or a Matrix, for refering to data points

typedef Eigen::Matrix< Index, Eigen::Dynamic, 1 >	IndexVector
	a vector of indices to data points

typedef Eigen::Matrix< Index, Eigen::Dynamic, Eigen::Dynamic >	IndexMatrix
	a matrix of indices to data points

Public Member Functions
unsigned long	knn (const Vector &query, IndexVector &indices, Vector &dists2, const Index k=1, const T epsilon=0, const unsigned optionFlags=0, const T maxRadius=std::numeric_limits< T >::infinity()) const
	Find the k nearest neighbours of query.

virtual unsigned long	knn (const Matrix &query, IndexMatrix &indices, Matrix &dists2, const Index k=1, const T epsilon=0, const unsigned optionFlags=0, const T maxRadius=std::numeric_limits< T >::infinity()) const =0
	Find the k nearest neighbours for each point of query.

virtual unsigned long	knn (const Matrix &query, IndexMatrix &indices, Matrix &dists2, const Vector &maxRadii, const Index k=1, const T epsilon=0, const unsigned optionFlags=0) const =0
	Find the k nearest neighbours for each point of query.

virtual	~NearestNeighbourSearch ()
	virtual destructor

Static Public Member Functions
static NearestNeighbourSearch *	create (const CloudType &cloud, const Index dim=std::numeric_limits< Index >::max(), const SearchType preferedType=KDTREE_LINEAR_HEAP, const unsigned creationOptionFlags=0, const Parameters &additionalParameters=Parameters())
	Create a nearest-neighbour search.

static NearestNeighbourSearch *	createBruteForce (const CloudType &cloud, const Index dim=std::numeric_limits< Index >::max(), const unsigned creationOptionFlags=0)
	Create a nearest-neighbour search, using brute-force search, useful for comparison only.

static NearestNeighbourSearch *	createKDTreeLinearHeap (const CloudType &cloud, const Index dim=std::numeric_limits< Index >::max(), const unsigned creationOptionFlags=0, const Parameters &additionalParameters=Parameters())
	Create a nearest-neighbour search, using a kd-tree with linear heap, good for small k (~up to 30)

static NearestNeighbourSearch *	createKDTreeTreeHeap (const CloudType &cloud, const Index dim=std::numeric_limits< Index >::max(), const unsigned creationOptionFlags=0, const Parameters &additionalParameters=Parameters())
	Create a nearest-neighbour search, using a kd-tree with tree heap, good for large k (~from 30)

template<typename WrongMatrixType>
static NearestNeighbourSearch *	create (const WrongMatrixType &cloud, const Index dim=std::numeric_limits< Index >::max(), const SearchType preferedType=KDTREE_LINEAR_HEAP, const unsigned creationOptionFlags=0, const Parameters &additionalParameters=Parameters())
	Prevent creation of trees with the wrong matrix type. Currently only dynamic size matrices are supported.

template<typename WrongMatrixType>
static NearestNeighbourSearch *	createBruteForce (const WrongMatrixType &cloud, const Index dim=std::numeric_limits< Index >::max(), const unsigned creationOptionFlags=0)
	Prevent creation of trees with the wrong matrix type. Currently only dynamic size matrices are supported.

template<typename WrongMatrixType>
static NearestNeighbourSearch *	createKDTreeLinearHeap (const WrongMatrixType &cloud, const Index dim=std::numeric_limits< Index >::max(), const unsigned creationOptionFlags=0, const Parameters &additionalParameters=Parameters())
	Prevent creation of trees with the wrong matrix type. Currently only dynamic size matrices are supported.

template<typename WrongMatrixType>
static NearestNeighbourSearch *	createKDTreeTreeHeap (const WrongMatrixType &, const Index dim=std::numeric_limits< Index >::max(), const unsigned creationOptionFlags=0, const Parameters &additionalParameters=Parameters())
	Prevent creation of trees with the wrong matrix type. Currently only dynamic size matrices are supported.

Public Attributes
const CloudType &	cloud
	the reference to the data-point cloud, which must remain valid during the lifetime of the NearestNeighbourSearch object

const Index	dim
	the dimensionality of the data-point cloud

const unsigned	creationOptionFlags
	creation options

const Vector	minBound
	the low bound of the search space (axis-aligned bounding box)

const Vector	maxBound
	the high bound of the search space (axis-aligned bounding box)

Static Public Attributes
static constexpr Index	InvalidIndex = invalidIndex<Index>()
	the invalid index

static constexpr T	InvalidValue = invalidValue<T>()
	the invalid value

Protected Member Functions
	NearestNeighbourSearch (const CloudType &cloud, const Index dim, const unsigned creationOptionFlags)
	constructor

void	checkSizesKnn (const Matrix &query, const IndexMatrix &indices, const Matrix &dists2, const Index k, const unsigned optionFlags, const Vector *maxRadii=0) const
	Make sure that the output matrices have the right sizes. Throw an exception otherwise.

Detailed Description

template<typename T, typename Cloud_T = Eigen::Matrix<T, Eigen::Dynamic, Eigen::Dynamic>>
struct Nabo::NearestNeighbourSearch< T, Cloud_T >

Nearest neighbour search interface, templatized on scalar type.

Member Enumeration Documentation

◆ CreationOptionFlags

template<typename T, typename Cloud_T = Eigen::Matrix<T, Eigen::Dynamic, Eigen::Dynamic>>

enum Nabo::NearestNeighbourSearch::CreationOptionFlags

creation option

Enumerator
TOUCH_STATISTICS	perform statistics on the number of points touched

◆ SearchOptionFlags

template<typename T, typename Cloud_T = Eigen::Matrix<T, Eigen::Dynamic, Eigen::Dynamic>>

enum Nabo::NearestNeighbourSearch::SearchOptionFlags

search option

Enumerator
ALLOW_SELF_MATCH	allows the return of the same point as the query, if this point is in the data cloud; forbidden by default
SORT_RESULTS	sort points by distances, when k > 1; do not sort by default

◆ SearchType

template<typename T, typename Cloud_T = Eigen::Matrix<T, Eigen::Dynamic, Eigen::Dynamic>>

enum Nabo::NearestNeighbourSearch::SearchType

type of search

Enumerator
BRUTE_FORCE	brute force, check distance to every point in the data
KDTREE_LINEAR_HEAP	kd-tree with linear heap, good for small k (~up to 30)
KDTREE_TREE_HEAP	kd-tree with tree heap, good for large k (~from 30)
KDTREE_CL_PT_IN_NODES	kd-tree using openCL, pt in nodes, only available if OpenCL enabled, UNSTABLE API
KDTREE_CL_PT_IN_LEAVES	kd-tree using openCL, pt in leaves, only available if OpenCL enabled, UNSTABLE API
BRUTE_FORCE_CL	brute-force using openCL, only available if OpenCL enabled, UNSTABLE API
SEARCH_TYPE_COUNT	number of search types

Member Function Documentation

◆ checkSizesKnn()

template<typename T, typename CloudType>

void Nabo::NearestNeighbourSearch< T, CloudType >::checkSizesKnn	(	const Matrix &	query,
		const IndexMatrix &	indices,
		const Matrix &	dists2,
		const Index	k,
		const unsigned	optionFlags,
		const Vector *	maxRadii = 0 ) const

protected

Make sure that the output matrices have the right sizes. Throw an exception otherwise.

Parameters

query	query points
k	number of nearest neighbour requested
indices	indices of nearest neighbours, must be of size k x query.cols()
dists2	squared distances to nearest neighbours, must be of size k x query.cols()
optionFlags	the options passed to knn()
maxRadii	if non 0, maximum radii, must be of size k

◆ create()

template<typename T, typename CloudType>

NearestNeighbourSearch< T, CloudType > * Nabo::NearestNeighbourSearch< T, CloudType >::create	(	const CloudType &	cloud,
		const Index	dim = std::numeric_limits<Index>::max(),
		const SearchType	preferedType = KDTREE_LINEAR_HEAP,
		const unsigned	creationOptionFlags = 0,
		const Parameters &	additionalParameters = Parameters() )

static

Create a nearest-neighbour search.

Parameters

cloud	data-point cloud in which to search
dim	number of dimensions to consider, must be lower or equal to cloud.rows()
preferedType	type of search, one of SearchType
creationOptionFlags	creation options, a bitwise OR of elements of CreationOptionFlags
additionalParameters	additional parameters, currently only useful for KDTREE_

Returns: an object on which to run nearest neighbour queries

◆ createBruteForce()

template<typename T, typename CloudType>

NearestNeighbourSearch< T, CloudType > * Nabo::NearestNeighbourSearch< T, CloudType >::createBruteForce	(	const CloudType &	cloud,
		const Index	dim = std::numeric_limits<Index>::max(),
		const unsigned	creationOptionFlags = 0 )

static

Create a nearest-neighbour search, using brute-force search, useful for comparison only.

This is an helper function, you can also use create() with BRUTE_FORCE as preferedType

Parameters

cloud	data-point cloud in which to search
dim	number of dimensions to consider, must be lower or equal to cloud.rows()
creationOptionFlags	creation options, a bitwise OR of elements of CreationOptionFlags

Returns: an object on which to run nearest neighbour queries

◆ createKDTreeLinearHeap()

template<typename T, typename CloudType>

NearestNeighbourSearch< T, CloudType > * Nabo::NearestNeighbourSearch< T, CloudType >::createKDTreeLinearHeap	(	const CloudType &	cloud,
		const Index	dim = std::numeric_limits<Index>::max(),
		const unsigned	creationOptionFlags = 0,
		const Parameters &	additionalParameters = Parameters() )

static

Create a nearest-neighbour search, using a kd-tree with linear heap, good for small k (~up to 30)

This is an helper function, you can also use create() with KDTREE_LINEAR_HEAP as preferedType

Parameters

cloud	data-point cloud in which to search
dim	number of dimensions to consider, must be lower or equal to cloud.rows()
creationOptionFlags	creation options, a bitwise OR of elements of CreationOptionFlags
additionalParameters	additional parameters

Returns: an object on which to run nearest neighbour queries

◆ createKDTreeTreeHeap()

template<typename T, typename CloudType>

NearestNeighbourSearch< T, CloudType > * Nabo::NearestNeighbourSearch< T, CloudType >::createKDTreeTreeHeap	(	const CloudType &	cloud,
		const Index	dim = std::numeric_limits<Index>::max(),
		const unsigned	creationOptionFlags = 0,
		const Parameters &	additionalParameters = Parameters() )

static

Create a nearest-neighbour search, using a kd-tree with tree heap, good for large k (~from 30)

This is an helper function, you can also use create() with KDTREE_TREE_HEAP as preferedType

Parameters

cloud	data-point cloud in which to search
dim	number of dimensions to consider, must be lower or equal to cloud.rows()
creationOptionFlags	creation options, a bitwise OR of elements of CreationOptionFlags
additionalParameters	additional parameters

Returns: an object on which to run nearest neighbour queries

◆ knn() [1/3]

template<typename T, typename Cloud_T = Eigen::Matrix<T, Eigen::Dynamic, Eigen::Dynamic>>

virtual unsigned long Nabo::NearestNeighbourSearch< T, Cloud_T >::knn	(	const Matrix &	query,
		IndexMatrix &	indices,
		Matrix &	dists2,
		const Index	k = 1,
		const T	epsilon = 0,
		const unsigned	optionFlags = 0,
		const T	maxRadius = std::numeric_limits< T >::infinity() ) const

pure virtual

Find the k nearest neighbours for each point of query.

If the search finds less than k points, the empty entries in dists2 will be filled with InvalidValue and the indices with InvalidIndex.

Parameters

query	query points
indices	indices of nearest neighbours, must be of size k x query.cols()
dists2	squared distances to nearest neighbours, must be of size k x query.cols()
k	number of nearest neighbour requested
epsilon	maximal ratio of error for approximate search, 0 for exact search; has no effect if the number of neighbour found is smaller than the number requested
optionFlags	search options, a bitwise OR of elements of SearchOptionFlags
maxRadius	maximum radius in which to search, can be used to prune search, is not affected by epsilon

Returns: if creationOptionFlags contains TOUCH_STATISTICS, return the number of point touched, otherwise return 0

Implemented in Nabo::BruteForceSearch< T, CloudType >, Nabo::KDTreeUnbalancedPtInLeavesImplicitBoundsStackOpt< T, Heap, CloudType >, Nabo::OpenCLSearch< T, CloudType >, and Nabo::OpenCLSearch< T, Eigen::Matrix< T, Eigen::Dynamic, Eigen::Dynamic > >.

◆ knn() [2/3]

template<typename T, typename Cloud_T = Eigen::Matrix<T, Eigen::Dynamic, Eigen::Dynamic>>

virtual unsigned long Nabo::NearestNeighbourSearch< T, Cloud_T >::knn	(	const Matrix &	query,
		IndexMatrix &	indices,
		Matrix &	dists2,
		const Vector &	maxRadii,
		const Index	k = 1,
		const T	epsilon = 0,
		const unsigned	optionFlags = 0 ) const

pure virtual

Find the k nearest neighbours for each point of query.

If the search finds less than k points, the empty entries in dists2 will be filled with InvalidValue and the indices with InvalidIndex.

Parameters

query	query points
indices	indices of nearest neighbours, must be of size k x query.cols()
dists2	squared distances to nearest neighbours, must be of size k x query.cols()
maxRadii	vector of maximum radii in which to search, used to prune search, is not affected by epsilon
k	number of nearest neighbour requested
epsilon	maximal ratio of error for approximate search, 0 for exact search; has no effect if the number of neighbour found is smaller than the number requested
optionFlags	search options, a bitwise OR of elements of SearchOptionFlags

Returns: if creationOptionFlags contains TOUCH_STATISTICS, return the number of point touched, otherwise return 0

Implemented in Nabo::BruteForceSearch< T, CloudType >, Nabo::KDTreeUnbalancedPtInLeavesImplicitBoundsStackOpt< T, Heap, CloudType >, Nabo::OpenCLSearch< T, CloudType >, and Nabo::OpenCLSearch< T, Eigen::Matrix< T, Eigen::Dynamic, Eigen::Dynamic > >.

◆ knn() [3/3]

template<typename T, typename CloudType>

unsigned long Nabo::NearestNeighbourSearch< T, CloudType >::knn	(	const Vector &	query,
		IndexVector &	indices,
		Vector &	dists2,
		const Index	k = 1,
		const T	epsilon = 0,
		const unsigned	optionFlags = 0,
		const T	maxRadius = std::numeric_limits<T>::infinity() ) const

Find the k nearest neighbours of query.

If the search finds less than k points, the empty entries in dists2 will be filled with InvalidValue and the indices with InvalidIndex. If you must query more than one point at once, use the version of the knn() function taking matrices as input, because it is much faster.

Parameters

query	query point
indices	indices of nearest neighbours, must be of size k
dists2	squared distances to nearest neighbours, must be of size k
k	number of nearest neighbour requested
epsilon	maximal ratio of error for approximate search, 0 for exact search; has no effect if the number of neighbour found is smaller than the number requested
optionFlags	search options, a bitwise OR of elements of SearchOptionFlags
maxRadius	maximum radius in which to search, can be used to prune search, is not affected by epsilon

Returns: if creationOptionFlags contains TOUCH_STATISTICS, return the number of point touched, otherwise return 0

The documentation for this struct was generated from the following files:

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ CreationOptionFlags

◆ SearchOptionFlags

◆ SearchType

Member Function Documentation

◆ checkSizesKnn()

◆ create()

◆ createBruteForce()

◆ createKDTreeLinearHeap()

◆ createKDTreeTreeHeap()

◆ knn() [1/3]

◆ knn() [2/3]

◆ knn() [3/3]