KdTree : Changes to Make In The Next Major Version

include/IECore/KDTree.h

@@ -36,10 +36,12 @@
 #define IE_CORE_KDTREE_H
 
 #include "IECore/Export.h"
+#include "IECore/TypeTraits.h"
 #include "IECore/VectorTraits.h"
 
 IECORE_PUSH_DEFAULT_VISIBILITY
 #include "Imath/ImathVec.h"
+#include "Imath/ImathBox.h"
 IECORE_POP_DEFAULT_VISIBILITY
 
 #include <set>
@@ -48,6 +50,15 @@ IECORE_POP_DEFAULT_VISIBILITY
 namespace IECore
 {
 
+namespace Detail
+{
+	// \todo - ugly machinery needed until we deprecate the old signature of enclosedPoints
+	template <typename, typename = void>
+	struct IsIterator : std::false_type {};
+	template <typename T>
+	struct IsIterator<T, std::void_t< typename std::iterator_traits<T>::iterator_category >> : std::true_type {};
+}
+
 /// The KDTree class provides accelerated searching of pointsets. It is
 /// templated so that it can operate on a wide variety of datatypes, and uses
 /// the VectorTraits.h and VectorOps.h functionality to assist in this.
@@ -93,21 +104,28 @@ class KDTree
 		/// \threading May be called by multiple concurrent threads.
 		PointIterator nearestNeighbour( const Point &p, BaseType &distSquared ) const;
 
-		/// Populates the passed vector of iterators with the neighbours of point p which are closer than radius r. Returns the number of points found.
-		/// \todo There should be a form where nearNeighbours is an output iterator, to allow any container to be filled.
-		/// See enclosedPoints for an example of this form.
-		/// \threading May be called by multiple concurrent threads provided they are each using a different vector for the result.
-		unsigned int nearestNeighbours( const Point &p, BaseType r, std::vector<PointIterator> &nearNeighbours ) const;
+		/// Call a functor for each neighbour of point p which is closer than radius r.
+		/// The functor must take a PointIterator.
+		template<typename F>
+		void nearestNeighbours( const Point &p, BaseType r, F &&functor ) const;
 
 		class Neighbour;
 		/// Populates the passed vector with the N closest neighbours to p, sorted with the closest first. Returns the number found.
 		/// \threading May be called by multiple concurrent threads provided they are each using a different vector for the result.
 		unsigned int nearestNNeighbours( const Point &p, unsigned int numNeighbours, std::vector<Neighbour> &nearNeighbours ) const;
 
-		/// Finds all the points contained by the specified bound, outputting them to the specified iterator.
+		/// Finds all the points contained by the specified bound, outputting them to the specified functor,
+		/// which must take a PointIterator.
 		/// \threading May be called by multiple concurrent threads.
-		template<typename Box, typename OutputIterator>
-		void enclosedPoints( const Box &bound, OutputIterator it ) const;
+		template<typename Box, typename F>
+		void enclosedPoints( const Box &bound, F &&functor ) const;
+
+		// Finds all the points contained within a set of half-spaces, passing them to the given
+		// functor which must take a PointIterator.
+		// A half-space is specified with an origin and a plane normal ( the normal points towards the region that
+		// is included )
+		template<typename F>
+		void enclosedPoints( const std::vector<Point> &normals, const std::vector<Point> &origins, F &&functor ) const;
 
 		/// Returns the number of nodes in the tree.
 		inline NodeIndex numNodes() const;
@@ -132,22 +150,38 @@ class KDTree
 
 		class AxisSort;
 
+		// -- Utilities used when building the tree	--
+
+		// Compute min/max of a list of points
+		Imath::Box<Point> bound( PermutationConstIterator permFirst, PermutationConstIterator permLast );
+		// Return which axis of the bounding box is largest
 		unsigned char majorAxis( PermutationConstIterator permFirst, PermutationConstIterator permLast );
+		// Recursively build the tree
 		void build( NodeIndex nodeIndex, PermutationIterator permFirst, PermutationIterator permLast );
 
+
+		// -- Walk functions that implement the recursive searches --
+
 		void nearestNeighbourWalk( NodeIndex nodeIndex, const Point &p, PointIterator &closestPoint, BaseType &distSquared ) const;
 
-		void nearestNeighboursWalk( NodeIndex nodeIndex, const Point &p, BaseType r2, std::vector<PointIterator> &nearNeighbours ) const;
+		template<typename F>
+		void nearestNeighboursWalk( NodeIndex nodeIndex, const Point &p, BaseType r2, F &&functor ) const;
+
+		template<typename Box, typename F>
+		void enclosedPointsWalk( NodeIndex nodeIndex, const Box &bound, F &&functor  ) const;
+
+		struct HalfSpaceWorkingData;
 
-		template<typename Box, typename OutputIterator>
-		void enclosedPointsWalk( NodeIndex nodeIndex, const Box &bound, OutputIterator it ) const;
+		template<typename F>
+		void enclosedPointsHalfSpacesWalk( NodeIndex nodeIndex, std::vector<HalfSpaceWorkingData> &working, F &&functor ) const;
 
 		void nearestNNeighboursWalk( NodeIndex nodeIndex, const Point &p, unsigned int numNeighbours, std::vector<Neighbour> &nearNeighbours, BaseType &maxDistSquared ) const;
 
 		Permutation m_perm;
 		NodeVector m_nodes;
 		int m_maxLeafSize;
 		PointIterator m_lastPoint;
+		Imath::Box< Point > m_bound;
 
 };