Added format_mnist.hpp.

Moved formats to pico_toolshed.
Small documentation and formatting updates.

Author: Jaybro

CMakeLists.txt

@@ -2,36 +2,37 @@
 # CMake version 3.9 provides OpenMP per language.
 cmake_minimum_required(VERSION 3.12)
 
-include (${CMAKE_CURRENT_SOURCE_DIR}/cmake/utils.cmake)
+include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/utils.cmake)
 
 project(pico_tree
     LANGUAGES CXX
     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)
+if(NOT CMAKE_BUILD_TYPE)
     set(CMAKE_BUILD_TYPE "Release")
 endif()
 
-################################################################################
+# ##############################################################################
 # PicoTree, examples, unit tests and documentation.
-################################################################################
-
+# ##############################################################################
 set(PROJECT_PACKAGE_NAME "PicoTree")
 add_subdirectory(src)
 
 # Ignored when running cmake from setup.py using scikit-build.
 if(NOT SKBUILD)
     option(BUILD_EXAMPLES "Enable the creation of PicoTree examples." ON)
+
     if(BUILD_EXAMPLES)
         add_subdirectory(examples)
     endif()
 
     include(CTest)
     find_package(GTest QUIET)
+
     if(BUILD_TESTING)
-        if (GTEST_FOUND)
+        if(GTEST_FOUND)
             # Tests are dependent on some common code.
             # For now, the understory is considered important enough to be tested.
             if(NOT TARGET pico_toolshed)
@@ -49,12 +50,13 @@ if(NOT SKBUILD)
 
     find_package(Doxygen QUIET)
     option(BUILD_DOCS "Build documentation with Doxygen." ON)
+
     if(BUILD_DOCS)
         if(DOXYGEN_FOUND)
             set(DOC_TARGET_NAME ${PROJECT_NAME}_doc)
+
             # Hide the internal namespace from the documentation.
             # set(DOXYGEN_EXCLUDE_SYMBOLS "internal")
-
             doxygen_add_docs(
                 ${DOC_TARGET_NAME}
                 src/pico_tree)

README.md

@@ -27,9 +27,10 @@ Available under the [MIT](https://en.wikipedia.org/wiki/MIT_License) license.
 
 KdTree:
 * Nearest neighbor, approximate nearest neighbor, radius, box, and customizable nearest neighbor searches.
-* [Metrics](https://en.wikipedia.org/wiki/Metric_(mathematics)):
+* 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 metrics: `L1`, `L2Squared`, `LInf`, `SO2`, and `SE2Squared`. Metrics can be customized.
+  * Available distance functions: `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.

examples/CMakeLists.txt

@@ -9,6 +9,7 @@ add_subdirectory(pico_understory)
 add_subdirectory(kd_tree)
 
 find_package(Eigen3 QUIET)
+
 if(Eigen3_FOUND)
     message(STATUS "Eigen3 found. Building Eigen example.")
     add_subdirectory(eigen)
@@ -17,6 +18,7 @@ else()
 endif()
 
 find_package(OpenCV QUIET)
+
 if(OpenCV_FOUND)
     message(STATUS "OpenCV found. Building OpenCV example.")
     add_subdirectory(opencv)
@@ -25,6 +27,7 @@ else()
 endif()
 
 find_package(benchmark QUIET)
+
 if(benchmark_FOUND)
     message(STATUS "benchmark found. Building PicoTree benchmarks.")
     add_subdirectory(benchmark)

examples/benchmark/CMakeLists.txt

@@ -3,21 +3,21 @@ function(add_benchmark TARGET_NAME)
     set_default_target_properties(${TARGET_NAME})
     target_link_libraries(${TARGET_NAME}
         PRIVATE
-            pico_toolshed
-            benchmark::benchmark
+        pico_toolshed
+        benchmark::benchmark
     )
 endfunction()
 
-################################################################################
+# ##############################################################################
 # bm_pico_kd_tree, bm_pico_cover_tree, bm_nanoflann, bm_opencv_flann
-################################################################################
-
+# ##############################################################################
 add_benchmark(bm_pico_kd_tree)
 
 add_benchmark(bm_pico_cover_tree)
 target_link_libraries(bm_pico_cover_tree PRIVATE pico_understory)
 
 find_package(nanoflann QUIET)
+
 if(nanoflann_FOUND)
     message(STATUS "nanoflann found. Building nanoflann benchmark.")
     add_benchmark(bm_nanoflann)
@@ -29,6 +29,7 @@ endif()
 # The FLANN respository does not provide a flannConfig.cmake. So it's more
 # easy to go with the OpenCV one.
 find_package(OpenCV COMPONENTS core flann QUIET)
+
 if(OpenCV_FOUND)
     message(STATUS "OpenCV found. Building OpenCV FLANN benchmark.")
     add_benchmark(bm_opencv_flann)
@@ -37,25 +38,23 @@ else()
     message(STATUS "OpenCV not found. OpenCV FLANN benchmark skipped.")
 endif()
 
-################################################################################
+# ##############################################################################
 # uosr_to_bin
-################################################################################
-
+# ##############################################################################
 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)
 
-################################################################################
+# ##############################################################################
 # bin_to_ascii
-################################################################################
-
+# ##############################################################################
 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)
 
-################################################################################
+# ##############################################################################
 # plot_benchmarks
-################################################################################
+# ##############################################################################
 
 # TODO These don't get deleted when running: make clean
 add_custom_target(plot_benchmarks ALL

examples/benchmark/benchmark.hpp

@@ -1,9 +1,8 @@
 #include <benchmark/benchmark.h>
 
+#include <pico_toolshed/format/format_bin.hpp>
 #include <pico_toolshed/point.hpp>
 
-#include "format_bin.hpp"
-
 // 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
@@ -28,8 +27,8 @@ class Benchmark : public benchmark::Fixture {
   Benchmark() {
     // Here you may need to be patient depending on the size of the binaries.
     // Loaded for each benchmark.
-    pico_tree::ReadBin("./scans0.bin", &points_tree_);
-    pico_tree::ReadBin("./scans1.bin", &points_test_);
+    pico_tree::ReadBin("./scans0.bin", points_tree_);
+    pico_tree::ReadBin("./scans1.bin", points_test_);
   }
 
  protected:

examples/benchmark/bin_to_ascii.cpp

@@ -1,9 +1,8 @@
 #include <filesystem>
+#include <pico_toolshed/format/format_ascii.hpp>
+#include <pico_toolshed/format/format_bin.hpp>
 #include <pico_toolshed/point.hpp>
 
-#include "format_ascii.hpp"
-#include "format_bin.hpp"
-
 int main() {
   std::filesystem::path dirname_root = ".";
   std::filesystem::path filename_bin = "scans.bin";
@@ -16,7 +15,7 @@ int main() {
   } else if (!std::filesystem::exists(path_ascii)) {
     std::cout << "Reading points in bin format..." << std::endl;
     std::vector<Point3f> points;
-    pico_tree::ReadBin(path_bin.string(), &points);
+    pico_tree::ReadBin(path_bin.string(), points);
     std::cout << "Read " << points.size() << " points." << std::endl;
     std::cout << "Writing points to ascii xyz format..." << std::endl;
     pico_tree::WriteAscii(path_ascii.string(), points);

examples/benchmark/uosr_to_bin.cpp

@@ -1,7 +1,6 @@
 #include <filesystem>
-
-#include "format_bin.hpp"
-#include "format_uosr.hpp"
+#include <pico_toolshed/format/format_bin.hpp>
+#include <pico_toolshed/format/format_uosr.hpp>
 
 int main() {
   std::filesystem::path dirname_root = ".";
@@ -11,7 +10,7 @@ int main() {
   if (!std::filesystem::exists(path_bin)) {
     std::cout << "Reading scans in uosr format..." << std::endl;
     std::vector<Point3f> points;
-    pico_tree::ReadUosr(dirname_root.string(), &points);
+    pico_tree::ReadUosr(dirname_root.string(), points);
     std::cout << "Read " << points.size() << " points." << std::endl;
     std::cout << "Writing scans to bin xyz format..." << std::endl;
     pico_tree::WriteBin(path_bin.string(), points);

examples/pico_toolshed/pico_toolshed/format/endian.hpp

@@ -0,0 +1,54 @@
+#pragma once
+
+#include <cstddef>
+#include <type_traits>
+
+namespace pico_tree::internal {
+
+template <typename T>
+T SwapEndian(T const& u) {
+  T s;
+
+  std::byte const* up = reinterpret_cast<std::byte const*>(&u);
+  std::byte* sp = reinterpret_cast<std::byte*>(&s);
+  for (std::size_t i = 0; i < sizeof(T); ++i) {
+    sp[i] = up[sizeof(T) - i - 1];
+  }
+
+  return s;
+}
+
+template <typename T_>
+T_ BigEndianToNative(T_ v) {
+  static_assert(std::is_integral_v<T_>, "NOT_AN_INTEGRAL_TYPE");
+  static_assert(sizeof(T_) <= sizeof(std::size_t), "SIZE_UNSUPPORTED");
+
+  std::byte* v_object = reinterpret_cast<std::byte*>(&v);
+
+  T_ native{};
+  for (std::size_t i = 0; i < sizeof(T_); ++i) {
+    native |= static_cast<T_>(
+        static_cast<std::size_t>(v_object[i]) << ((sizeof(T_) - 1 - i) * 8));
+  }
+
+  return native;
+}
+
+//! \brief Stores the value of an integral type assuming big endian byte
+//! ordering.
+//! \details The idea is to be oblivious to the native endianness. When a big
+//! endian value is read it can be converted to its native counterpart. If the
+//! native endianness equals big endian then we're basically making a very
+//! elaborate copy. However, use of this class should be quite minimal.
+template <typename T_>
+struct BigEndian {
+  static_assert(std::is_integral_v<T_>, "NOT_AN_INTEGRAL_TYPE");
+
+  T_ operator()() const { return BigEndianToNative(value); }
+
+  operator T_() const { return this->operator()(); }
+
+  T_ value;
+};
+
+}  // namespace pico_tree::internal

examples/benchmark/format_ascii.hpp renamed to examples/pico_toolshed/pico_toolshed/format/format_ascii.hpp

@@ -18,7 +18,7 @@ void WriteBin(std::string const& filename, std::vector<T> const& v) {
 }
 
 template <typename T>
-void ReadBin(std::string const& filename, std::vector<T>* v) {
+void ReadBin(std::string const& filename, std::vector<T>& v) {
   std::fstream stream =
       internal::OpenStream(filename, std::ios::in | std::ios::binary);
 
@@ -36,8 +36,8 @@ void ReadBin(std::string const& filename, std::vector<T>* v) {
   std::size_t const element_size = sizeof(T);
   std::size_t const element_count =
       static_cast<std::size_t>(byte_count / element_size);
-  v->resize(element_count);
-  stream.read(reinterpret_cast<char*>(&(*v)[0]), element_size * element_count);
+  v.resize(element_count);
+  stream.read(reinterpret_cast<char*>(&v[0]), element_size * element_count);
 }
 
 }  // namespace pico_tree