Added KdTree build options:

Jaybro · Jaybro · commit 2993ade8b77d · 2025-02-02T23:25:47.000+01:00
* Updated the split rule class template to be a constructor argument.
* Builds can now terminate based maximum leaf depth instead of maximum leaf size.
* The bounds of the input space can be customized.
diff --git a/README.md b/README.md
@@ -31,7 +31,7 @@ KdTree:
   * Support for topological spaces with identifications. E.g., points on the circle `[-pi, pi]`.
   * Available distance functions: `L1`, `L2Squared`, `LInf`, `SO2`, and `SE2Squared`.
   * Metrics can be customized.
-* Multiple tree splitting rules: `kLongestMedian`, `kMidpoint` and `kSlidingMidpoint`.
+* Multiple tree splitting rules: `median_max_side_t`, `midpoint_max_side_t` and `sliding_midpoint_max_side_t`.
 * Compile time and run time known dimensions.
 * Static tree builds.
 * Thread safe queries.
diff --git a/examples/benchmark/bm_pico_kd_tree.cpp b/examples/benchmark/bm_pico_kd_tree.cpp
@@ -26,15 +26,17 @@ using PicoKdTreeRtSldMid = pico_tree::KdTree<PicoRtSpace<PointX>>;
 // ****************************************************************************
 
 BENCHMARK_DEFINE_F(BmPicoKdTree, BuildCtSldMid)(benchmark::State& state) {
-  int max_leaf_size = state.range(0);
+  pico_tree::max_leaf_size_t max_leaf_size =
+      static_cast<std::size_t>(state.range(0));
 
   for (auto _ : state) {
     PicoKdTreeCtSldMid<PointX> tree(points_tree_, max_leaf_size);
   }
 }
 
 BENCHMARK_DEFINE_F(BmPicoKdTree, BuildRtSldMid)(benchmark::State& state) {
-  int max_leaf_size = state.range(0);
+  pico_tree::max_leaf_size_t max_leaf_size =
+      static_cast<std::size_t>(state.range(0));
 
   for (auto _ : state) {
     PicoKdTreeRtSldMid<PointX> tree(
@@ -58,8 +60,9 @@ BENCHMARK_REGISTER_F(BmPicoKdTree, BuildRtSldMid)
 // ****************************************************************************
 
 BENCHMARK_DEFINE_F(BmPicoKdTree, KnnCtSldMid)(benchmark::State& state) {
-  int max_leaf_size = state.range(0);
-  int knn_count = state.range(1);
+  pico_tree::max_leaf_size_t max_leaf_size =
+      static_cast<std::size_t>(state.range(0));
+  std::size_t knn_count = static_cast<std::size_t>(state.range(1));
 
   PicoKdTreeCtSldMid<PointX> tree(points_tree_, max_leaf_size);
 
@@ -105,7 +108,8 @@ BENCHMARK_REGISTER_F(BmPicoKdTree, KnnCtSldMid)
 // ****************************************************************************
 
 BENCHMARK_DEFINE_F(BmPicoKdTree, RadiusCtSldMid)(benchmark::State& state) {
-  int max_leaf_size = state.range(0);
+  pico_tree::max_leaf_size_t max_leaf_size =
+      static_cast<std::size_t>(state.range(0));
   Scalar radius = static_cast<Scalar>(state.range(1)) / Scalar(10.0);
   Scalar squared = radius * radius;
 
@@ -143,7 +147,8 @@ BENCHMARK_REGISTER_F(BmPicoKdTree, RadiusCtSldMid)
 // ****************************************************************************
 
 BENCHMARK_DEFINE_F(BmPicoKdTree, BoxCtSldMid)(benchmark::State& state) {
-  int max_leaf_size = state.range(0);
+  pico_tree::max_leaf_size_t max_leaf_size =
+      static_cast<std::size_t>(state.range(0));
   Scalar radius = static_cast<Scalar>(state.range(1)) / Scalar(10.0);
 
   PicoKdTreeCtSldMid<PointX> tree(points_tree_, max_leaf_size);
@@ -172,7 +177,8 @@ BENCHMARK_REGISTER_F(BmPicoKdTree, BoxCtSldMid)
     ->Args({14, 15});
 
 BENCHMARK_DEFINE_F(BmPicoKdTree, BoxRtSldMid)(benchmark::State& state) {
-  int max_leaf_size = state.range(0);
+  pico_tree::max_leaf_size_t max_leaf_size =
+      static_cast<std::size_t>(state.range(0));
   Scalar radius = static_cast<Scalar>(state.range(1)) / Scalar(10.0);
 
   PicoKdTreeRtSldMid<PointX> tree(
diff --git a/examples/eigen/eigen.cpp b/examples/eigen/eigen.cpp
@@ -23,7 +23,7 @@ using PointsMapRowMajor = Eigen::Map<Eigen::Matrix<
 std::size_t const kRunCount = 1024 * 1024;
 std::size_t const kNumPoints = 1024 * 1024 * 2;
 float const kArea = 1000.0;
-std::size_t const kMaxLeafCount = 16;
+pico_tree::max_leaf_size_t const kMaxLeafCount = 16;
 
 template <typename PointX>
 std::vector<PointX> GenerateRandomEigenN(
diff --git a/examples/kd_forest/kd_forest.cpp b/examples/kd_forest/kd_forest.cpp
@@ -44,7 +44,7 @@ void RunKdTree(
     std::vector<Vector_> const& train,
     std::vector<Vector_> const& test,
     std::string const& fn_nns_gt,
-    std::size_t tree_max_leaf_size,
+    pico_tree::max_leaf_size_t tree_max_leaf_size,
     std::vector<pico_tree::Neighbor<int, Scalar_>>& nns) {
   using Space = std::reference_wrapper<std::vector<Vector_> const>;
 
diff --git a/examples/kd_tree/kd_tree_creation.cpp b/examples/kd_tree/kd_tree_creation.cpp
@@ -40,18 +40,17 @@ auto MakePointSet() { return Space{{0.0f, 1.0f, 2.0f}, {3.0f, 4.0f, 5.0f}}; }
 // In this example, the creation of a KdTree results in a copy of the input
 // point set. The KdTree has full ownership of the copy.
 void BuildKdTreeWithCopy() {
-  int max_leaf_size = 12;
   auto points = MakePointSet();
 
-  pico_tree::KdTree<Space> tree(points, max_leaf_size);
+  pico_tree::KdTree<Space> tree(points, pico_tree::max_leaf_size_t(12));
 
   QueryTree(tree);
 }
 
 // In this example, the point sets are not copied but moved into the KdTrees
 // when they are created. Each tree has full ownership of the moved point set.
 void BuildKdTreeWithMove() {
-  int max_leaf_size = 12;
+  pico_tree::max_leaf_size_t max_leaf_size = 12;
   auto points = MakePointSet();
 
   pico_tree::KdTree<Space> tree1(std::move(points), max_leaf_size);
@@ -66,7 +65,7 @@ void BuildKdTreeWithMove() {
 // only a reference is copied by a KdTree. Each tree only has shallow ownership
 // of the input point set.
 void BuildKdTreeWithReference() {
-  int max_leaf_size = 12;
+  pico_tree::max_leaf_size_t max_leaf_size = 12;
   auto points = MakePointSet();
 
   // By reference.
@@ -83,7 +82,7 @@ void BuildKdTreeWithReference() {
 // This example shows that the type of the input point set may be deduced by the
 // compiler.
 void SpaceTypeDeduction() {
-  int max_leaf_size = 12;
+  pico_tree::max_leaf_size_t max_leaf_size = 12;
   auto points = MakePointSet();
 
   // The type of the first class template argument, the space type, is
diff --git a/examples/kd_tree/kd_tree_custom_point_type.cpp b/examples/kd_tree/kd_tree_custom_point_type.cpp
@@ -31,11 +31,10 @@ struct PointTraits<PointXYZ> {
 }  // namespace pico_tree
 
 int main() {
-  std::size_t max_leaf_size = 12;
   std::vector<PointXYZ> points{{0.0f, 1.0f, 2.0f}, {3.0f, 4.0f, 5.0f}};
 
   pico_tree::KdTree<std::reference_wrapper<std::vector<PointXYZ>>> tree(
-      points, max_leaf_size);
+      points, pico_tree::max_leaf_size_t(12));
 
   PointXYZ query{4.0f, 4.0f, 4.0f};
   pico_tree::Neighbor<int, float> nn;
diff --git a/examples/kd_tree/kd_tree_custom_search_visitor.cpp b/examples/kd_tree/kd_tree_custom_search_visitor.cpp
@@ -47,7 +47,7 @@ int main() {
   using PointX = Point2f;
   using Scalar = typename PointX::ScalarType;
 
-  std::size_t max_leaf_size = 12;
+  pico_tree::max_leaf_size_t max_leaf_size = 12;
   std::size_t point_count = 1024 * 1024;
   Scalar area_size = 1000;
 
diff --git a/examples/kd_tree/kd_tree_custom_space_type.cpp b/examples/kd_tree/kd_tree_custom_space_type.cpp
@@ -37,12 +37,11 @@ struct SpaceTraits<std::deque<std::array<Scalar_, Dim_>>> {
 }  // namespace pico_tree
 
 int main() {
-  std::size_t max_leaf_size = 1;
   std::deque<std::array<float, 2>> points{
       {0.0f, 1.0f}, {2.0f, 3.0f}, {4.0f, 5.0f}};
 
   pico_tree::KdTree<std::reference_wrapper<std::deque<std::array<float, 2>>>>
-      tree(points, max_leaf_size);
+      tree(points, pico_tree::max_leaf_size_t(1));
 
   std::array<float, 2> query{4.0f, 4.0f};
   pico_tree::Neighbor<int, float> nn;
diff --git a/examples/kd_tree/kd_tree_dynamic_arrays.cpp b/examples/kd_tree/kd_tree_dynamic_arrays.cpp
@@ -22,9 +22,8 @@ void ArrayOfScalars() {
   // argument: The spatial dimension known at run time.
   pico_tree::SpaceMap<pico_tree::PointMap<double, Dim>> map(data.get(), count);
 
-  std::size_t max_leaf_size = 3;
   pico_tree::KdTree<pico_tree::SpaceMap<pico_tree::PointMap<double, Dim>>> tree(
-      map, max_leaf_size);
+      map, pico_tree::max_leaf_size_t(3));
 
   // If Dim equals pico_tree::kDynamicSize, then PointMap will need a 2nd
   // argument: The spatial dimension known at run time.
@@ -52,9 +51,8 @@ void ArrayOfPoints() {
 
   pico_tree::SpaceMap<std::array<double, Dim>> map(data.get(), count);
 
-  std::size_t max_leaf_size = 3;
   pico_tree::KdTree<pico_tree::SpaceMap<std::array<double, Dim>>> tree(
-      map, max_leaf_size);
+      map, pico_tree::max_leaf_size_t(3));
 
   std::size_t index = 1;
   std::array<double, Dim> const& query = data[index];
diff --git a/examples/kd_tree/kd_tree_minimal.cpp b/examples/kd_tree/kd_tree_minimal.cpp
@@ -9,7 +9,7 @@
 // used for storing points and a point can be either an array or an std::array.
 
 int main() {
-  std::size_t max_leaf_size = 12;
+  pico_tree::max_leaf_size_t max_leaf_size = 12;
   std::vector<std::array<float, 3>> points{
       {0.0f, 1.0f, 2.0f}, {3.0f, 4.0f, 5.0f}};
 
diff --git a/examples/kd_tree/kd_tree_save_and_load.cpp b/examples/kd_tree/kd_tree_save_and_load.cpp
@@ -21,8 +21,7 @@ int main() {
   std::string filename = "tree.bin";
 
   // Save to file.
-  std::size_t max_leaf_size = 12;
-  KdTree::Save(KdTree(points, max_leaf_size), filename);
+  KdTree::Save(KdTree(points, pico_tree::max_leaf_size_t(12)), filename);
 
   // Load from file.
   auto tree = KdTree::Load(points, filename);
diff --git a/examples/kd_tree/kd_tree_search.cpp b/examples/kd_tree/kd_tree_search.cpp
@@ -9,7 +9,7 @@ void SearchR3() {
   using Scalar = typename PointX::ScalarType;
 
   std::size_t run_count = 1024 * 1024;
-  std::size_t max_leaf_size = 12;
+  pico_tree::max_leaf_size_t max_leaf_size = 12;
   std::size_t point_count = 1024 * 1024;
   Scalar area_size = 1000;
 
@@ -79,7 +79,7 @@ void SearchS1() {
   const auto pi = typename PointX::ScalarType(3.1415926537);
 
   pico_tree::KdTree<SpaceX, pico_tree::SO2> tree(
-      GenerateRandomN<PointX>(512, -pi, pi), 10);
+      GenerateRandomN<PointX>(512, -pi, pi), pico_tree::max_leaf_size_t(10));
 
   std::array<NeighborX, 8> knn;
   tree.SearchKnn(PointX{pi}, knn.begin(), knn.end());
diff --git a/examples/opencv/opencv.cpp b/examples/opencv/opencv.cpp
@@ -33,7 +33,7 @@ void BasicVector() {
   using PointX = cv::Vec<Scalar, 3>;
   std::vector<PointX> random = GenerateRandomVecN<PointX>(kNumPoints, kArea);
 
-  pico_tree::KdTree tree(std::cref(random), 10);
+  pico_tree::KdTree tree(std::cref(random), pico_tree::max_leaf_size_t(10));
 
   auto p = random[random.size() / 2];
 
@@ -51,7 +51,8 @@ void BasicMatrix() {
     cv::Mat random(kNumPoints, 3, cv::DataType<Scalar>::type);
     cv::randu(random, Scalar(0.0), kArea);
 
-    pico_tree::KdTree<pico_tree::MatWrapper<Scalar, 3>> tree(random, 10);
+    pico_tree::KdTree<pico_tree::MatWrapper<Scalar, 3>> tree(
+        random, pico_tree::max_leaf_size_t(10));
     pico_tree::PointMap<Scalar, 3> p(random.ptr<Scalar>(random.rows / 2));
 
     pico_tree::Neighbor<Index, Scalar> nn;
@@ -67,7 +68,7 @@ void BasicMatrix() {
     std::vector<PointX> random = GenerateRandomVecN<PointX>(kNumPoints, kArea);
 
     pico_tree::KdTree<pico_tree::MatWrapper<Scalar, 3>> tree(
-        cv::Mat(random), 10);
+        cv::Mat(random), pico_tree::max_leaf_size_t(10));
 
     PointX p = random[random.size() / 2];
 
diff --git a/examples/pico_understory/pico_understory/internal/rkd_tree_builder.hpp b/examples/pico_understory/pico_understory/internal/rkd_tree_builder.hpp
@@ -5,27 +5,37 @@
 
 namespace pico_tree::internal {
 
-template <typename Node_, Size Dim_, SplittingRule SplittingRule_>
+template <typename RKdTreeHhData_, Size Dim_>
 class BuildRKdTree {
+  using NodeType = typename RKdTreeHhData_::NodeType;
+  using KdTreeDataType = KdTreeData<NodeType, Dim_>;
+
  public:
-  using RKdTreeDataType = RKdTreeHhData<Node_, Dim_>;
+  using RKdTreeDataType = RKdTreeHhData_;
 
-  template <typename SpaceWrapper_>
+  template <
+      typename SpaceWrapper_,
+      typename Stop_,
+      typename Bounds_,
+      typename Rule_>
   std::vector<RKdTreeDataType> operator()(
-      SpaceWrapper_ space, Size max_leaf_size, Size forest_size) {
-    assert(space.size() > 0);
-    assert(max_leaf_size > 0);
+      SpaceWrapper_ space,
+      splitter_stop_condition_t<Stop_> const& stop_condition,
+      splitter_start_bounds_t<Bounds_> const& start_bounds,
+      splitter_rule_t<Rule_> const& rule,
+      Size forest_size) {
     assert(forest_size > 0);
 
     using SpaceWrapperType = typename RKdTreeDataType::SpaceWrapperType;
-    using BuildKdTreeType = BuildKdTree<Node_, Dim_, SplittingRule_>;
+    using BuildKdTreeType = BuildKdTree<KdTreeDataType, Dim_>;
 
     std::vector<RKdTreeDataType> trees;
     trees.reserve(forest_size);
     for (std::size_t i = 0; i < forest_size; ++i) {
       auto r = RKdTreeDataType::RandomRotation(space);
       auto s = RKdTreeDataType::RotateSpace(r, space);
-      auto t = BuildKdTreeType()(SpaceWrapperType(s), max_leaf_size);
+      auto t = BuildKdTreeType()(
+          SpaceWrapperType(s), stop_condition, start_bounds, rule);
       trees.push_back({std::move(r), std::move(s), std::move(t)});
     }
     return trees;
diff --git a/examples/pico_understory/pico_understory/kd_forest.hpp b/examples/pico_understory/pico_understory/kd_forest.hpp
@@ -9,18 +9,14 @@
 
 namespace pico_tree {
 
-template <
-    typename Space_,
-    typename Metric_ = L2Squared,
-    SplittingRule SplittingRule_ = SplittingRule::kSlidingMidpoint,
-    typename Index_ = int>
+template <typename Space_, typename Metric_ = L2Squared, typename Index_ = int>
 class KdForest {
   using SpaceWrapperType = internal::SpaceWrapper<Space_>;
+  // PrioritySearchNearestEuclidean only supports KdTreeNodeTopological.
   using NodeType = internal::
       KdTreeNodeTopological<Index_, typename SpaceWrapperType::ScalarType>;
-  using BuildRKdTreeType =
-      internal::BuildRKdTree<NodeType, SpaceWrapperType::Dim, SplittingRule_>;
-  using RKdTreeDataType = typename BuildRKdTreeType::RKdTreeDataType;
+  using RKdTreeDataType =
+      internal::RKdTreeHhData<NodeType, SpaceWrapperType::Dim>;
 
  public:
   //! \brief Size type.
@@ -42,8 +38,12 @@ class KdForest {
   KdForest(SpaceType space, SizeType max_leaf_size, SizeType forest_size)
       : space_(std::move(space)),
         metric_(),
-        data_(BuildRKdTreeType()(
-            SpaceWrapperType(space_), max_leaf_size, forest_size)) {}
+        data_(internal::BuildRKdTree<RKdTreeDataType, Dim>()(
+            SpaceWrapperType(space_),
+            max_leaf_size_t(max_leaf_size),
+            bounds_from_space,
+            sliding_midpoint_max_side,
+            forest_size)) {}
 
   //! \brief The KdForest cannot be copied.
   //! \details The KdForest uses pointers to nodes and copying pointers is not
@@ -117,16 +117,12 @@ class KdForest {
 };
 
 template <typename Space_>
-KdForest(Space_, Size)
-    -> KdForest<Space_, L2Squared, SplittingRule::kSlidingMidpoint, int>;
-
-template <
-    typename Metric_ = L2Squared,
-    SplittingRule SplittingRule_ = SplittingRule::kSlidingMidpoint,
-    typename Index_ = int,
-    typename Space_>
-auto MakeKdForest(Space_&& space, Size max_leaf_size, Size forest_size) {
-  return KdForest<std::decay_t<Space_>, Metric_, SplittingRule_, Index_>(
+KdForest(Space_, Size, Size) -> KdForest<Space_, L2Squared, int>;
+
+template <typename Metric_ = L2Squared, typename Index_ = int, typename Space_>
+KdForest<std::decay_t<Space_>, Metric_, Index_> MakeKdForest(
+    Space_&& space, Size max_leaf_size, Size forest_size) {
+  return KdForest<std::decay_t<Space_>, Metric_, Index_>(
       std::forward<Space_>(space), max_leaf_size, forest_size);
 }
 
diff --git a/src/pico_tree/CMakeLists.txt b/src/pico_tree/CMakeLists.txt
@@ -14,7 +14,7 @@ target_compile_features(${PROJECT_NAME} INTERFACE cxx_std_17)
 set_target_properties(${PROJECT_NAME} PROPERTIES EXPORT_NAME ${PROJECT_PACKAGE_NAME})
 target_compile_options(${PROJECT_NAME} INTERFACE
      $<$<OR:$<CXX_COMPILER_ID:Clang>,$<CXX_COMPILER_ID:AppleClang>,$<CXX_COMPILER_ID:GNU>>:
-          -Wall>
+          -Wall -Werror>
      $<$<CXX_COMPILER_ID:MSVC>:
           /W4>)
 
diff --git a/src/pico_tree/pico_tree/internal/kd_tree_builder.hpp b/src/pico_tree/pico_tree/internal/kd_tree_builder.hpp
diff --git a/src/pico_tree/pico_tree/kd_tree.hpp b/src/pico_tree/pico_tree/kd_tree.hpp
diff --git a/src/pyco_tree/pico_tree/_pyco_tree/kd_tree.hpp b/src/pyco_tree/pico_tree/_pyco_tree/kd_tree.hpp
diff --git a/test/pico_tree/kd_tree_test.cpp b/test/pico_tree/kd_tree_test.cpp
