feat: dynamic rather than static parameters

rstar-benches/benches/benchmarks.rs

@@ -8,30 +8,22 @@ extern crate rstar;
 use rand::{Rng, SeedableRng};
 use rand_hc::Hc128Rng;
 
-use rstar::{RStarInsertionStrategy, RTree, RTreeParams};
+use rstar::{Params, RTree};
 
 use criterion::Criterion;
 
 const SEED_1: &[u8; 32] = b"Gv0aHMtHkBGsUXNspGU9fLRuCWkZWHZx";
 const SEED_2: &[u8; 32] = b"km7DO4GeaFZfTcDXVpnO7ZJlgUY7hZiS";
 
-struct Params;
-
-impl RTreeParams for Params {
-    const MIN_SIZE: usize = 2;
-    const MAX_SIZE: usize = 40;
-    const REINSERTION_COUNT: usize = 1;
-    type DefaultInsertionStrategy = RStarInsertionStrategy;
-}
-
 const DEFAULT_BENCHMARK_TREE_SIZE: usize = 2000;
 
 fn bulk_load_baseline(c: &mut Criterion) {
+    let params = Params::new(2, 40, 1);
     c.bench_function("Bulk load baseline", move |b| {
         let points: Vec<_> = create_random_points(DEFAULT_BENCHMARK_TREE_SIZE, SEED_1);
 
         b.iter(|| {
-            RTree::<_, Params>::bulk_load_with_params(points.clone());
+            RTree::<_>::bulk_load_with_params(params, points.clone());
         });
     });
 }
@@ -54,7 +46,8 @@ fn bulk_load_comparison(c: &mut Criterion) {
 fn tree_creation_quality(c: &mut Criterion) {
     const SIZE: usize = 100_000;
     let points: Vec<_> = create_random_points(SIZE, SEED_1);
-    let tree_bulk_loaded = RTree::<_, Params>::bulk_load_with_params(points.clone());
+    let params = Params::new(2, 40, 1);
+    let tree_bulk_loaded = RTree::<_>::bulk_load_with_params(params.clone(), points.clone());
     let mut tree_sequential = RTree::new();
     for point in &points {
         tree_sequential.insert(*point);
@@ -81,15 +74,17 @@ fn tree_creation_quality(c: &mut Criterion) {
 fn locate_successful(c: &mut Criterion) {
     let points: Vec<_> = create_random_points(100_000, SEED_1);
     let query_point = points[500];
-    let tree = RTree::<_, Params>::bulk_load_with_params(points);
+    let params = Params::new(2, 40, 1);
+    let tree = RTree::<_>::bulk_load_with_params(params, points);
     c.bench_function("locate_at_point (successful)", move |b| {
         b.iter(|| tree.locate_at_point(&query_point).is_some())
     });
 }
 
 fn locate_unsuccessful(c: &mut Criterion) {
     let points: Vec<_> = create_random_points(100_000, SEED_1);
-    let tree = RTree::<_, Params>::bulk_load_with_params(points);
+    let params = Params::new(2, 40, 1);
+    let tree = RTree::<_>::bulk_load_with_params(params, points);
     let query_point = [0.7, 0.7];
     c.bench_function("locate_at_point (unsuccessful)", move |b| {
         b.iter(|| tree.locate_at_point(&query_point).is_none())

rstar-demo/src/main.rs

@@ -7,7 +7,7 @@ use kiss3d::window::Window;
 use nalgebra::{Point2, Point3, Vector2};
 use rand::distributions::Uniform;
 use rand::Rng;
-use rstar::{Point, RStarInsertionStrategy, RTree, RTreeNode, RTreeParams, AABB};
+use rstar::{Params, Point, RTree, RTreeNode, AABB};
 
 mod three_d;
 mod two_d;
@@ -67,14 +67,14 @@ impl Scene {
 
     fn reset_to_empty(&mut self) {
         match self.render_mode {
-            RenderMode::TwoD => self.tree_2d = Default::default(),
-            RenderMode::ThreeD => self.tree_3d = Default::default(),
+            RenderMode::TwoD => self.tree_2d = DemoTree2D::new_with_params(params()),
+            RenderMode::ThreeD => self.tree_3d = DemoTree3D::new_with_params(params()),
         }
     }
 
     fn bulk_load_tree_3d() -> DemoTree3D {
         let points_3d = create_random_points(500);
-        DemoTree3D::bulk_load_with_params(points_3d)
+        DemoTree3D::bulk_load_with_params(params(), points_3d)
     }
 
     fn bulk_load_tree_2d(window_width: u32, window_height: u32) -> DemoTree2D {
@@ -83,24 +83,20 @@ impl Scene {
             *x = *x * window_width as f32 * 0.5;
             *y = *y * window_height as f32 * 0.5;
         }
-        DemoTree2D::bulk_load_with_params(points_2d)
+        DemoTree2D::bulk_load_with_params(params(), points_2d)
     }
 }
 
-type DemoTree3D = RTree<TreePointType3D, Params>;
+fn params() -> Params {
+    Params::new(5, 9, 3)
+}
+
+type DemoTree3D = RTree<TreePointType3D>;
 type TreePointType3D = [f32; 3];
 
 type DemoTree2D = RTree<TreePointType2D>;
 type TreePointType2D = [f32; 2];
 
-pub struct Params;
-impl RTreeParams for Params {
-    const MIN_SIZE: usize = 5;
-    const MAX_SIZE: usize = 9;
-    const REINSERTION_COUNT: usize = 3;
-    type DefaultInsertionStrategy = RStarInsertionStrategy;
-}
-
 pub enum RenderData {
     ThreeD(
         Vec<three_d::LineRenderData3D>,

rstar/src/algorithm/bulk_load/bulk_load_sequential.rs

@@ -1,7 +1,7 @@
 use crate::envelope::Envelope;
 use crate::node::{ParentNode, RTreeNode};
 use crate::object::RTreeObject;
-use crate::params::RTreeParams;
+use crate::params::Params;
 use crate::point::Point;
 
 use alloc::{vec, vec::Vec};
@@ -11,29 +11,28 @@ use num_traits::Float;
 
 use super::cluster_group_iterator::{calculate_number_of_clusters_on_axis, ClusterGroupIterator};
 
-fn bulk_load_recursive<T, Params>(elements: Vec<T>, depth: usize) -> ParentNode<T>
+fn bulk_load_recursive<T>(params: Params, elements: Vec<T>, depth: usize) -> ParentNode<T>
 where
     T: RTreeObject,
     <T::Envelope as Envelope>::Point: Point,
-    Params: RTreeParams,
 {
-    let m = Params::MAX_SIZE;
+    let m = params.max_size();
     if elements.len() <= m {
         // Reached leaf level
         let elements: Vec<_> = elements.into_iter().map(RTreeNode::Leaf).collect();
         return ParentNode::new_parent(elements);
     }
     let number_of_clusters_on_axis =
-        calculate_number_of_clusters_on_axis::<T, Params>(elements.len());
+        calculate_number_of_clusters_on_axis::<T>(params, elements.len());
 
-    let iterator = PartitioningTask::<_, Params> {
+    let iterator = PartitioningTask::<_> {
         number_of_clusters_on_axis,
         depth,
         work_queue: vec![PartitioningState {
             current_axis: <T::Envelope as Envelope>::Point::DIMENSIONS,
             elements,
         }],
-        _params: Default::default(),
+        params: params.clone(),
     };
     ParentNode::new_parent(iterator.collect())
 }
@@ -48,14 +47,14 @@ struct PartitioningState<T: RTreeObject> {
 }
 
 /// Successively partitions the given elements into  cluster groups and finally into clusters.
-struct PartitioningTask<T: RTreeObject, Params: RTreeParams> {
+struct PartitioningTask<T: RTreeObject> {
     work_queue: Vec<PartitioningState<T>>,
     depth: usize,
     number_of_clusters_on_axis: usize,
-    _params: core::marker::PhantomData<Params>,
+    params: Params,
 }
 
-impl<T: RTreeObject, Params: RTreeParams> Iterator for PartitioningTask<T, Params> {
+impl<T: RTreeObject> Iterator for PartitioningTask<T> {
     type Item = RTreeNode<T>;
 
     fn next(&mut self) -> Option<Self::Item> {
@@ -66,7 +65,7 @@ impl<T: RTreeObject, Params: RTreeParams> Iterator for PartitioningTask<T, Param
             } = next;
             if current_axis == 0 {
                 // Partitioning finished successfully on all axis. The remaining cluster forms a new node
-                let data = bulk_load_recursive::<_, Params>(elements, self.depth - 1);
+                let data = bulk_load_recursive::<_>(self.params, elements, self.depth - 1);
                 return RTreeNode::Parent(data).into();
             } else {
                 // The cluster group needs to be partitioned further along the next axis
@@ -89,15 +88,14 @@ impl<T: RTreeObject, Params: RTreeParams> Iterator for PartitioningTask<T, Param
 /// A multi dimensional implementation of the OMT bulk loading algorithm.
 ///
 /// See http://ceur-ws.org/Vol-74/files/FORUM_18.pdf
-pub fn bulk_load_sequential<T, Params>(elements: Vec<T>) -> ParentNode<T>
+pub fn bulk_load_sequential<T>(params: Params, elements: Vec<T>) -> ParentNode<T>
 where
     T: RTreeObject,
     <T::Envelope as Envelope>::Point: Point,
-    Params: RTreeParams,
 {
-    let m = Params::MAX_SIZE;
+    let m = params.max_size();
     let depth = (elements.len() as f32).log(m as f32).ceil() as usize;
-    bulk_load_recursive::<_, Params>(elements, depth)
+    bulk_load_recursive::<_>(params, elements, depth)
 }
 
 #[cfg(test)]

rstar/src/algorithm/bulk_load/cluster_group_iterator.rs

@@ -1,4 +1,4 @@
-use crate::{Envelope, Point, RTreeObject, RTreeParams};
+use crate::{Envelope, Params, Point, RTreeObject};
 
 use alloc::vec::Vec;
 
@@ -47,12 +47,11 @@ impl<T: RTreeObject> Iterator for ClusterGroupIterator<T> {
 /// Calculates the desired number of clusters on any axis
 ///
 /// A 'cluster' refers to a set of elements that will finally form an rtree node.
-pub fn calculate_number_of_clusters_on_axis<T, Params>(number_of_elements: usize) -> usize
+pub fn calculate_number_of_clusters_on_axis<T>(params: Params, number_of_elements: usize) -> usize
 where
     T: RTreeObject,
-    Params: RTreeParams,
 {
-    let max_size = Params::MAX_SIZE as f32;
+    let max_size = params.max_size() as f32;
     // The depth of the resulting tree, assuming all leaf nodes will be filled up to MAX_SIZE
     let depth = (number_of_elements as f32).log(max_size).ceil() as usize;
     // The number of elements each subtree will hold

rstar/src/algorithm/removal.rs

@@ -3,7 +3,6 @@ use core::mem::replace;
 use crate::algorithm::selection_functions::SelectionFunction;
 use crate::node::{ParentNode, RTreeNode};
 use crate::object::RTreeObject;
-use crate::params::RTreeParams;
 use crate::{Envelope, RTree};
 
 use alloc::{vec, vec::Vec};
@@ -24,25 +23,23 @@ use num_traits::Float;
 /// the yielded values (this behaviour is unlike `Vec::drain_*`). Leaking
 /// this iterator leads to a leak amplification where all elements of the
 /// tree are leaked.
-pub struct DrainIterator<'a, T, R, Params>
+pub struct DrainIterator<'a, T, R>
 where
     T: RTreeObject,
-    Params: RTreeParams,
     R: SelectionFunction<T>,
 {
     node_stack: Vec<(ParentNode<T>, usize, usize)>,
     removal_function: R,
-    rtree: &'a mut RTree<T, Params>,
+    rtree: &'a mut RTree<T>,
     original_size: usize,
 }
 
-impl<'a, T, R, Params> DrainIterator<'a, T, R, Params>
+impl<'a, T, R> DrainIterator<'a, T, R>
 where
     T: RTreeObject,
-    Params: RTreeParams,
     R: SelectionFunction<T>,
 {
-    pub(crate) fn new(rtree: &'a mut RTree<T, Params>, removal_function: R) -> Self {
+    pub(crate) fn new(rtree: &'a mut RTree<T>, removal_function: R) -> Self {
         // We replace with a root as a brand new RTree in case the iterator is
         // `mem::forgot`ten.
 
@@ -57,7 +54,7 @@ where
         );
         let original_size = replace(rtree.size_mut(), 0);
 
-        let m = Params::MIN_SIZE;
+        let m = rtree.params.min_size();
         let max_depth = (original_size as f32).log(m.max(2) as f32).ceil() as usize;
         let mut node_stack = Vec::with_capacity(max_depth);
         node_stack.push((root, 0, 0));
@@ -120,10 +117,9 @@ where
     }
 }
 
-impl<'a, T, R, Params> Iterator for DrainIterator<'a, T, R, Params>
+impl<'a, T, R> Iterator for DrainIterator<'a, T, R>
 where
     T: RTreeObject,
-    Params: RTreeParams,
     R: SelectionFunction<T>,
 {
     type Item = T;
@@ -180,10 +176,9 @@ where
     }
 }
 
-impl<'a, T, R, Params> Drop for DrainIterator<'a, T, R, Params>
+impl<'a, T, R> Drop for DrainIterator<'a, T, R>
 where
     T: RTreeObject,
-    Params: RTreeParams,
     R: SelectionFunction<T>,
 {
     fn drop(&mut self) {