libnabo  1.0.4
nabo.h
Go to the documentation of this file.
1 /*
2 
3 Copyright (c) 2010--2011, Stephane Magnenat, ASL, ETHZ, Switzerland
4 You can contact the author at <stephane at magnenat dot net>
5 
6 All rights reserved.
7 
8 Redistribution and use in source and binary forms, with or without
9 modification, 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 
19 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
20 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
21 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22 DISCLAIMED. IN NO EVENT SHALL ETH-ASL BE LIABLE FOR ANY
23 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
24 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
26 ON 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
28 SOFTWARE, 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 <boost/any.hpp>
45 
206 namespace Nabo
208 {
210 
211 
213  #define NABO_VERSION "1.0.4"
214  #define NABO_VERSION_INT 10004
216 
218  struct Parameters: public std::map<std::string, boost::any>
219  {
223 
226  Parameters(const std::string& key, const boost::any& value){(*this)[key] = value;}
228 
232  template<typename T>
233  T get(const std::string& key, const T& defaultValue) const
234  {
235  const_iterator it(find(key));
236  if (it != end())
237  return boost::any_cast<T>(it->second);
238  else
239  return defaultValue;
240  }
241  };
242 
244  template<typename T>
246  {
248  typedef typename Eigen::Matrix<T, Eigen::Dynamic, 1> Vector;
250  typedef typename Eigen::Matrix<T, Eigen::Dynamic, Eigen::Dynamic> Matrix;
252  typedef int Index;
254  typedef typename Eigen::Matrix<Index, Eigen::Dynamic, 1> IndexVector;
256  typedef typename Eigen::Matrix<Index, Eigen::Dynamic, Eigen::Dynamic> IndexMatrix;
257 
259  const Matrix& cloud;
261  const Index dim;
263  const unsigned creationOptionFlags;
268 
271  {
279  };
280 
283  {
285  };
286 
289  {
292  };
293 
295 
305  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;
306 
308 
318  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;
319 
321 
331  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;
332 
334 
340  static NearestNeighbourSearch* create(const Matrix& cloud, const Index dim = std::numeric_limits<Index>::max(), const SearchType preferedType = KDTREE_LINEAR_HEAP, const unsigned creationOptionFlags = 0, const Parameters& additionalParameters = Parameters());
341 
343 
348  static NearestNeighbourSearch* createBruteForce(const Matrix& cloud, const Index dim = std::numeric_limits<Index>::max(), const unsigned creationOptionFlags = 0);
349 
351 
357  static NearestNeighbourSearch* createKDTreeLinearHeap(const Matrix& cloud, const Index dim = std::numeric_limits<Index>::max(), const unsigned creationOptionFlags = 0, const Parameters& additionalParameters = Parameters());
358 
360 
366  static NearestNeighbourSearch* createKDTreeTreeHeap(const Matrix& cloud, const Index dim = std::numeric_limits<Index>::max(), const unsigned creationOptionFlags = 0, const Parameters& additionalParameters = Parameters());
367 
370 
371  protected:
373  NearestNeighbourSearch(const Matrix& cloud, const Index dim, const unsigned creationOptionFlags);
374 
376 
382  void checkSizesKnn(const Matrix& query, const IndexMatrix& indices, const Matrix& dists2, const Index k, const unsigned optionFlags, const Vector* maxRadii = 0) const;
383  };
384 
385  // Convenience typedefs
386 
391 
393 }
394 
395 #endif // __NABO_H
Eigen::Matrix< Index, Eigen::Dynamic, 1 > IndexVector
a vector of indices to data points
Definition: nabo.h:254
static NearestNeighbourSearch * createKDTreeTreeHeap(const Matrix &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:155
Parameters()
Create an empty parameter vector.
Definition: nabo.h:221
const Index dim
the dimensionality of the data-point cloud
Definition: nabo.h:261
const Vector minBound
the low bound of the search space (axis-aligned bounding box)
Definition: nabo.h:265
brute-force using openCL, only available if OpenCL enabled, UNSTABLE API
Definition: nabo.h:277
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:84
Eigen::Matrix< Index, Eigen::Dynamic, Eigen::Dynamic > IndexMatrix
a matrix of indices to data points
Definition: nabo.h:256
NearestNeighbourSearch(const Matrix &cloud, const Index dim, const unsigned creationOptionFlags)
constructor
Definition: nabo.cpp:50
Nearest neighbour search interface, templatized on scalar type.
Definition: nabo.h:245
SearchType
type of search
Definition: nabo.h:270
static NearestNeighbourSearch * create(const Matrix &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:116
brute force, check distance to every point in the data
Definition: nabo.h:272
SearchOptionFlags
search option
Definition: nabo.h:288
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:250
const unsigned creationOptionFlags
creation options
Definition: nabo.h:263
int Index
an index to a Vector or a Matrix, for refering to data points
Definition: nabo.h:252
const Vector maxBound
the high bound of the search space (axis-aligned bounding box)
Definition: nabo.h:267
static NearestNeighbourSearch * createKDTreeLinearHeap(const Matrix &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:147
NearestNeighbourSearch< double > NNSearchD
nearest neighbour search with scalars of type double
Definition: nabo.h:390
kd-tree with tree heap, good for large k (~from 30)
Definition: nabo.h:274
sort points by distances, when k &gt; 1; do not sort by default
Definition: nabo.h:291
CreationOptionFlags
creation option
Definition: nabo.h:282
Parameter vector.
Definition: nabo.h:218
virtual ~NearestNeighbourSearch()
virtual destructor
Definition: nabo.h:369
static NearestNeighbourSearch * createBruteForce(const Matrix &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:139
perform statistics on the number of points touched
Definition: nabo.h:284
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:64
kd-tree using openCL, pt in nodes, only available if OpenCL enabled, UNSTABLE API ...
Definition: nabo.h:275
allows the return of the same point as the query, if this point is in the data cloud; forbidden by de...
Definition: nabo.h:290
kd-tree using openCL, pt in leaves, only available if OpenCL enabled, UNSTABLE API ...
Definition: nabo.h:276
kd-tree with linear heap, good for small k (~up to 30)
Definition: nabo.h:273
Eigen::Matrix< T, Eigen::Dynamic, 1 > Vector
an Eigen vector of type T, to hold the coordinates of a point
Definition: nabo.h:248
Parameters(const std::string &key, const boost::any &value)
Create a parameter vector with a single entry.
Definition: nabo.h:226
const Matrix & cloud
the reference to the data-point cloud, which must remain valid during the lifetime of the NearestNeig...
Definition: nabo.h:259
number of search types
Definition: nabo.h:278
NearestNeighbourSearch< float > NNSearchF
nearest neighbour search with scalars of type float
Definition: nabo.h:388