libnabo 1.0.7
nabo.h
Go to the documentation of this file.
1/*
2
3Copyright (c) 2010--2011, Stephane Magnenat, ASL, ETHZ, Switzerland
4You can contact the author at <stephane at magnenat dot net>
5
6All rights reserved.
7
8Redistribution and use in source and binary forms, with or without
9modification, are permitted provided that the following conditions are met:
10 * Redistributions of source code must retain the above copyright
11 notice, this list of conditions and the following disclaimer.
12 * Redistributions in binary form must reproduce the above copyright
13 notice, this list of conditions and the following disclaimer in the
14 documentation and/or other materials provided with the distribution.
15 * Neither the name of the <organization> nor the
16 names of its contributors may be used to endorse or promote products
17 derived from this software without specific prior written permission.
18
19THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
20ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
21WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22DISCLAIMED. IN NO EVENT SHALL ETH-ASL BE LIABLE FOR ANY
23DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
24(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
26ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
28SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29
30*/
31
32#ifndef __NABO_H
33#define __NABO_H
34
35#include "Eigen/Core"
36#if EIGEN_VERSION_AT_LEAST(2,92,0)
37 #define EIGEN3_API
38#endif
39#ifndef EIGEN3_API
40 #include "Eigen/Array"
41#endif
42#include <vector>
43#include <map>
44#include "third_party/any.hpp"
45
205namespace Nabo
206{
208
209
211 #define NABO_VERSION "1.0.7"
213 #define NABO_VERSION_INT 10007
214
215 // TODO (c++14) Convert invalidIndex, invalidValue to constexpr templated variables.
216 template <typename IndexType>
217 inline constexpr IndexType invalidIndex() {
218 static_assert(std::is_integral<IndexType>::value, "");
219 return std::is_unsigned<IndexType>::value ? std::numeric_limits<IndexType>::max() : IndexType(-1);
220 }
221
222 template <typename ValueType>
223 inline constexpr ValueType invalidValue() {
224 static_assert(std::is_floating_point<ValueType>::value, "");
225 return std::numeric_limits<ValueType>::infinity();
226 }
227
229 //
230 // TODO: replace with C++17 std::any.
231 struct Parameters: public std::map<std::string, linb::any>
232 {
236
239 Parameters(const std::string& key, const linb::any& value){(*this)[key] = value;}
241
245 template<typename T>
246 T get(const std::string& key, const T& defaultValue) const
247 {
248 const_iterator it(find(key));
249 if (it != end())
250 return linb::any_cast<T>(it->second);
251 else
252 return defaultValue;
253 }
254 };
255
257 template<typename T, typename Cloud_T = Eigen::Matrix<T, Eigen::Dynamic, Eigen::Dynamic> >
259 {
261 typedef typename Eigen::Matrix<T, Eigen::Dynamic, 1> Vector;
263 typedef typename Eigen::Matrix<T, Eigen::Dynamic, Eigen::Dynamic> Matrix;
265 typedef Cloud_T CloudType;
267 typedef int Index;
269 typedef typename Eigen::Matrix<Index, Eigen::Dynamic, 1> IndexVector;
271 typedef typename Eigen::Matrix<Index, Eigen::Dynamic, Eigen::Dynamic> IndexMatrix;
272
276 const Index dim;
278 const unsigned creationOptionFlags;
283
285 static constexpr Index InvalidIndex = invalidIndex<Index>();
287 static constexpr T InvalidValue = invalidValue<T>();
288
291 {
299 };
300
303 {
305 };
306
309 {
311 SORT_RESULTS = 2
312 };
313
315
325 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;
326
328
338 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;
339
341
351 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;
352
354
360 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());
361
363
368 static NearestNeighbourSearch* createBruteForce(const CloudType& cloud, const Index dim = std::numeric_limits<Index>::max(), const unsigned creationOptionFlags = 0);
369
371
377 static NearestNeighbourSearch* createKDTreeLinearHeap(const CloudType& cloud, const Index dim = std::numeric_limits<Index>::max(), const unsigned creationOptionFlags = 0, const Parameters& additionalParameters = Parameters());
378
380
386 static NearestNeighbourSearch* createKDTreeTreeHeap(const CloudType& cloud, const Index dim = std::numeric_limits<Index>::max(), const unsigned creationOptionFlags = 0, const Parameters& additionalParameters = Parameters());
387
388
389
391 template <typename WrongMatrixType>
392 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())
393 {
394 typedef int Please_make_sure_that_the_decltype_of_the_first_parameter_is_equal_to_the_Matrix_typedef[sizeof(WrongMatrixType) > 0 ? -1 : 1];
395 Please_make_sure_that_the_decltype_of_the_first_parameter_is_equal_to_the_Matrix_typedef dummy;
396 return NULL;
397 }
398
400 template <typename WrongMatrixType>
401 static NearestNeighbourSearch* createBruteForce(const WrongMatrixType& cloud, const Index dim = std::numeric_limits<Index>::max(), const unsigned creationOptionFlags = 0)
402 {
403 typedef int Please_make_sure_that_the_decltype_of_the_first_parameter_is_equal_to_the_Matrix_typedef[sizeof(WrongMatrixType) > 0 ? -1 : 1];
404 Please_make_sure_that_the_decltype_of_the_first_parameter_is_equal_to_the_Matrix_typedef dummy;
405 return NULL;
406 }
407
409 template <typename WrongMatrixType>
410 static NearestNeighbourSearch* createKDTreeLinearHeap(const WrongMatrixType& cloud, const Index dim = std::numeric_limits<Index>::max(), const unsigned creationOptionFlags = 0, const Parameters& additionalParameters = Parameters())
411 {
412 typedef int Please_make_sure_that_the_decltype_of_the_first_parameter_is_equal_to_the_Matrix_typedef[sizeof(WrongMatrixType) > 0 ? -1 : 1];
413 Please_make_sure_that_the_decltype_of_the_first_parameter_is_equal_to_the_Matrix_typedef dummy;
414 return NULL;
415 }
416
418 template <typename WrongMatrixType>
419 static NearestNeighbourSearch* createKDTreeTreeHeap(const WrongMatrixType&, const Index dim = std::numeric_limits<Index>::max(), const unsigned creationOptionFlags = 0, const Parameters& additionalParameters = Parameters())
420 {
421 typedef int Please_make_sure_that_the_decltype_of_the_first_parameter_is_equal_to_the_Matrix_typedef[sizeof(WrongMatrixType) > 0 ? -1 : 1];
422 Please_make_sure_that_the_decltype_of_the_first_parameter_is_equal_to_the_Matrix_typedef dummy;
423 return NULL;
424 }
425
428
429 protected:
431 NearestNeighbourSearch(const CloudType& cloud, const Index dim, const unsigned creationOptionFlags);
432
434
440 void checkSizesKnn(const Matrix& query, const IndexMatrix& indices, const Matrix& dists2, const Index k, const unsigned optionFlags, const Vector* maxRadii = 0) const;
441 };
442
443 // Convenience typedefs
444
449
451}
452
453#endif // __NABO_H
Definition: any.hpp:36
Namespace for Nabo.
Definition: brute_force_cpu.cpp:41
NearestNeighbourSearch< float > NNSearchF
nearest neighbour search with scalars of type float
Definition: nabo.h:446
NearestNeighbourSearch< double > NNSearchD
nearest neighbour search with scalars of type double
Definition: nabo.h:448
Nearest neighbour search interface, templatized on scalar type.
Definition: nabo.h:259
static constexpr Index InvalidIndex
the invalid index
Definition: nabo.h:285
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 suppor...
Definition: nabo.h:419
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.
Definition: nabo.cpp:103
int Index
an index to a Vector or a Matrix, for refering to data points
Definition: nabo.h:267
SearchOptionFlags
search option
Definition: nabo.h:309
@ ALLOW_SELF_MATCH
allows the return of the same point as the query, if this point is in the data cloud; forbidden by de...
Definition: nabo.h:310
@ SORT_RESULTS
sort points by distances, when k > 1; do not sort by default
Definition: nabo.h:311
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)
Definition: nabo.cpp:166
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.
Definition: nabo.cpp:135
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)
Definition: nabo.cpp:174
Cloud_T CloudType
a column-major Eigen matrix in which each column is a point; this matrix has dim rows
Definition: nabo.h:265
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.
Definition: nabo.cpp:158
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 suppor...
Definition: nabo.h:392
const Vector maxBound
the high bound of the search space (axis-aligned bounding box)
Definition: nabo.h:282
const CloudType & cloud
the reference to the data-point cloud, which must remain valid during the lifetime of the NearestNeig...
Definition: nabo.h:274
const unsigned creationOptionFlags
creation options
Definition: nabo.h:278
CreationOptionFlags
creation option
Definition: nabo.h:303
@ TOUCH_STATISTICS
perform statistics on the number of points touched
Definition: nabo.h:304
Eigen::Matrix< Index, Eigen::Dynamic, 1 > IndexVector
a vector of indices to data points
Definition: nabo.h:269
static constexpr T InvalidValue
the invalid value
Definition: nabo.h:287
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.
const Index dim
the dimensionality of the data-point cloud
Definition: nabo.h:276
Eigen::Matrix< Index, Eigen::Dynamic, Eigen::Dynamic > IndexMatrix
a matrix of indices to data points
Definition: nabo.h:271
virtual ~NearestNeighbourSearch()
virtual destructor
Definition: nabo.h:427
const Vector minBound
the low bound of the search space (axis-aligned bounding box)
Definition: nabo.h:280
SearchType
type of search
Definition: nabo.h:291
@ KDTREE_CL_PT_IN_LEAVES
kd-tree using openCL, pt in leaves, only available if OpenCL enabled, UNSTABLE API
Definition: nabo.h:296
@ KDTREE_LINEAR_HEAP
kd-tree with linear heap, good for small k (~up to 30)
Definition: nabo.h:293
@ KDTREE_CL_PT_IN_NODES
kd-tree using openCL, pt in nodes, only available if OpenCL enabled, UNSTABLE API
Definition: nabo.h:295
@ BRUTE_FORCE_CL
brute-force using openCL, only available if OpenCL enabled, UNSTABLE API
Definition: nabo.h:297
@ SEARCH_TYPE_COUNT
number of search types
Definition: nabo.h:298
@ KDTREE_TREE_HEAP
kd-tree with tree heap, good for large k (~from 30)
Definition: nabo.h:294
@ BRUTE_FORCE
brute force, check distance to every point in the data
Definition: nabo.h:292
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 suppor...
Definition: nabo.h:410
Eigen::Matrix< T, Eigen::Dynamic, 1 > Vector
an Eigen vector of type T, to hold the coordinates of a point
Definition: nabo.h:261
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
Definition: nabo.h:263
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.
Definition: nabo.cpp:83
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 suppor...
Definition: nabo.h:401
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.
Parameter vector.
Definition: nabo.h:232
T get(const std::string &key, const T &defaultValue) const
Get the value of a key, return defaultValue if the key does not exist.
Definition: nabo.h:246
Parameters(const std::string &key, const linb::any &value)
Create a parameter vector with a single entry.
Definition: nabo.h:239
Parameters()
Create an empty parameter vector.
Definition: nabo.h:234