Added metric_lninf supporting negative infinity.

Renamed metric_linf to metric_lpinf and LInf to LPInf (positive infinity).
Renamed dynamic_size to dynamic_extent to avoid name collisions.
Simplified both Euclidean and topological metrics.
Added an example showing how to create custom metrics.
Updated the benchmark table in the README.md file.
Added the metric_box_map class to remove code duplication.
Bug fix: toplogical_box.contains(topological_box).
Removed various warnings.

Author: Jaybro

README.md

@@ -6,14 +6,14 @@ PicoTree is a C++ header only library with [Python bindings](https://github.com/
 
 |                                     | Build C++ | Build Python  | Knn C++    | Knn Python  |
 | ----------------------------------- | --------- | ------------- | ---------- | ----------- |
-| [nanoflann][nano] v1.5.0            | 2.9s      | ...           | 3.2s       | ...         |
-| [SciPy KDTree][spkd] 1.11.0         | ...       | 4.5s          | ...        | 563.6s      |
-| [Scikit-learn KDTree][skkd] 1.2.2   | ...       | 6.2s          | ...        | 42.2s       |
-| [pykdtree][pykd] 1.3.7              | ...       | 1.0s          | ...        | 6.6s        |
-| [OpenCV FLANN][cvfn] 4.6.0          | 1.9s      | ...           | 4.7s       | ...         |
-| PicoTree KdTree v0.8.3              | 0.9s      | 1.0s          | 2.8s       | 3.1s        |
+| [nanoflann][nano] v1.7.1            | 1.42s     | ...           | 1.40s      | ...         |
+| [SciPy KDTree][spkd] 1.15.2         | ...       | 1.37s         | ...        | 212.04s     |
+| [Scikit-learn KDTree][skkd] 1.6.1   | ...       | 3.60s         | ...        | 11.90s      |
+| [pykdtree][pykd] 1.3.7              | ...       | 0.43s         | ...        | 2.95s       |
+| [OpenCV FLANN][cvfn] 4.11.0         | 0.99s     | ...           | 2.30s      | ...         |
+| PicoTree KdTree v1.0.0              | 0.54s     | 0.54s         | 1.13s      | 1.64s       |
 
-Two [LiDAR](./docs/benchmark.md) based point clouds of sizes 7733372 and 7200863 were used to generate these numbers. The first point cloud was the input to the build algorithm and the second to the query algorithm. All benchmarks were run on a single thread with the following parameters: `max_leaf_size=10` and `knn=1`. A more detailed [C++ comparison](./docs/benchmark.md) of PicoTree is available with respect to [nanoflann][nano].
+These numbers were generated on an Intel Core i9-14900HX using two [LiDAR](./docs/benchmark.md) based point clouds of sizes 7733372 and 7200863. The first point cloud was the input to the build algorithm and the second to the query algorithm. All benchmarks were run on a single thread with the following parameters: `max_leaf_size=10` and `knn=1`. A more detailed [C++ comparison](./docs/benchmark.md) of PicoTree is available with respect to [nanoflann][nano].
 
 [nano]: https://github.com/jlblancoc/nanoflann
 [spkd]: https://docs.scipy.org/doc/scipy/reference/generated/scipy.spatial.KDTree.html
@@ -26,12 +26,18 @@ Available under the [MIT](https://en.wikipedia.org/wiki/MIT_License) license.
 # Capabilities
 
 KdTree:
-* Nearest neighbor, approximate nearest neighbor, radius, box, and customizable nearest neighbor searches.
-* Different [metric spaces](https://en.wikipedia.org/wiki/Metric_space):
-  * Support for topological spaces with identifications. E.g., points on the circle `[-pi, pi]`.
-  * Available distance functions: `metric_l1`, `metric_l2_squared`, `metric_linf`, `metric_so2`, and `metric_se2_squared`.
-  * Metrics can be customized.
-* Multiple tree splitting rules: `median_max_side_t`, `midpoint_max_side_t` and `sliding_midpoint_max_side_t`.
+* Search functions:
+  * Exact nearest neighbor, radius and box searches.
+  * Approximate nearest neighbor and radius searches.
+  * Custom nearest neighbor searches.
+* [Metric spaces](https://en.wikipedia.org/wiki/Metric_space):
+  * Support for spaces with identifications. E.g., points on the circle S<sup>1</sup> `[0, 1]`.
+  * Available distance functions: `metric_l1`, `metric_l2_squared`, `metric_lpinf`, `metric_lninf`, `metric_so2`, and `metric_se2_squared`.
+  * Custom metrics.
+* Multiple build options:
+  * Tree splitting rules: `median_max_side_t`, `midpoint_max_side_t` and `sliding_midpoint_max_side_t`.
+  * Tree split stop conditions: `max_leaf_size_t` and `max_leaf_depth_t`.
+  * Custom starting bounding box.
 * Compile time and run time known dimensions.
 * Static tree builds.
 * Thread safe queries.
@@ -59,6 +65,7 @@ PicoTree can interface with different types of points and point sets through tra
 * Supporting a [custom point type](./examples/kd_tree/kd_tree_custom_point_type.cpp).
 * Supporting a [custom space type](./examples/kd_tree/kd_tree_custom_space_type.cpp).
 * Creating a [custom search visitor](./examples/kd_tree/kd_tree_custom_search_visitor.cpp).
+* Creating a [custom metric](./examples/kd_tree/kd_tree_custom_metric.cpp).
 * [Saving and loading](./examples/kd_tree/kd_tree_save_and_load.cpp) a KdTree to and from a file.
 * Support for [Eigen](./examples/eigen/eigen.cpp) and [OpenCV](./examples/opencv/opencv.cpp) data types.
 * [Running the KdTree and KdForest](./examples/kd_forest/kd_forest.cpp) on the [MNIST](http://yann.lecun.com/exdb/mnist/) and [SIFT](http://corpus-texmex.irisa.fr/) datasets.

examples/benchmark/bm_opencv_flann.cpp

@@ -99,7 +99,7 @@ BENCHMARK_REGISTER_F(BmOpenCvFlann, BuildRt)
 
 BENCHMARK_DEFINE_F(BmOpenCvFlann, KnnCt)(benchmark::State& state) {
   int max_leaf_size = static_cast<int>(state.range(0));
-  int knn_count = static_cast<int>(state.range(1));
+  std::size_t knn_count = static_cast<std::size_t>(state.range(1));
 
   // Reorder will change the order of the input to fit the generated indices,
   // but it will replace (and delete) the original input. The reorder option
@@ -126,7 +126,12 @@ BENCHMARK_DEFINE_F(BmOpenCvFlann, KnnCt)(benchmark::State& state) {
 
     for (auto& p : points_test_) {
       fl::Matrix<scalar_type> query(p.data(), 1, 3);
-      tree.knnSearch(query, mat_indices, mat_distances, knn_count, psearch);
+      tree.knnSearch(
+          query,
+          mat_indices,
+          mat_distances,
+          static_cast<int>(knn_count),
+          psearch);
     }
   }
 }

examples/benchmark/bm_pico_kd_tree.cpp

@@ -27,15 +27,17 @@ using pico_kd_tree_rt_sld_mid = pico_tree::kd_tree<pico_rt_space<Point_>>;
 // ****************************************************************************
 
 BENCHMARK_DEFINE_F(BmPicoKdTree, BuildCtSldMid)(benchmark::State& state) {
-  pico_tree::max_leaf_size_t max_leaf_size = state.range(0);
+  pico_tree::max_leaf_size_t max_leaf_size =
+      static_cast<pico_tree::size_t>(state.range(0));
 
   for (auto _ : state) {
     pico_kd_tree_ct_sld_mid<point_type> tree(points_tree_, max_leaf_size);
   }
 }
 
 BENCHMARK_DEFINE_F(BmPicoKdTree, BuildRtSldMid)(benchmark::State& state) {
-  pico_tree::max_leaf_size_t max_leaf_size = state.range(0);
+  pico_tree::max_leaf_size_t max_leaf_size =
+      static_cast<pico_tree::size_t>(state.range(0));
 
   for (auto _ : state) {
     pico_kd_tree_rt_sld_mid<point_type> tree(
@@ -59,8 +61,9 @@ BENCHMARK_REGISTER_F(BmPicoKdTree, BuildRtSldMid)
 // ****************************************************************************
 
 BENCHMARK_DEFINE_F(BmPicoKdTree, KnnCtSldMid)(benchmark::State& state) {
-  pico_tree::max_leaf_size_t max_leaf_size = state.range(0);
-  std::size_t knn_count = state.range(1);
+  pico_tree::max_leaf_size_t max_leaf_size =
+      static_cast<pico_tree::size_t>(state.range(0));
+  pico_tree::size_t knn_count = static_cast<pico_tree::size_t>(state.range(1));
 
   pico_kd_tree_ct_sld_mid<point_type> tree(points_tree_, max_leaf_size);
 
@@ -106,7 +109,8 @@ BENCHMARK_REGISTER_F(BmPicoKdTree, KnnCtSldMid)
 // ****************************************************************************
 
 BENCHMARK_DEFINE_F(BmPicoKdTree, RadiusCtSldMid)(benchmark::State& state) {
-  pico_tree::max_leaf_size_t max_leaf_size = state.range(0);
+  pico_tree::max_leaf_size_t max_leaf_size =
+      static_cast<pico_tree::size_t>(state.range(0));
   scalar_type radius =
       static_cast<scalar_type>(state.range(1)) / scalar_type(10.0);
   scalar_type squared = radius * radius;
@@ -145,7 +149,8 @@ BENCHMARK_REGISTER_F(BmPicoKdTree, RadiusCtSldMid)
 // ****************************************************************************
 
 BENCHMARK_DEFINE_F(BmPicoKdTree, BoxCtSldMid)(benchmark::State& state) {
-  pico_tree::max_leaf_size_t max_leaf_size = state.range(0);
+  pico_tree::max_leaf_size_t max_leaf_size =
+      static_cast<pico_tree::size_t>(state.range(0));
   scalar_type radius =
       static_cast<scalar_type>(state.range(1)) / scalar_type(10.0);
 
@@ -175,7 +180,8 @@ BENCHMARK_REGISTER_F(BmPicoKdTree, BoxCtSldMid)
     ->Args({14, 15});
 
 BENCHMARK_DEFINE_F(BmPicoKdTree, BoxRtSldMid)(benchmark::State& state) {
-  pico_tree::max_leaf_size_t max_leaf_size = state.range(0);
+  pico_tree::max_leaf_size_t max_leaf_size =
+      static_cast<pico_tree::size_t>(state.range(0));
   scalar_type radius =
       static_cast<scalar_type>(state.range(1)) / scalar_type(10.0);
 

examples/benchmark/nano_adaptor.hpp

@@ -21,7 +21,8 @@ class nano_adaptor {
 
   //! \brief Returns the dim'th component of the idx'th point in the class:
   inline scalar_type kdtree_get_pt(Index_ const idx, Index_ const dim) const {
-    return points_[idx].data()[dim];
+    return points_[static_cast<typename std::vector<Point_>::size_type>(idx)]
+        .data()[dim];
   }
 
   // Optional bounding-box computation: return false to default to a standard

examples/kd_tree/CMakeLists.txt

@@ -12,6 +12,8 @@ add_demo_executable(kd_tree_search)
 
 add_demo_executable(kd_tree_dynamic_arrays)
 
+add_demo_executable(kd_tree_custom_metric)
+
 add_demo_executable(kd_tree_custom_point_type)
 
 add_demo_executable(kd_tree_custom_space_type)

examples/kd_tree/kd_tree_creation.cpp

@@ -109,11 +109,11 @@ void space_type_deduction() {
   // space type when we want to change any of the other template arguments, such
   // as the metric type. In this case we can use the make_kd_tree method to make
   // life a bit easier.
-  auto tree2 = pico_tree::make_kd_tree<pico_tree::metric_linf>(
+  auto tree2 = pico_tree::make_kd_tree<pico_tree::metric_lpinf>(
       std::ref(points), max_leaf_size);
 
-  using kd_tree2_type =
-      pico_tree::kd_tree<std::reference_wrapper<space>, pico_tree::metric_linf>;
+  using kd_tree2_type = pico_tree::
+      kd_tree<std::reference_wrapper<space>, pico_tree::metric_lpinf>;
 
   static_assert(std::is_same_v<decltype(tree2), kd_tree2_type>);
 

examples/kd_tree/kd_tree_custom_metric.cpp

@@ -0,0 +1,132 @@
+#include <pico_toolshed/point.hpp>
+#include <pico_tree/kd_tree.hpp>
+#include <pico_tree/vector_traits.hpp>
+
+// This example shows how to create a custom metric for the kd_tree. The kd_tree
+// does not support metrics that "normalize" the distance between two points for
+// performance reasons. This means that, for example, the L2 metric is not
+// supported, but there is support for the L1 or L2^2 metric.
+//
+// There are two different categories of metrics: Euclidean and topological. A
+// Euclidean metric supports any R^n space where all axes are orthogonal with
+// respect to each other. A topological space is the same, but it allows
+// wrapping of coordinate values along any of the axes. An implementation for
+// both is provided below.
+
+// The LP^P metric is a generalization of the L2^2 metric.
+template <std::size_t P_>
+struct metric_lp_p {
+  static_assert(P_ > 0, "P_CANNOT_BE_ZERO");
+
+  // Indicate that this metric is a Euclidean one.
+  using space_category = pico_tree::euclidean_space_tag;
+
+  // Calculates the distance between two points.
+  template <typename InputIterator_>
+  auto operator()(
+      InputIterator_ begin1, InputIterator_ end1, InputIterator_ begin2) const {
+    using scalar_type =
+        typename std::iterator_traits<InputIterator_>::value_type;
+
+    scalar_type d{};
+    for (; begin1 != end1; ++begin1, ++begin2) {
+      d += operator()(*begin1 - *begin2);
+    }
+    return d;
+  }
+
+  // Returns the absolute value of x to the power of p.
+  template <typename Scalar_>
+  Scalar_ operator()(Scalar_ x) const {
+    return std::pow(std::abs(x), static_cast<Scalar_>(P_));
+  }
+};
+
+// This metric measures distances on the two dimensional ring torus T2. The
+// torus is the Cartesian product of two circles S1 x S1. The values of each of
+// the point coordinates should be within the range of [0...1].
+struct metric_t2_squared {
+  // Indicate that this metric is defined on a topological space. The
+  // topological_space_tag is required because the torus wraps around in both
+  // dimensions.
+  using space_category = pico_tree::topological_space_tag;
+
+  // Calculates the distance between two points.
+  template <typename InputIterator_>
+  auto operator()(
+      InputIterator_ begin1, InputIterator_ end1, InputIterator_ begin2) const {
+    using scalar_type =
+        typename std::iterator_traits<InputIterator_>::value_type;
+
+    scalar_type d{};
+    for (; begin1 != end1; ++begin1, ++begin2) {
+      d += pico_tree::squared_s1_distance(*begin1, *begin2);
+    }
+    return d;
+  }
+
+  // Distances are squared values.
+  template <typename Scalar_>
+  Scalar_ operator()(Scalar_ x) const {
+    return x * x;
+  }
+
+  template <typename UnaryPredicate_>
+  void apply_one_space([[maybe_unused]] int dim, UnaryPredicate_ p) const {
+    p(pico_tree::one_space_s1{});
+  }
+};
+
+void search_lp3_3() {
+  using point = pico_tree::point_2f;
+  using scalar = typename point::scalar_type;
+
+  pico_tree::max_leaf_size_t max_leaf_size = 12;
+  std::size_t point_count = 1024 * 1024;
+  scalar area_size = 10;
+
+  using kd_tree = pico_tree::kd_tree<std::vector<point>, metric_lp_p<3>>;
+  using neighbor = typename kd_tree::neighbor_type;
+
+  kd_tree tree(
+      pico_tree::generate_random_n<point>(point_count, area_size),
+      max_leaf_size);
+
+  neighbor nn;
+  tree.search_nn(point{area_size / scalar(2), area_size / scalar(2)}, nn);
+
+  std::cout << "Index closest point: " << nn.index << std::endl;
+}
+
+void search_t2() {
+  using point = pico_tree::point_2f;
+  using scalar = typename point::scalar_type;
+
+  pico_tree::max_leaf_size_t max_leaf_size = 12;
+  std::size_t point_count = 1024 * 1024;
+  scalar area_size = 1;
+
+  using kd_tree = pico_tree::kd_tree<std::vector<point>, metric_t2_squared>;
+  using neighbor = typename kd_tree::neighbor_type;
+
+  kd_tree tree(
+      pico_tree::generate_random_n<point>(point_count, area_size),
+      max_leaf_size);
+
+  std::array<neighbor, 8> knn;
+  tree.search_knn(point{area_size, area_size}, knn.begin(), knn.end());
+
+  // These prints show that wrapping near values 0 ~ 1 is supported.
+  std::cout << "Closest points (index, distance, point): " << std::endl;
+  for (auto const& nn : knn) {
+    std::cout << "  " << nn.index << ", " << nn.distance << ", ["
+              << tree.space()[static_cast<std::size_t>(nn.index)] << "]"
+              << std::endl;
+  }
+}
+
+int main() {
+  search_lp3_3();
+  search_t2();
+  return 0;
+}

examples/kd_tree/kd_tree_custom_point_type.cpp

@@ -17,7 +17,7 @@ template <>
 struct point_traits<PointXYZ> {
   using point_type = PointXYZ;
   using scalar_type = float;
-  // Spatial dimension. Set to pico_tree::dynamic_size when the dimension is
+  // Spatial dimension. Set to pico_tree::dynamic_extent when the dimension is
   // only known at run-time.
   static constexpr pico_tree::size_t dim = 3;
 

examples/kd_tree/kd_tree_custom_search_visitor.cpp

@@ -1,3 +1,4 @@
+#include <limits>
 #include <pico_toolshed/point.hpp>
 #include <pico_toolshed/scoped_timer.hpp>
 #include <pico_tree/kd_tree.hpp>

examples/kd_tree/kd_tree_custom_space_type.cpp

@@ -14,7 +14,7 @@ struct space_traits<std::deque<std::array<Scalar_, Dim_>>> {
   using space_type = std::deque<std::array<Scalar_, Dim_>>;
   using point_type = std::array<Scalar_, Dim_>;
   using scalar_type = Scalar_;
-  // Spatial dimension. Set to pico_tree::dynamic_size when the dimension is
+  // Spatial dimension. Set to pico_tree::dynamic_extent when the dimension is
   // only known at run-time.
   static constexpr pico_tree::size_t dim = Dim_;