Interface Rework (#28)

Size type consistency.
Updated containers and adaptors.
CMake qol update.
Sequence renamed to Point.
SearchBox ReportNode update. Small 3-5% benchark performance improvement.
Moved KdTree functors to their own header files.
Split KdTree unit tests.
Removed the KdTree Dim template argument.
KdTree Splitter argument type replaced.
Google Code Guide update for output function arguments.
Added SpaceWrapper to simplify interfacing with a Space.
Minimum required C++ standard updated from C++11 to C++17.
kDynamicDim to kDynamicSize.
Minor KdTreeBuilder rework.
Moved KdTreeData to its own header file.
Renamed StdPointTraits to PointTraits.
PointTraits moved to its own header file.
Eigen and OpenCV header files renamed.
Map and its traits moved into PicoTree from PycoTree.
CvTraits now uses PointMap instead of CvMatRow.
Metrics now use iterators instead of points.
Trait dependency removed for metrics.
Eigen metrics removed.
Added PointWrapper to simplify interfacing with a Point.
Split space and point related traits.
Updated Aknn functions to be overloads of the Knn functions.
Added the SE2Squared metric.
Added the Midpoint splitting rule.
Code reduction/reuse of point classes.
Traits PointTraitsFor requirement removed. PointTraits used directly.
Traits IndexType requirement removed. Moved (back) to the KdTree.
Traits PointSdim and PointCoords requirement removed. PointTraits used directly.
Created SpaceTraits and updated Eigen, OpenCV, Vector and Map traits accordingly.
KdTree and CoverTree now take a Space as template argument, not the traits.
Split up the CoverTree.
Added default SpaceTraits overload for reference_wrapper<SpaceType>.
More consistent interface between points, spaces and their traits.
Using SpaceWrapper and PointWrapper in unit tests.
Version updated to 8.0.0.

Author: Jaybro

CMakeLists.txt

@@ -6,8 +6,8 @@ include (${CMAKE_CURRENT_SOURCE_DIR}/cmake/utils.cmake)
 
 project(pico_tree
     LANGUAGES CXX
-    VERSION 0.7.5
-    DESCRIPTION "PicoTree is a C++ header only library with Python bindings for nearest neighbor searches and range searches using a KdTree."
+    VERSION 0.8.0
+    DESCRIPTION "PicoTree is a C++ header only library for fast nearest neighbor searches and range searches using a KdTree."
     HOMEPAGE_URL "https://github.com/Jaybro/pico_tree")
 
 if (NOT CMAKE_BUILD_TYPE)
@@ -59,7 +59,7 @@ if(NOT SKBUILD)
                 ${DOC_TARGET_NAME}
                 src/pico_tree)
 
-            message(STATUS "Doxygen found. Documentation can be build as: make ${DOC_TARGET_NAME}")
+            message(STATUS "Doxygen found. To build the documentation: cmake --build . --target ${DOC_TARGET_NAME}")
         else()
             message(STATUS "Doxygen not found. Documentation cannot be build.")
         endif()

COPYING.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020,2021,2022 Jonathan Broere
+Copyright (c) 2020,2021,2022,2023 Jonathan Broere
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

README.md

@@ -13,7 +13,7 @@ See the table below to get an impression of the performance provided by the [KdT
 | [Scikit-learn KDTree][skkd] 0.22.2  | ...       | 12.2s         | ...        | 44.5s       |
 | [pykdtree][pykd] 1.3.6              | ...       | 1.0s          | ...        | 6.6s        |
 | [OpenCV FLANN][cvfn] 4.6.0          | 1.9s      | ...           | 4.7s       | ...         |
-| PicoTree KdTree v0.7.5              | 0.9s      | 1.0s          | 2.8s       | 3.1s        |
+| PicoTree KdTree v0.8.0              | 0.9s      | 1.0s          | 2.8s       | 3.1s        |
 
 It compares the performance of the build and query algorithms using two [LiDAR](./docs/benchmark.md) based point clouds of sizes 7733372 and 7200863. The first point cloud is used to compare build times and both are used to compare query times. All benchmarks were generated with the following parameters: `max_leaf_size=10`, `knn=1` and `OMP_NUM_THREADS=1`. A more detailed [C++ comparison](./docs/benchmark.md) of PicoTree is available with respect to [nanoflann][nano].
 
@@ -27,22 +27,27 @@ Available under the [MIT](https://en.wikipedia.org/wiki/MIT_License) license.
 
 # Capabilities
 
-* KdTree
-  * Nearest neighbors, approximate nearest neighbors, radius, and box searches.
-  * Customizable nearest neighbor searches, [metrics](https://en.wikipedia.org/wiki/Metric_(mathematics)) and tree splitting techniques.
-  * Support for topological spaces with identifications. E.g., points on the circle `[-pi, pi]`.
+* KdTree:
+  * Nearest neighbor, approximate nearest neighbor, radius, box, and customizable nearest neighbor searches.
+  * Multiple tree splitting rules: `kLongestMedian`, `kMidpoint` and `kSlidingMidpoint`.
+  * [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.
   * Compile time and run time known dimensions.
   * Static tree builds.
   * Thread safe queries.
-* PicoTree can interface with different types of points or point sets through a traits class. This can be a custom implementation or one of the traits classes provided by this library:
-  * `pico_tree::StdTraits<>` supports interfacing with any `std::vector<PointType>`. It requires a specialization of `pico_tree::StdPointTraits<>` for each `PointType`. There are default `pico_tree::StdPointTraits<>` available for Eigen and OpenCV point types.
-  * `pico_tree::EigenTraits<>` supports interfacing with Eigen matrices.
-  * `pico_tree::CvTraits<>` supports interfacing with OpenCV matrices.
+* PicoTree can interface with different types of points or point sets through traits classes. These can be custom implementations or one of the `pico_tree::PointTraits<>` and `pico_tree::SpaceTraits<>` classes provided by this library. There is default support for the following data types:
+  * `std::vector<PointType>`.
+    * A specialization of `pico_tree::PointTraits<>` is required for each `PointType`. There are traits available for Eigen and OpenCV point types.
+  * `pico_tree::SpaceMap<PointType>` and `pico_tree::PointMap<>`.
+    * These classes allow interfacing with raw pointers. It is assumed that points and their coordinates are laid out contiguously in memory.
+  * `Eigen::Matrix` and `Eigen::Map<Eigen::Matrix>`.
+  * `cv::Mat`.
 
 # Examples
 
-* [Minimal working example](./examples/kd_tree/kd_tree_point_traits.cpp) for building and querying a KdTree using a custom point type.
-* Creating a [traits](./examples/kd_tree/kd_tree_traits.cpp) class for a custom type of point set.
+* [Minimal working example](./examples/kd_tree/kd_tree_minimal.cpp) using an std::vector of points.
+* Creating [traits](./examples/kd_tree/kd_tree_traits.cpp) classes for a custom point and point set.
 * Using the KdTree's [search](./examples/kd_tree/kd_tree_search.cpp) options and creating a custom search visitor.
 * Support for [Eigen](./examples/eigen/eigen.cpp) and [OpenCV](./examples/opencv/opencv.cpp) data types.
 * How to use the [KdTree with Python](./examples/python/kd_tree.py).
@@ -51,7 +56,7 @@ Available under the [MIT](https://en.wikipedia.org/wiki/MIT_License) license.
 
 Minimum:
 
-* A compiler that is compliant with the C++11 standard or higher.
+* A compiler that is compliant with the C++17 standard or higher.
 * [CMake](https://cmake.org/). It is also possible to just copy and paste the [pico_tree](./src/pico_tree/) directory into an include directory.
 
 Optional:
@@ -60,7 +65,7 @@ Optional:
 * [Google Test](https://github.com/google/googletest). Used for running unit tests.
 * [Eigen](http://eigen.tuxfamily.org). To run the example that shows how Eigen data types can be used in combination with PicoTree.
 * [OpenCV](https://opencv.org/). To run the OpenCV example that shows how to work with OpenCV data types.
-* [Google Benchmark](https://github.com/google/benchmark) and a compiler that is compliant with the C++17 standard are needed to run any of the benchmarks. The [nanoflann](https://github.com/jlblancoc/nanoflann) and [OpenCV](https://opencv.org/) benchmarks also require their respective libraries to be installed.
+* [Google Benchmark](https://github.com/google/benchmark) is needed to run any of the benchmarks. The [nanoflann](https://github.com/jlblancoc/nanoflann) and [OpenCV](https://opencv.org/) benchmarks also require their respective libraries to be installed.
 
 Python bindings:
 * [Python](https://www.python.org/). Version 3.7 or higher.

docs/benchmark.md

@@ -18,7 +18,7 @@ The different KdTree implementations are compared to each other with respect to
   * Nanoflann Midpoint variation.
   * PicoTree Sliding Midpoint (along the longest axis).
 * Radius search algorithm: The radius in meters divided by 10 (i.e. 1.5m and 3.0m).
-* Knn algorithm: The amount of neighbors searched.
+* Knn algorithm: The number of neighbors searched.
 
 The running time of the benchmark was kept reasonable by using two subsets of points and storing those in a simple binary format. The final point cloud sizes were as follows:
 

examples/CMakeLists.txt

@@ -24,13 +24,12 @@ else()
     message(STATUS "OpenCV not found. OpenCV example skipped.")
 endif()
 
-has_cxx_compile_feature(HAS_CPP17_FEATURE cxx_std_17)
 find_package(benchmark QUIET)
-if(benchmark_FOUND AND ${HAS_CPP17_FEATURE})
-    message(STATUS "benchmark and C++17 found. Building PicoTree benchmarks.")
+if(benchmark_FOUND)
+    message(STATUS "benchmark found. Building PicoTree benchmarks.")
     add_subdirectory(benchmark)
 else()
-    message(STATUS "benchmark or C++17 not found. PicoTree benchmarks skipped.")
+    message(STATUS "benchmark not found. PicoTree benchmarks skipped.")
 endif()
 
 # The Python examples only get copied when the bindings module will be build.

examples/benchmark/CMakeLists.txt

@@ -44,8 +44,6 @@ endif()
 add_executable(uosr_to_bin uosr_to_bin.cpp)
 set_default_target_properties(uosr_to_bin)
 target_link_libraries(uosr_to_bin PRIVATE pico_toolshed)
-# This executable requires <filesystem>
-target_compile_features(uosr_to_bin PRIVATE cxx_std_17)
 
 ################################################################################
 # bin_to_ascii
@@ -54,8 +52,6 @@ target_compile_features(uosr_to_bin PRIVATE cxx_std_17)
 add_executable(bin_to_ascii bin_to_ascii.cpp)
 set_default_target_properties(bin_to_ascii)
 target_link_libraries(bin_to_ascii PRIVATE pico_toolshed)
-# This executable requires <filesystem>
-target_compile_features(bin_to_ascii PRIVATE cxx_std_17)
 
 ################################################################################
 # plot_benchmarks

examples/benchmark/benchmark.hpp

@@ -4,7 +4,7 @@
 
 #include "format_bin.hpp"
 
-// It seems that there is a "threshold" to the amount of functions being
+// It seems that there is a "threshold" to the number of functions being
 // benchmarked. Having "too many" of them makes them become slow(er). This
 // appears to be due to code alignment. See similar issue and video referencing
 // that issue:

examples/benchmark/bm_nanoflann.cpp

@@ -79,8 +79,8 @@ BENCHMARK_DEFINE_F(BmNanoflann, KnnCt)(benchmark::State& state) {
     std::size_t sum = 0;
     for (auto const& p : points_test_) {
       benchmark::DoNotOptimize(
-          sum +=
-          tree.knnSearch(p.data, knn_count, indices.data(), distances.data()));
+          sum += tree.knnSearch(
+              p.data(), knn_count, indices.data(), distances.data()));
     }
   }
 }
@@ -135,7 +135,10 @@ BENCHMARK_DEFINE_F(BmNanoflann, RadiusCt)(benchmark::State& state) {
     for (auto const& p : points_test_) {
       benchmark::DoNotOptimize(
           sum += tree.radiusSearch(
-              p.data, squared, results, nanoflann::SearchParams{0, 0, false}));
+              p.data(),
+              squared,
+              results,
+              nanoflann::SearchParams{0, 0, false}));
     }
   }
 }

examples/benchmark/bm_opencv_flann.cpp

@@ -56,11 +56,13 @@ struct L2_3D {
 
 }  // namespace cvflann
 
-template <typename Scalar, int Dim>
+template <typename Scalar, std::size_t Dim>
 Scalar* RawCopy(std::vector<Point<Scalar, Dim>> const& points) {
   Scalar* copy = new Scalar[points.size() * Dim];
   std::copy(
-      points.begin()->data, points.begin()->data + points.size() * Dim, copy);
+      points.begin()->data(),
+      points.begin()->data() + points.size() * Dim,
+      copy);
   return copy;
 }
 
@@ -120,7 +122,7 @@ BENCHMARK_DEFINE_F(BmOpenCvFlann, KnnCt)(benchmark::State& state) {
     fl::Matrix<Scalar> mat_distances(distances.data(), 1, knn_count);
 
     for (auto& p : points_test_) {
-      fl::Matrix<Scalar> query(p.data, 1, 3);
+      fl::Matrix<Scalar> query(p.data(), 1, 3);
       tree.knnSearch(query, mat_indices, mat_distances, knn_count, psearch);
     }
   }

examples/benchmark/bm_pico_cover_tree.cpp

@@ -1,5 +1,6 @@
 #include <pico_toolshed/point.hpp>
 #include <pico_toolshed/scoped_timer.hpp>
+#include <pico_tree/vector_traits.hpp>
 #include <pico_understory/cover_tree.hpp>
 
 #include "benchmark.hpp"
@@ -10,11 +11,10 @@ class BmPicoCoverTree : public pico_tree::Benchmark {
 
 // Index explicitly set to int.
 template <typename PointX>
-using PicoTraits =
-    pico_tree::StdTraits<std::reference_wrapper<std::vector<PointX>>, int>;
+using PicoSpace = std::reference_wrapper<std::vector<PointX>>;
 
 template <typename PointX>
-using PicoCoverTree = pico_tree::CoverTree<PicoTraits<PointX>>;
+using PicoCoverTree = pico_tree::CoverTree<PicoSpace<PointX>>;
 
 // ****************************************************************************
 // Building the tree
@@ -54,7 +54,7 @@ BENCHMARK_DEFINE_F(BmPicoCoverTree, KnnCt)(benchmark::State& state) {
       ScopedTimer timer("query_group");
       for (; pi < group_end; ++pi) {
         auto const& p = points_test_[pi];
-        tree.SearchKnn(p, knn_count, &results);
+        tree.SearchKnn(p, knn_count, results);
         benchmark::DoNotOptimize(sum += results.size());
       }
     }