Added the LInf metric.

Documentation updated.

Author: Jaybro

README.md

@@ -29,7 +29,7 @@ KdTree:
 * Nearest neighbor, approximate nearest neighbor, radius, box, and customizable nearest neighbor searches.
 * [Metrics](https://en.wikipedia.org/wiki/Metric_(mathematics)):
   * Support for topological spaces with identifications. E.g., points on the circle `[-pi, pi]`.
-  * Available metrics: `L1`, `L2Squared`, `SO2`, and `SE2Squared`. Metrics can be customized.
+  * Available metrics: `L1`, `L2Squared`, `LInf`, `SO2`, and `SE2Squared`. Metrics can be customized.
 * Multiple tree splitting rules: `kLongestMedian`, `kMidpoint` and `kSlidingMidpoint`.
 * Compile time and run time known dimensions.
 * Static tree builds.
@@ -51,8 +51,8 @@ PicoTree can interface with different types of points and point sets through tra
 
 # Examples
 
-* [Minimal working example](./examples/kd_tree/kd_tree_minimal.cpp) using an `std::vector<>` of points.
-* [Creating a KdTree](./examples/kd_tree/kd_tree_creation.cpp) and taking the input by value or reference.
+* [Minimal working example](./examples/kd_tree/kd_tree_minimal.cpp) for building and querying a KdTree.
+* [Creating a KdTree](./examples/kd_tree/kd_tree_creation.cpp) and having it take the input by value or reference.
 * Using the KdTree's [search](./examples/kd_tree/kd_tree_search.cpp) capabilities.
 * Working with [dynamic size arrays](./examples/kd_tree/kd_tree_dynamic_arrays.cpp).
 * Supporting a [custom point type](./examples/kd_tree/kd_tree_custom_point_type.cpp).

src/pico_tree/pico_tree/internal/box.hpp

@@ -27,8 +27,8 @@ class BoxBase {
   static constexpr SizeType Dim = BoxTraits<Derived>::Dim;
   static_assert(Dim == kDynamicSize || Dim > 0, "DIM_MUST_BE_DYNAMIC_OR_>_0");
 
-  //! \brief Returns true if \p x is contained. A point on the edge considered
-  //! inside the box.
+  //! \brief Returns true if \p x is contained. A point on the edge is
+  //! considered inside the box.
   constexpr bool Contains(ScalarType const* x) const {
     // We use derived().size() which includes the constexpr part. Otherwise a
     // small trait needs to be written.

src/pico_tree/pico_tree/metric.hpp

@@ -210,6 +210,41 @@ struct L2Squared {
   }
 };
 
+struct LInf {
+  //! \brief This tag specifies the supported space by this metric.
+  using SpaceTag = EuclideanSpaceTag;
+
+  template <
+      typename InputIterator1,
+      typename InputSentinel1,
+      typename InputIterator2>
+  constexpr auto operator()(
+      InputIterator1 begin1, InputSentinel1 end1, InputIterator2 begin2) const {
+    using ScalarType =
+        typename std::iterator_traits<InputIterator1>::value_type;
+
+    ScalarType d{};
+
+    for (; begin1 != end1; ++begin1, ++begin2) {
+      d = std::max(d, internal::Distance(*begin1, *begin2));
+    }
+
+    return d;
+  }
+
+  //! \brief Calculates the distance between two coordinates.
+  template <typename Scalar_>
+  constexpr Scalar_ operator()(Scalar_ x, Scalar_ y) const {
+    return internal::Distance(x, y);
+  }
+
+  //! \brief Returns the absolute value of \p x.
+  template <typename Scalar_>
+  constexpr Scalar_ operator()(Scalar_ x) const {
+    return std::abs(x);
+  }
+};
+
 //! \brief The SO2 metric measures distances on the unit circle S1. It is the
 //! intrinsic metric of points in R2 on S1 given by the great-circel distance.
 //! \details Named after the Special Orthogonal Group of dimension 2. The circle

src/pico_tree/pico_tree/opencv_traits.hpp

@@ -8,17 +8,19 @@
 //! \file opencv_traits.hpp
 //! \brief Contains traits that provide OpenCV support for PicoTree.
 //! \details The following is supported:
-//! * std::vector<cv::Point_<>>
-//! * std::vector<cv::Point3_<>>
-//! * std::vector<cv::Vec_<>>
-//! * cv::Mat
+//! * cv::Vec_<> as a point type.
+//! * cv::Mat as a space type.
 
 namespace pico_tree {
 
 //! \brief PointTraits provides an interface for cv::Point_<>.
+//! \details PointTraits<cv::Point_<Scalar_>> violates the strict aliasing rule
+//! by interpreting a struct of scalars as an array of scalars and using this
+//! specialization is therefore UB. Note that this specialization will work in
+//! practice but you have been warned. Don't use it to avoid UB.
 template <typename Scalar_>
 struct PointTraits<cv::Point_<Scalar_>> {
-  static_assert(sizeof(cv::Point_<Scalar_>) == (sizeof(Scalar_) * 2), "");
+  static_assert(sizeof(cv::Point_<Scalar_>) == sizeof(Scalar_[2]), "");
 
   //! \brief Supported point type.
   using PointType = cv::Point_<Scalar_>;
@@ -39,9 +41,13 @@ struct PointTraits<cv::Point_<Scalar_>> {
 };
 
 //! \brief PointTraits provides an interface for cv::Point3_<>.
+//! \details PointTraits<cv::Point3_<Scalar_>> violates the strict aliasing rule
+//! by interpreting a struct of scalars as an array of scalars and using this
+//! specialization is therefore UB. Note that this specialization will work in
+//! practice but you have been warned. Don't use it to avoid UB.
 template <typename Scalar_>
 struct PointTraits<cv::Point3_<Scalar_>> {
-  static_assert(sizeof(cv::Point3_<Scalar_>) == (sizeof(Scalar_) * 3), "");
+  static_assert(sizeof(cv::Point3_<Scalar_>) == sizeof(Scalar_[3]), "");
 
   //! \brief Supported point type.
   using PointType = cv::Point3_<Scalar_>;

test/pico_tree/metric_test.cpp

@@ -5,8 +5,6 @@
 #include <pico_tree/metric.hpp>
 #include <pico_understory/metric.hpp>
 
-using PointX = Point2f;
-
 template <typename Metric_, typename P0, typename P1>
 inline auto Distance(Metric_ const& metric, P0 const& p0, P1 const& p1) {
   auto w0 = pico_tree::internal::PointWrapper<P0>(p0);
@@ -15,8 +13,8 @@ inline auto Distance(Metric_ const& metric, P0 const& p0, P1 const& p1) {
 }
 
 TEST(MetricTest, L1) {
-  PointX p0{2.0f, 4.0f};
-  PointX p1{10.0f, 1.0f};
+  Point2f p0{2.0f, 4.0f};
+  Point2f p1{10.0f, 1.0f};
 
   pico_tree::L1 metric;
 
@@ -26,8 +24,8 @@ TEST(MetricTest, L1) {
 }
 
 TEST(MetricTest, L2) {
-  PointX p0{7.0f, 5.0f};
-  PointX p1{10.0f, 1.0f};
+  Point2f p0{7.0f, 5.0f};
+  Point2f p1{10.0f, 1.0f};
 
   pico_tree::L2 metric;
 
@@ -37,8 +35,8 @@ TEST(MetricTest, L2) {
 }
 
 TEST(MetricTest, L2Squared) {
-  PointX p0{2.0f, 4.0f};
-  PointX p1{10.0f, 1.0f};
+  Point2f p0{2.0f, 4.0f};
+  Point2f p1{10.0f, 1.0f};
 
   pico_tree::L2Squared metric;
 
@@ -47,6 +45,17 @@ TEST(MetricTest, L2Squared) {
   EXPECT_FLOAT_EQ(metric(-3.1f), 9.61f);
 }
 
+TEST(MetricTest, LInf) {
+  Point2f p0{2.0f, 4.0f};
+  Point2f p1{10.0f, 1.0f};
+
+  pico_tree::LInf metric;
+
+  EXPECT_FLOAT_EQ(Distance(metric, p0, p1), 8.0f);
+  EXPECT_FLOAT_EQ(metric(-3.1f, 8.9f), 12.0f);
+  EXPECT_FLOAT_EQ(metric(-3.1f), 3.1f);
+}
+
 TEST(MetricTest, SO2) {
   Point1f p0{1.0f};
   Point1f p1{1.1f};