libnabo  1.0.4
nabo_private.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_PRIVATE_H
33 #define __NABO_PRIVATE_H
34 
35 #include "nabo.h"
36 
37 #ifdef BOOST_STDINT
38  #include <boost/cstdint.hpp>
39  using boost::uint32_t;
40 #else // BOOST_STDINT
41  #include <stdint.h>
42 #endif // BOOST_STDINT
43 
44 // OpenCL
45 #ifdef HAVE_OPENCL
46  #define __CL_ENABLE_EXCEPTIONS
47  #include "CL/cl.hpp"
48 #endif // HAVE_OPENCL
49 
50 // Unused macro, add support for your favorite compiler
51 #if defined(__GNUC__)
52  #define _UNUSED __attribute__ ((unused))
53 #else
54  #define _UNUSED
55 #endif
56 
62 namespace Nabo
63 {
65 
66 
68  template<typename T, typename A, typename B>
69  inline T dist2(const A& v0, const B& v1)
70  {
71  return (v0 - v1).squaredNorm();
72  }
73 
75  template<typename T>
77  {
80  typedef typename NearestNeighbourSearch<T>::Index Index;
83 
89 
91  BruteForceSearch(const Matrix& cloud, const Index dim, const unsigned creationOptionFlags);
92  virtual unsigned long knn(const Matrix& query, IndexMatrix& indices, Matrix& dists2, const Index k, const T epsilon, const unsigned optionFlags, const T maxRadius) const;
93  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;
94  };
95 
97  template<typename T, typename Heap>
99  {
100  typedef typename NearestNeighbourSearch<T>::Vector Vector;
101  typedef typename NearestNeighbourSearch<T>::Matrix Matrix;
102  typedef typename NearestNeighbourSearch<T>::Index Index;
105 
112 
113  protected:
115  typedef std::vector<Index> BuildPoints;
117  typedef typename BuildPoints::iterator BuildPointsIt;
119  typedef typename BuildPoints::const_iterator BuildPointsCstIt;
120 
122  const unsigned bucketSize;
123 
125  const uint32_t dimBitCount;
127  const uint32_t dimMask;
128 
130  inline uint32_t createDimChildBucketSize(const uint32_t dim, const uint32_t childIndex) const
131  { return dim | (childIndex << dimBitCount); }
133  inline uint32_t getDim(const uint32_t dimChildBucketSize) const
134  { return dimChildBucketSize & dimMask; }
136  inline uint32_t getChildBucketSize(const uint32_t dimChildBucketSize) const
137  { return dimChildBucketSize >> dimBitCount; }
138 
139  struct BucketEntry;
140 
142  struct Node
143  {
145  union
146  {
147  T cutVal;
148  uint32_t bucketIndex;
149  };
150 
152  Node(const uint32_t dimChild, const T cutVal):
153  dimChildBucketSize(dimChild), cutVal(cutVal) {}
155  Node(const uint32_t bucketSize, const uint32_t bucketIndex):
156  dimChildBucketSize(bucketSize), bucketIndex(bucketIndex) {}
157  };
159  typedef std::vector<Node> Nodes;
160 
162  struct BucketEntry
163  {
164  const T* pt;
165  Index index;
166 
168 
171  BucketEntry(const T* pt = 0, const Index index = 0): pt(pt), index(index) {}
172  };
173 
175  typedef std::vector<BucketEntry> Buckets;
176 
178  Nodes nodes;
179 
181  Buckets buckets;
182 
184  std::pair<T,T> getBounds(const BuildPointsIt first, const BuildPointsIt last, const unsigned dim);
186  unsigned buildNodes(const BuildPointsIt first, const BuildPointsIt last, const Vector minValues, const Vector maxValues);
187 
189 
201  unsigned long onePointKnn(const Matrix& query, IndexMatrix& indices, Matrix& dists2, int i, Heap& heap, std::vector<T>& off, const T maxError, const T maxRadius2, const bool allowSelfMatch, const bool collectStatistics, const bool sortResults) const;
202 
204 
212  template<bool allowSelfMatch, bool collectStatistics>
213  unsigned long recurseKnn(const T* query, const unsigned n, T rd, Heap& heap, std::vector<T>& off, const T maxError, const T maxRadius2) const;
214 
215  public:
217  KDTreeUnbalancedPtInLeavesImplicitBoundsStackOpt(const Matrix& cloud, const Index dim, const unsigned creationOptionFlags, const Parameters& additionalParameters);
218  virtual unsigned long knn(const Matrix& query, IndexMatrix& indices, Matrix& dists2, const Index k, const T epsilon, const unsigned optionFlags, const T maxRadius) const;
219  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;
220  };
221 
222  #ifdef HAVE_OPENCL
223 
225  template<typename T>
227  {
228  typedef typename NearestNeighbourSearch<T>::Vector Vector;
229  typedef typename NearestNeighbourSearch<T>::Matrix Matrix;
230  typedef typename NearestNeighbourSearch<T>::Index Index;
233 
238 
239  protected:
240  const cl_device_type deviceType;
241  cl::Context& context;
242  mutable cl::Kernel knnKernel;
243  cl::CommandQueue queue;
244  cl::Buffer cloudCL;
245 
247  OpenCLSearch(const Matrix& cloud, const Index dim, const unsigned creationOptionFlags, const cl_device_type deviceType);
249 
253  void initOpenCL(const char* clFileName, const char* kernelName, const std::string& additionalDefines = "");
254 
255  public:
256  virtual unsigned long knn(const Matrix& query, IndexMatrix& indices, Matrix& dists2, const Index k, const T epsilon, const unsigned optionFlags, const T maxRadius) const;
257  };
258 
260  template<typename T>
262  {
263  typedef typename NearestNeighbourSearch<T>::Vector Vector;
264  typedef typename NearestNeighbourSearch<T>::Matrix Matrix;
265  typedef typename NearestNeighbourSearch<T>::Index Index;
266 
268 
270  BruteForceSearchOpenCL(const Matrix& cloud, const Index dim, const unsigned creationOptionFlags, const cl_device_type deviceType);
271  };
272 
274  template<typename T>
276  {
277  typedef typename NearestNeighbourSearch<T>::Vector Vector;
278  typedef typename NearestNeighbourSearch<T>::Matrix Matrix;
279  typedef typename NearestNeighbourSearch<T>::Index Index;
282 
288 
291 
293 
294  protected:
296  struct BuildPoint
297  {
298  Vector pos;
299  size_t index;
300  BuildPoint(const Vector& pos = Vector(), const size_t index = 0): pos(pos), index(index) {}
302  };
304  typedef std::vector<BuildPoint> BuildPoints;
306  typedef typename BuildPoints::iterator BuildPointsIt;
308  typedef typename BuildPoints::const_iterator BuildPointsCstIt;
309 
311  struct CompareDim
312  {
313  size_t dim;
314  CompareDim(const size_t dim):dim(dim){}
317  bool operator() (const BuildPoint& p0, const BuildPoint& p1) { return p0.pos(dim) < p1.pos(dim); }
318  };
319 
321  struct Node
322  {
323  int dim;
324  T cutVal;
325  Node(const int dim = -1, const T cutVal = 0):dim(dim), cutVal(cutVal) {}
327  };
329  typedef std::vector<Node> Nodes;
330 
331  Nodes nodes;
332  cl::Buffer nodesCL;
333 
334 
335  inline size_t childLeft(size_t pos) const { return 2*pos + 1; }
336  inline size_t childRight(size_t pos) const { return 2*pos + 2; }
337  inline size_t parent(size_t pos) const { return (pos-1)/2; }
338  size_t getTreeDepth(size_t size) const;
339  size_t getTreeSize(size_t size) const;
340 
342  void buildNodes(const BuildPointsIt first, const BuildPointsIt last, const size_t pos, const Vector minValues, const Vector maxValues);
343 
344  public:
346  KDTreeBalancedPtInLeavesStackOpenCL(const Matrix& cloud, const Index dim, const unsigned creationOptionFlags, const cl_device_type deviceType);
347  };
348 
350  template<typename T>
352  {
353  typedef typename NearestNeighbourSearch<T>::Vector Vector;
354  typedef typename NearestNeighbourSearch<T>::Matrix Matrix;
355  typedef typename NearestNeighbourSearch<T>::Index Index;
356  typedef typename NearestNeighbourSearch<T>::IndexVector IndexVector;
357  typedef typename NearestNeighbourSearch<T>::IndexMatrix IndexMatrix;
358 
364 
367 
369 
370  protected:
372  typedef Index BuildPoint;
374  typedef std::vector<BuildPoint> BuildPoints;
376  typedef typename BuildPoints::iterator BuildPointsIt;
378  typedef typename BuildPoints::const_iterator BuildPointsCstIt;
379 
381  struct CompareDim
382  {
383  const Matrix& cloud;
384  size_t dim;
385  CompareDim(const Matrix& cloud, const size_t dim): cloud(cloud), dim(dim){}
388  bool operator() (const BuildPoint& p0, const BuildPoint& p1) { return cloud.coeff(dim, p0) < cloud.coeff(dim, p1); }
389  };
390 
392  struct Node
393  {
394  int dim;
395  Index index;
396  Node(const int dim = -2, const Index index = 0):dim(dim), index(index) {}
398  };
400  typedef std::vector<Node> Nodes;
401 
402  Nodes nodes;
403  cl::Buffer nodesCL;
404 
405 
406  inline size_t childLeft(size_t pos) const { return 2*pos + 1; }
407  inline size_t childRight(size_t pos) const { return 2*pos + 2; }
408  inline size_t parent(size_t pos) const { return (pos-1)/2; }
409  size_t getTreeDepth(size_t size) const;
410  size_t getTreeSize(size_t size) const;
411 
413  void buildNodes(const BuildPointsIt first, const BuildPointsIt last, const size_t pos, const Vector minValues, const Vector maxValues);
414 
415  public:
417  KDTreeBalancedPtInNodesStackOpenCL(const Matrix& cloud, const Index dim, const unsigned creationOptionFlags, const cl_device_type deviceType);
418  };
419 
420  #endif // HAVE_OPENCL
421 
423 }
424 
425 #endif // __NABO_H
Eigen::Matrix< Index, Eigen::Dynamic, 1 > IndexVector
a vector of indices to data points
Definition: nabo.h:254
OpenCL support for nearest neighbour search.
Definition: nabo_private.h:226
KDTree, unbalanced, points in leaves, stack, implicit bounds, ANN_KD_SL_MIDPT, optimised implementati...
Definition: nabo_private.h:98
const Index dim
the dimensionality of the data-point cloud
Definition: nabo.h:261
std::vector< BucketEntry > Buckets
bucket data
Definition: nabo_private.h:175
KDTree, balanced, points in nodes, stack, implicit bounds, balance aspect ratio.
Definition: nabo_private.h:351
size_t dim
dimension on which to compare
Definition: nabo_private.h:313
BuildPoints::iterator BuildPointsIt
iterator to points during kd-tree construction
Definition: nabo_private.h:376
BuildPoints::iterator BuildPointsIt
iterator to points during kd-tree construction
Definition: nabo_private.h:306
Eigen::Matrix< Index, Eigen::Dynamic, Eigen::Dynamic > IndexMatrix
a matrix of indices to data points
Definition: nabo.h:256
Nodes nodes
search nodes
Definition: nabo_private.h:331
Nearest neighbour search interface, templatized on scalar type.
Definition: nabo.h:245
cl::Buffer nodesCL
CL buffer for search nodes.
Definition: nabo_private.h:332
cl::Context & context
the CL context
Definition: nabo_private.h:241
cl::Buffer nodesCL
CL buffer for search nodes.
Definition: nabo_private.h:403
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
BuildPoints::const_iterator BuildPointsCstIt
const-iterator to indices of points during kd-tree construction
Definition: nabo_private.h:119
BucketEntry(const T *pt=0, const Index index=0)
create a new bucket entry for a point in the data
Definition: nabo_private.h:171
size_t childRight(size_t pos) const
Return the right child of pos.
Definition: nabo_private.h:407
uint32_t dimChildBucketSize
cut dimension for split nodes (dimBitCount lsb), index of right node or number of bucket(rest)...
Definition: nabo_private.h:144
T cutVal
for split node, split value
Definition: nabo_private.h:147
const unsigned bucketSize
size of bucket
Definition: nabo_private.h:122
int dim
dimension of the cut, or, if negative, index of the point: -1 == invalid, <= -2 = index of pt ...
Definition: nabo_private.h:323
const unsigned creationOptionFlags
creation options
Definition: nabo.h:263
Node(const uint32_t dimChild, const T cutVal)
construct a split node
Definition: nabo_private.h:152
T cutVal
value of the cut
Definition: nabo_private.h:324
KDTree, balanced, points in leaves, stack, implicit bounds, balance aspect ratio. ...
Definition: nabo_private.h:261
int Index
an index to a Vector or a Matrix, for refering to data points
Definition: nabo.h:252
Nodes nodes
search nodes
Definition: nabo_private.h:402
const uint32_t dimBitCount
number of bits required to store dimension index + number of dimensions
Definition: nabo_private.h:125
Index index
index of point
Definition: nabo_private.h:165
BruteForceSearch(const Matrix &cloud, const Index dim, const unsigned creationOptionFlags)
constructor, calls NearestNeighbourSearch<T>(cloud)
Definition: brute_force_cpu.cpp:45
uint32_t getChildBucketSize(const uint32_t dimChildBucketSize) const
get the child index or the bucket size out of the coumpount index
Definition: nabo_private.h:136
std::vector< Node > Nodes
dense vector of search nodes, provides better memory performances than many small objects ...
Definition: nabo_private.h:159
Functor to compare point values on a given dimension.
Definition: nabo_private.h:311
const Matrix & cloud
reference to data points used to compare
Definition: nabo_private.h:383
size_t childLeft(size_t pos) const
Return the left child of pos.
Definition: nabo_private.h:406
size_t parent(size_t pos) const
Return the parent of pos.
Definition: nabo_private.h:337
Brute-force nearest neighbour.
Definition: nabo_private.h:76
Nodes nodes
search nodes
Definition: nabo_private.h:178
int dim
dimension of the cut, or, if -1 == leaf, -2 == invalid
Definition: nabo_private.h:394
const cl_device_type deviceType
the type of device to run CL code on (CL_DEVICE_TYPE_CPU or CL_DEVICE_TYPE_GPU)
Definition: nabo_private.h:240
uint32_t bucketIndex
for leaf node, pointer to bucket
Definition: nabo_private.h:148
virtual unsigned long knn(const Matrix &query, IndexMatrix &indices, Matrix &dists2, const Index k, const T epsilon, const unsigned optionFlags, const T maxRadius) const
Find the k nearest neighbours for each point of query.
Definition: brute_force_cpu.cpp:64
Parameter vector.
Definition: nabo.h:218
const uint32_t dimMask
mask to access dim
Definition: nabo_private.h:127
uint32_t createDimChildBucketSize(const uint32_t dim, const uint32_t childIndex) const
create the compound index containing the dimension and the index of the child or the bucket size ...
Definition: nabo_private.h:130
BuildPoints::const_iterator BuildPointsCstIt
const-iterator to points during kd-tree construction
Definition: nabo_private.h:378
std::vector< BuildPoint > BuildPoints
points during kd-tree construction
Definition: nabo_private.h:374
BuildPoints::const_iterator BuildPointsCstIt
const-iterator to points during kd-tree construction
Definition: nabo_private.h:308
size_t childRight(size_t pos) const
Return the right child of pos.
Definition: nabo_private.h:336
std::vector< Index > BuildPoints
indices of points during kd-tree construction
Definition: nabo_private.h:115
Point during kd-tree construction.
Definition: nabo_private.h:296
BuildPoints::iterator BuildPointsIt
iterator to indices of points during kd-tree construction
Definition: nabo_private.h:117
cl::Kernel knnKernel
the kernel to perform knnSearch, mutable because it is stateful, but conceptually const ...
Definition: nabo_private.h:242
cl::CommandQueue queue
the command queue
Definition: nabo_private.h:243
size_t index
index of point in cloud
Definition: nabo_private.h:299
size_t parent(size_t pos) const
Return the parent of pos.
Definition: nabo_private.h:408
Namespace for Nabo.
Definition: brute_force_cpu.cpp:40
size_t dim
dimension on which to compare
Definition: nabo_private.h:384
Functor to compare point values on a given dimension.
Definition: nabo_private.h:381
public interface
std::vector< Node > Nodes
dense vector of search nodes
Definition: nabo_private.h:400
KDTree, balanced, points in leaves, stack, implicit bounds, balance aspect ratio. ...
Definition: nabo_private.h:275
Node(const uint32_t bucketSize, const uint32_t bucketIndex)
construct a leaf node
Definition: nabo_private.h:155
uint32_t getDim(const uint32_t dimChildBucketSize) const
get the dimension out of the compound index
Definition: nabo_private.h:133
Index BuildPoint
a point during kd-tree construction is just its index
Definition: nabo_private.h:372
Index index
index of the point to cut
Definition: nabo_private.h:395
Buckets buckets
buckets
Definition: nabo_private.h:181
Tree node for CL.
Definition: nabo_private.h:392
cl::Buffer cloudCL
the buffer for the input data
Definition: nabo_private.h:244
T dist2(const A &v0, const B &v1)
Euclidean distance.
Definition: nabo_private.h:69
entry in a bucket
Definition: nabo_private.h:162
Tree node for CL.
Definition: nabo_private.h:321
Eigen::Matrix< T, Eigen::Dynamic, 1 > Vector
an Eigen vector of type T, to hold the coordinates of a point
Definition: nabo.h:248
const Matrix & cloud
the reference to the data-point cloud, which must remain valid during the lifetime of the NearestNeig...
Definition: nabo.h:259
size_t childLeft(size_t pos) const
Return the left child of pos.
Definition: nabo_private.h:335
Vector pos
point
Definition: nabo_private.h:298
std::vector< BuildPoint > BuildPoints
points during kd-tree construction
Definition: nabo_private.h:304
search node
Definition: nabo_private.h:142
std::vector< Node > Nodes
dense vector of search nodes
Definition: nabo_private.h:329
const T * pt
pointer to first value of point data, 0 if end of bucket
Definition: nabo_private.h:164