Python bindings SizeType update.

Added LInf metric to the Python bindings.
Python code guide update.
Documentation update.

Author: Jaybro

examples/benchmark/plot_benchmarks.py

@@ -1,49 +1,48 @@
 #!/usr/bin/env python
 
-import argparse
-from argparse import ArgumentParser
+from argparse import ArgumentParser, FileType
 import json
 import re
 import matplotlib.pyplot as plt
 
 
 def create_arguments():
     parser = ArgumentParser(description='benchmark visualization tool')
-    parser.add_argument('-json_file', '-j', type=argparse.FileType('r'),
+    parser.add_argument('-json_file', '-j', type=FileType('r'),
                         required=True,
                         help='JSON file with benchmark data')
 
     return parser
 
 
-def get_benchmark_subset(benchmarks, pattern):
-    return [x for x in benchmarks if pattern.match(x['name'])]
+def filter_benchmarks(benchmarks, filter_pattern):
+    return [x for x in benchmarks if filter_pattern.match(x['name'])]
 
 
-def get_benchmarks(json):
+def filter_benchmark_categories(json):
     benchmarks = [x for x in json['benchmarks'] if x['name'].endswith('_mean')]
 
     if not benchmarks:
         benchmarks = json['benchmarks']
 
     return [
-        get_benchmark_subset(benchmarks, re.compile(r'.+/Build.+')),
-        get_benchmark_subset(benchmarks, re.compile(r'.+/(Knn|Nn).+')),
-        get_benchmark_subset(benchmarks, re.compile(r'.+/Radius.+'))
+        filter_benchmarks(benchmarks, re.compile(r'.+/Build.+')),
+        filter_benchmarks(benchmarks, re.compile(r'.+/(Knn|Nn).+')),
+        filter_benchmarks(benchmarks, re.compile(r'.+/Radius.+'))
     ]
 
 
-def get_plots(benchmarks_subset, pattern):
+def create_plots(benchmarks, pattern):
     plots = dict()
 
-    for x in benchmarks_subset:
+    for x in benchmarks:
         m = pattern.match(x['name'])
         k = m.group('tree') + '_' + \
             m.group('type') + (('_' + m.group('arg'))
                                if m.group('arg') else '')
         plots[k] = {'x': [], 'y': []}
 
-    for x in benchmarks_subset:
+    for x in benchmarks:
         m = pattern.match(x['name'])
         k = m.group('tree') + '_' + \
             m.group('type') + (('_' + m.group('arg'))
@@ -54,7 +53,7 @@ def get_plots(benchmarks_subset, pattern):
     return plots
 
 
-def get_figure(plots, title):
+def create_figure(plots, title):
     fig, ax = plt.subplots(figsize=(4, 4), tight_layout=True)
 
     for label in plots:
@@ -74,17 +73,19 @@ def main():
     parser = create_arguments()
     args = parser.parse_args()
 
-    benchmarks = get_benchmarks(json.load(args.json_file))
+    benchmarks = filter_benchmark_categories(json.load(args.json_file))
     re_info = r'^Bm(?P<tree>.+)/(Build|Knn|Nn|Radius)(?P<type>(Ct|Rt)[^/]*)/(?P<x>\d+)(/(?P<arg>\d+))?(_mean)?$'
-    plots = [get_plots(b, re.compile(re_info)) for b in benchmarks]
-
+    plots = [create_plots(b, re.compile(re_info)) for b in benchmarks]
+    titles = ['build time', 'knn search time', 'radius search time']
     # Format is determined by filename extension
     extension = '.png'
-    get_figure(plots[0], 'build time')[0].savefig(f'./build_time{extension}')
-    get_figure(plots[1], 'knn search time')[
-        0].savefig(f'./knn_search_time{extension}')
-    get_figure(plots[2], 'radius search time')[
-        0].savefig(f'./radius_search_time{extension}')
+    file_names = [
+        f'./build_time{extension}',
+        f'./knn_search_time{extension}',
+        f'./radius_search_time{extension}']
+
+    for i in range(len(plots)):
+        create_figure(plots[i], titles[i])[0].savefig(file_names[i])
     plt.show()
 
 

examples/kd_tree/kd_tree_dynamic_arrays.cpp

@@ -8,43 +8,46 @@
 // for working with an array of scalars or an array of points.
 
 void ArrayOfScalars() {
-  std::size_t count = 10;
+  std::size_t count = 6;
   constexpr std::size_t Dim = 2;
 
-  // Dummy array of scalars.
-  std::unique_ptr<double[]> data = std::make_unique<double[]>(count);
-  for (std::size_t i = 0; i < count; ++i) {
+  // Here we create an array of scalars that will be interpreted as a set of
+  // points: {{0, 1}, {2, 3}, ...}
+  std::unique_ptr<double[]> data = std::make_unique<double[]>(count * Dim);
+  for (std::size_t i = 0; i < (count * Dim); ++i) {
     data[i] = static_cast<double>(i);
   }
 
-  // If Dim equals pico_tree::kDynamicSize, SpaceMap needs a 3rd argument: The
-  // spatial dimension known at run time.
-  pico_tree::SpaceMap<pico_tree::PointMap<double, Dim>> map(
-      data.get(), count / Dim);
+  // If Dim equals pico_tree::kDynamicSize, then SpaceMap will need a 3rd
+  // 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);
 
-  // If Dim equals pico_tree::kDynamicSize, PointMap needs a 2nd argument: The
-  // spatial dimension known at run time.
-  pico_tree::PointMap<double, Dim> query(data.get() + 4);
+  // If Dim equals pico_tree::kDynamicSize, then PointMap will need a 2nd
+  // argument: The spatial dimension known at run time.
+  std::size_t index = 2;
+  pico_tree::PointMap<double, Dim> query(data.get() + index * Dim);
   pico_tree::Neighbor<int, double> nn;
   tree.SearchNn(query, nn);
+
   // Prints index 2.
   std::cout << "Index closest point: " << nn.index << std::endl;
 }
 
 void ArrayOfPoints() {
-  std::size_t count = 3;
+  std::size_t count = 6;
   constexpr std::size_t Dim = 2;
 
-  // Dummy array of points.
+  // Here we create an array of points: {{0, 1}, {2, 3}, ...}
   std::unique_ptr<std::array<double, Dim>[]> data =
       std::make_unique<std::array<double, Dim>[]>(count);
   for (std::size_t i = 0; i < count; ++i) {
-    data[i] = {
-        static_cast<double>(i * Dim + 0), static_cast<double>(i * Dim + 1)};
+    for (std::size_t j = 0; j < Dim; ++j) {
+      data[i][j] = static_cast<double>(i * Dim + j);
+    }
   }
 
   pico_tree::SpaceMap<std::array<double, Dim>> map(data.get(), count);
@@ -53,7 +56,8 @@ void ArrayOfPoints() {
   pico_tree::KdTree<pico_tree::SpaceMap<std::array<double, Dim>>> tree(
       map, max_leaf_size);
 
-  std::array<double, Dim> const& query = data[1];
+  std::size_t index = 1;
+  std::array<double, Dim> const& query = data[index];
   pico_tree::Neighbor<int, double> nn;
   tree.SearchNn(query, nn);
 

examples/opencv/opencv.cpp

@@ -11,26 +11,27 @@ Index const kNumPoints = 1024 * 1024 * 2;
 Scalar const kArea = 1000.0;
 std::size_t const kRunCount = 1024 * 1024;
 
-template <typename Scalar_>
-std::vector<cv::Point3_<Scalar_>> GenerateRandomPoint3N(int n, Scalar_ size) {
+template <typename Vec_>
+std::vector<Vec_> GenerateRandomVecN(
+    std::size_t n, typename Vec_::value_type size) {
   std::random_device rd;
   std::mt19937 e2(rd());
-  std::uniform_real_distribution<Scalar_> dist(0, size);
+  std::uniform_real_distribution<typename Vec_::value_type> dist(0, size);
 
-  std::vector<cv::Point3_<Scalar_>> random(n);
+  std::vector<Vec_> random(n);
   for (auto& p : random) {
-    p.x = dist(e2);
-    p.y = dist(e2);
-    p.z = dist(e2);
+    for (auto& c : p.val) {
+      c = dist(e2);
+    }
   }
 
   return random;
 }
 
 // This example shows to build a KdTree from a vector of cv::Point3.
 void BasicVector() {
-  using PointX = cv::Point3_<Scalar>;
-  std::vector<PointX> random = GenerateRandomPoint3N(kNumPoints, kArea);
+  using PointX = cv::Vec<Scalar, 3>;
+  std::vector<PointX> random = GenerateRandomVecN<PointX>(kNumPoints, kArea);
 
   pico_tree::KdTree<std::reference_wrapper<std::vector<PointX>>> tree(
       random, 10);
@@ -63,8 +64,8 @@ void BasicMatrix() {
 
   // Single column cv::Mat based on a vector of points.
   {
-    using PointX = cv::Point3_<Scalar>;
-    std::vector<PointX> random = GenerateRandomPoint3N(kNumPoints, kArea);
+    using PointX = cv::Vec<Scalar, 3>;
+    std::vector<PointX> random = GenerateRandomVecN<PointX>(kNumPoints, kArea);
 
     pico_tree::KdTree<pico_tree::MatWrapper<Scalar, 3>> tree(
         cv::Mat(random), 10);

examples/python/kd_tree.py

@@ -11,11 +11,12 @@
 
 def tree_creation_and_query_types():
     print("*** KdTree Creation And Basic Information ***")
-    # An input array must have a dimension of two and it must be contiguous. A
-    # C contiguous array contains points in its rows and an F contiguous array
-    # contains points in its columns.
+    # An input array must have a dimension of two and it must be
+    # contiguous. A C contiguous array contains points in its rows and
+    # an F contiguous array contains points in its columns.
     p = np.array([[2, 1], [4, 3], [8, 7]], dtype=np.float32)
-    # Both the in and output distances are squared when using Metric.L2Squared.
+    # Both the in and output distances are squared when using
+    # Metric.L2Squared.
     t = pt.KdTree(p, pt.Metric.L2Squared, 1)
     print(f"{t}")
     print(f"Number of points used to build the tree: {t.npts}")
@@ -37,9 +38,10 @@ def tree_creation_and_query_types():
     print()
 
     print("*** Approximate Nearest Neighbor Search ***")
-    # Searching for approximate nearest neighbors works the same way.
-    # An approximate nearest neighbor can be at most a distance factor of 1+e
-    # farther away from the true nearest neighbor.
+    # Approximate nearest neighbor searches require an extra parameter
+    # compared to exact nearest neighbor searches, namely, a distance
+    # factor. An approximate nearest neighbor can be at most a factor
+    # of 1+e farther away from the true nearest neighbor.
     max_error = 0.75
     # Apply the metric function to the ratio to get the squared ratio.
     max_error_ratio = t.metric(1.0 + max_error)
@@ -48,14 +50,14 @@ def tree_creation_and_query_types():
     # Note that we scale back the ann distance its original distance.
     print("The 2nd closest to each input point:")
     for knn in knns:
-        print(
-            f"Point index {knn[1][0]} with distance {knn[1][1] * max_error_ratio}")
+        print("Point index {0} with distance {1}".format(
+            knn[1][0], knn[1][1] * max_error_ratio))
     print()
 
     print("*** Radius Search ***")
-    # A radius search doesn't return a numpy array but a custom vector of numpy
-    # arrays. This is because the number of neighbors to each of input points
-    # may vary for a radius search.
+    # A radius search doesn't return a numpy array but a custom vector
+    # of numpy arrays. This is because the number of neighbors to each
+    # of input points may vary for a radius search.
     search_radius = t.metric(2.5)
     print(f"Result with radius: {search_radius}")
     rnns = t.search_radius(p, search_radius)
@@ -69,8 +71,9 @@ def tree_creation_and_query_types():
     print()
 
     print("*** Box Search ***")
-    # A box search returns the same data structure as a radius search. However,
-    # instead of containing neighbors it simply contains indices.
+    # A box search returns the same data structure as a radius search.
+    # However, instead of containing neighbors it simply contains
+    # indices.
     min = np.array([[0, 0], [2, 2], [0, 0], [6, 6]], dtype=np.float32)
     max = np.array([[3, 3], [3, 3], [9, 9], [9, 9]], dtype=np.float32)
     bnns = t.search_box(min, max)
@@ -96,11 +99,14 @@ def tree_creation_and_query_types():
 def array_initialization():
     print("*** Array Initialization ***")
     p = np.array([[2, 1], [4, 3], [8, 7]], dtype=np.float64)
-    # In and output distances are absolute distances when using Metric.L1.
+    # Metric.L1: The sum of absolute differences.
     t = pt.KdTree(p, pt.Metric.L1, 10)
+    # Metric.LInf: The max of absolute differences.
+    t = pt.KdTree(p, pt.Metric.LInf, 10)
 
-    # This type of forward initialization of arrays may be useful to streamline
-    # loops that depend on them and where reusing memory is desired. E.g.: ICP.
+    # This type of forward initialization of arrays may be useful to
+    # streamline loops that depend on them and where reusing memory is
+    # desired. E.g.: ICP.
     knns = np.empty((0), dtype=t.dtype_neighbor)
     print(knns.dtype)
     rnns = pt.DArray(dtype=t.dtype_neighbor)
@@ -112,9 +118,9 @@ def array_initialization():
 
 def performance_test_pico_tree():
     print("*** Performance against scans.bin ***")
-    # The benchmark documentation, docs/benchmark.md section "Running a new
-    # benchmark", explains how to generate a scans.bin file from an online
-    # dataset.
+    # The benchmark documentation, docs/benchmark.md section "Running a
+    # new benchmark", explains how to generate a scans.bin file from an
+    # online dataset.
     try:
         p0 = np.fromfile(Path(__file__).parent / "scans0.bin",
                          np.float32).reshape((-1, 3))
@@ -125,34 +131,36 @@ def performance_test_pico_tree():
         return
 
     cnt_build_time_before = perf_counter()
-    # Tree creation is only slightly slower in Python vs C++ using the bindings.
+    # Tree creation is only slightly slower in Python.
     t = pt.KdTree(p0, pt.Metric.L2Squared, 10)
-    #t = spKDTree(p0, leafsize=10)
-    #t = skKDTree(p0, leaf_size=10)
-    #t = pyKDTree(p0, leafsize=10)
+    # t = spKDTree(p0, leafsize=10)
+    # t = skKDTree(p0, leaf_size=10)
+    # t = pyKDTree(p0, leafsize=10)
     cnt_build_time_after = perf_counter()
-    print(f"{t} was built in {(cnt_build_time_after - cnt_build_time_before) * 1000.0}ms")
-    # Use the OMP_NUM_THREADS environment variable to influence the number of
-    # threads used for querying: export OMP_NUM_THREADS=1
+    print("{0} was built in {1}ms".format(
+        t, (cnt_build_time_after - cnt_build_time_before) * 1000.0))
+    # Use the OMP_NUM_THREADS environment variable to influence the
+    # number of threads used for querying: export OMP_NUM_THREADS=1
     k = 1
     cnt_query_time_before = perf_counter()
-    # Searching for nearest neighbors is a constant amount of time slower
-    # using the bindings as compared to the C++ benchmark (regardless of k).
-    # The following must be noted however: The Python benchmark simply calls
-    # the knn function provided by the Python bindings. As such it does not
-    # directly wrap the C++ benchmark. This means the performance difference is
-    # not only due to the bindings overhead. The C++ implementation benchmark
-    # may have been optimized more because is very simple. The bindings also
-    # have various extra overhead: checks, numpy array memory creation, OpenMP,
-    # etc.
-    # TODO The actual overhead is probably very similar to that of the KdTree
-    # creation, but it would be nice to measure the overhead w.r.t. the actual
-    # query.
+    # Searching for nearest neighbors is a constant amount of time
+    # slower using the bindings as compared to the C++ benchmark
+    # (regardless of k). The following must be noted however: The
+    # Python benchmark simply calls the knn function provided by the
+    # Python bindings. As such it does not directly wrap the C++
+    # benchmark. This means the performance difference is not only due
+    # to the bindings overhead. The C++ implementation benchmark may
+    # have been optimized more because is very simple. The bindings
+    # also have various extra overhead: checks, numpy array memory
+    # creation, OpenMP, etc.
+    # TODO The actual overhead is probably very similar to that of the
+    # KdTree creation, but it would be nice to measure the overhead
+    # w.r.t. the actual query.
     unused_knns = t.search_knn(p1, k)
-    #unused_dd, unused_ii = t.query(p1, k=k)
+    # unused_dd, unused_ii = t.query(p1, k=k)
     cnt_query_time_after = perf_counter()
-    print(
-        f"{len(p1)} points queried in {(cnt_query_time_after - cnt_query_time_before) * 1000.0}ms")
+    print("{0} points queried in {1}ms".format(
+        len(p1), (cnt_query_time_after - cnt_query_time_before) * 1000.0))
     print()
 
 

src/pyco_tree/pico_tree/__init__.py

@@ -1,5 +1,5 @@
-__all__ = []
+__all__ = ['DArray', 'KdTree', 'Metric']
 
-from .metric import *
-from .kd_tree import *
+from .kd_tree import KdTree
+from .metric import Metric
 from ._pyco_tree import __doc__, DArray

src/pyco_tree/pico_tree/_pyco_tree/_pyco_tree.cpp

@@ -9,13 +9,15 @@
 
 PYBIND11_MODULE(_pyco_tree, m) {
   m.doc() =
-      "PicoTree is a module for nearest neighbor searches and range searches "
-      "using a KdTree. It wraps the C++ PicoTree library.";
+      R"ptdoc(
+PicoTree: a module for fast nearest neighbor and range searches using a
+KdTree. It wraps the C++ PicoTree library.
+)ptdoc";
 
   // Registered dtypes.
   PYBIND11_NUMPY_DTYPE(pyco_tree::Neighborf, index, distance);
   PYBIND11_NUMPY_DTYPE(pyco_tree::Neighbord, index, distance);
 
-  pyco_tree::DefDArray(&m);
-  pyco_tree::DefKdTree(&m);
+  pyco_tree::DefDArray(m);
+  pyco_tree::DefKdTree(m);
 }