You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

95 lines
5.4 KiB

  1. // This file is part of Eigen, a lightweight C++ template library
  2. // for linear algebra.
  3. //
  4. // Copyright (C) 2009 Ilya Baran <ibaran@mit.edu>
  5. //
  6. // This Source Code Form is subject to the terms of the Mozilla
  7. // Public License v. 2.0. If a copy of the MPL was not distributed
  8. // with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
  9. #ifndef EIGEN_BVH_MODULE_H
  10. #define EIGEN_BVH_MODULE_H
  11. #include <Eigen/Core>
  12. #include <Eigen/Geometry>
  13. #include <Eigen/StdVector>
  14. #include <algorithm>
  15. #include <queue>
  16. namespace StormEigen {
  17. /**
  18. * \defgroup BVH_Module BVH module
  19. * \brief This module provides generic bounding volume hierarchy algorithms
  20. * and reference tree implementations.
  21. *
  22. *
  23. * \code
  24. * #include <unsupported/Eigen/BVH>
  25. * \endcode
  26. *
  27. * A bounding volume hierarchy (BVH) can accelerate many geometric queries. This module provides a generic implementation
  28. * of the two basic algorithms over a BVH: intersection of a query object against all objects in the hierarchy and minimization
  29. * of a function over the objects in the hierarchy. It also provides intersection and minimization over a cartesian product of
  30. * two BVH's. A BVH accelerates intersection by using the fact that if a query object does not intersect a volume, then it cannot
  31. * intersect any object contained in that volume. Similarly, a BVH accelerates minimization because the minimum of a function
  32. * over a volume is no greater than the minimum of a function over any object contained in it.
  33. *
  34. * Some sample queries that can be written in terms of intersection are:
  35. * - Determine all points where a ray intersects a triangle mesh
  36. * - Given a set of points, determine which are contained in a query sphere
  37. * - Given a set of spheres, determine which contain the query point
  38. * - Given a set of disks, determine if any is completely contained in a query rectangle (represent each 2D disk as a point \f$(x,y,r)\f$
  39. * in 3D and represent the rectangle as a pyramid based on the original rectangle and shrinking in the \f$r\f$ direction)
  40. * - Given a set of points, count how many pairs are \f$d\pm\epsilon\f$ apart (done by looking at the cartesian product of the set
  41. * of points with itself)
  42. *
  43. * Some sample queries that can be written in terms of function minimization over a set of objects are:
  44. * - Find the intersection between a ray and a triangle mesh closest to the ray origin (function is infinite off the ray)
  45. * - Given a polyline and a query point, determine the closest point on the polyline to the query
  46. * - Find the diameter of a point cloud (done by looking at the cartesian product and using negative distance as the function)
  47. * - Determine how far two meshes are from colliding (this is also a cartesian product query)
  48. *
  49. * This implementation decouples the basic algorithms both from the type of hierarchy (and the types of the bounding volumes) and
  50. * from the particulars of the query. To enable abstraction from the BVH, the BVH is required to implement a generic mechanism
  51. * for traversal. To abstract from the query, the query is responsible for keeping track of results.
  52. *
  53. * To be used in the algorithms, a hierarchy must implement the following traversal mechanism (see KdBVH for a sample implementation): \code
  54. typedef Volume //the type of bounding volume
  55. typedef Object //the type of object in the hierarchy
  56. typedef Index //a reference to a node in the hierarchy--typically an int or a pointer
  57. typedef VolumeIterator //an iterator type over node children--returns Index
  58. typedef ObjectIterator //an iterator over object (leaf) children--returns const Object &
  59. Index getRootIndex() const //returns the index of the hierarchy root
  60. const Volume &getVolume(Index index) const //returns the bounding volume of the node at given index
  61. void getChildren(Index index, VolumeIterator &outVBegin, VolumeIterator &outVEnd,
  62. ObjectIterator &outOBegin, ObjectIterator &outOEnd) const
  63. //getChildren takes a node index and makes [outVBegin, outVEnd) range over its node children
  64. //and [outOBegin, outOEnd) range over its object children
  65. \endcode
  66. *
  67. * To use the hierarchy, call BVIntersect or BVMinimize, passing it a BVH (or two, for cartesian product) and a minimizer or intersector.
  68. * For an intersection query on a single BVH, the intersector encapsulates the query and must provide two functions:
  69. * \code
  70. bool intersectVolume(const Volume &volume) //returns true if the query intersects the volume
  71. bool intersectObject(const Object &object) //returns true if the intersection search should terminate immediately
  72. \endcode
  73. * The guarantee that BVIntersect provides is that intersectObject will be called on every object whose bounding volume
  74. * intersects the query (but possibly on other objects too) unless the search is terminated prematurely. It is the
  75. * responsibility of the intersectObject function to keep track of the results in whatever manner is appropriate.
  76. * The cartesian product intersection and the BVMinimize queries are similar--see their individual documentation.
  77. *
  78. * The following is a simple but complete example for how to use the BVH to accelerate the search for a closest red-blue point pair:
  79. * \include BVH_Example.cpp
  80. * Output: \verbinclude BVH_Example.out
  81. */
  82. }
  83. //@{
  84. #include "src/BVH/BVAlgorithms.h"
  85. #include "src/BVH/KdBVH.h"
  86. //@}
  87. #endif // EIGEN_BVH_MODULE_H