updates to deps, improved readme, clippy comments

Author: Alex Pyattaev

Cargo.toml

@@ -1,35 +1,33 @@
 [package]
 name = "spatialtree"
 description = "A fast and flexible generic spatial tree collection (Octree, Quadtree, etc)"
-version = "0.1.1"
+version = "0.1.2"
 edition = "2021"
 license = "GPL-3.0"
 repository = "https://github.com/alexpyattaev/spatialtree"
 documentation = "https://docs.rs/spatialtree"
-keywords = ["octree", "quadtree", "tree","lod", "generic"]
+keywords = ["octree", "quadtree", "tree", "lod", "generic"]
 categories = ["data-structures"]
-exclude = [
-    ".github/",
-]
+exclude = [".github/"]
 
 
 [dependencies]
-arrayvec = "0.7.2"
-duplicate = "1.0.0"
-slab = "0.4.8"
-rand ={version="0.8.5", features=['small_rng'], optional = true }
+arrayvec = "0.7"
+duplicate = "1.0"
+slab = "0.4"
+rand = { version = "0.8", features = ['small_rng'], optional = true }
 
 [features]
 default = ["rand"]
-rand=["dep:rand"]
+rand = ["dep:rand"]
 
 [dev-dependencies]
-freelist = "0.1.0"
+freelist = "0.1"
 lru = "0.10.0"
 rayon = "1.5"
 glium = "0.30"
 rand_derive = "0.5.0"
-criterion = {version= "0.4.0", features=['html_reports']}
+criterion = { version = "0.4.0", features = ['html_reports'] }
 
 [[bench]]
 name = "iterators"
@@ -44,16 +42,15 @@ name = "coordinates"
 harness = false
 
 [profile.release]
-opt-level=3
+opt-level = 3
 overflow-checks = false
-debug=0
+debug = 0
 strip = "symbols"
-debug-assertions=false
-lto="fat"
+debug-assertions = false
+lto = "fat"
 
 
 [profile.bench]
-debug=0
-lto="fat"
+debug = 0
+lto = "fat"
 strip = "symbols"
-

README.md

@@ -14,7 +14,7 @@ Internals are partially based on:
 The aim of this crate is to provide a generic, easy to use tree data structure that can be used to make Quadtrees, Octrees for various realtime applications (e.g. games or GIS software).
 
 Internally, the tree tries to keep all needed memory allocated in slab arenas to avoid the memory fragmentation and allocator pressure. All operations, where possible, use either stack allocations or allocate at most once.
- 
+
 
 ## Features
  - Highly tunable for different scales (from 8 bit to 64 bit coordinates), 2D, 3D, N-D if desired.
@@ -97,6 +97,24 @@ let idx = tree.insert(QuadVec::new([1u8,2], 3), |p| {p.pos.iter().sum::<u8>() as
 assert_eq!(tree.get_chunk(idx).chunk, 3);
 ```
 
+Lookups in the tree can be efficiently done over a wide area using an axis-aligned bounding box (AABB) to select the desired region as follows:
+```rust
+# use spatialtree::*;
+let mut tree = OctTree::<usize, OctVec>::new();
+let min = OctVec::new([0u8, 0, 0], 3);
+let max = OctVec::new([7u8, 7, 7], 3);
+
+// create iterator over all possible positions in the tree
+let pos_iter = iter_all_positions_in_bounds(min, max);
+// fill tree with important data
+tree.insert_many(pos_iter, |_| 42 );
+// iterateing over data in AABB yields both positions and associated data chunks
+// only populated positions are yielded, empty ones are quietly skipped.
+for (pos, data) in tree.iter_chunks_in_aabb(min, max) {
+    dbg!(pos, data);
+}
+```
+Selecting chunks this way will never traverse deeper than the deepest chunk in the AABB limits provided. Both limits should have the same depth.
 
 ## Advanced usage
 This structure can be used for purposes such as progressive LOD.

benches/coordinates.rs

@@ -26,8 +26,7 @@ fn run_eval<const N: usize, FL: LodVec<N>>(c: &mut Criterion, title: &str) {
     let mut rng = SmallRng::seed_from_u64(42);
     let samples_num = 10;
 
-    //for depth in [1, 4, 16].iter() {
-    for depth in [1].iter() {
+    for depth in [1, 4].iter() {
         group.significance_level(0.1).sample_size(samples_num);
         //TODO: more sensible stuff here
         group.bench_with_input(BenchmarkId::from_parameter(depth), depth, |b, &_depth| {

benches/freelist.rs

@@ -1,19 +1,19 @@
 /* Generic tree structures for storage of spatial data.
- Copyright (C) 2023  Alexander Pyattaev
+Copyright (C) 2023  Alexander Pyattaev
 
- This program is free software: you can redistribute it and/or modify
- it under the terms of the GNU General Public License as published by
- the Free Software Foundation, either version 3 of the License, or
- (at your option) any later version.
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
 
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- GNU General Public License for more details.
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
 
- You should have received a copy of the GNU General Public License
- along with this program.  If not, see <https://www.gnu.org/licenses/>.
- */
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
 
 use criterion::{black_box, criterion_group, criterion_main, BenchmarkId, Criterion};
 use freelist as libfreelist;
@@ -83,7 +83,7 @@ where
     let mut rng = SmallRng::seed_from_u64(42);
     let samples_num = 10;
 
-    for depth in [50 /* 1000, 100000*/].iter() {
+    for depth in [25, 50].iter() {
         group.significance_level(0.1).sample_size(samples_num);
         group.bench_with_input(BenchmarkId::from_parameter(depth), depth, |b, &depth| {
             b.iter(|| {

benches/iterators.rs

@@ -24,10 +24,10 @@ use spatialtree::*;
 
 const N_LOOKUPS: usize = 40;
 
-type DTYPE = u8;
+type DataType = u8;
 
-fn generate_area_bounds(rng: &mut SmallRng, depth: u8) -> (OctVec<DTYPE>, OctVec<DTYPE>) {
-    let cmax = ((1usize << depth as usize) - 1) as DTYPE;
+fn generate_area_bounds(rng: &mut SmallRng, depth: u8) -> (OctVec<DataType>, OctVec<DataType>) {
+    let cmax = ((1usize << depth as usize) - 1) as DataType;
 
     let min = rand_cv(
         rng,
@@ -40,7 +40,7 @@ fn generate_area_bounds(rng: &mut SmallRng, depth: u8) -> (OctVec<DTYPE>, OctVec
         OctVec::new([cmax, cmax, cmax], depth),
     );
 
-    return (min, max);
+    (min, max)
 }
 
 struct ChuChunk {

examples/glium.rs

@@ -35,7 +35,7 @@ struct Chunk {
 }
 
 fn make_shaders(display: &Display) -> Program {
-    let program = program!(display,
+    program!(display,
     140 => {
         vertex: "
 			#version 140
@@ -76,8 +76,7 @@ fn make_shaders(display: &Display) -> Program {
 		"
     }
     )
-    .unwrap();
-    return program;
+    .unwrap()
 }
 
 #[derive(Copy, Clone)]
@@ -98,7 +97,7 @@ impl RenderContext {
     pub fn new(event_loop: &EventLoop<()>) -> Self {
         let wb = glutin::window::WindowBuilder::new().with_title("Quadtree demo");
         let cb = glutin::ContextBuilder::new().with_vsync(true);
-        let display = Display::new(wb, cb, &event_loop).unwrap();
+        let display = Display::new(wb, cb, event_loop).unwrap();
         // make a vertex buffer
         // we'll reuse it as we only need to draw one quad multiple times anyway
         let vertex_buffer = {
@@ -125,7 +124,7 @@ impl RenderContext {
         let index_buffer = IndexBuffer::new(
             &display,
             PrimitiveType::TrianglesList,
-            &[0 as u16, 1, 2, 1, 2, 3],
+            &[0_u16, 1, 2, 1, 2, 3],
         )
         .unwrap();
 
@@ -173,7 +172,7 @@ fn draw(mouse_pos: (f32, f32), tree: &mut QuadTree<Chunk, QuadVec>, ctx: &Render
             // here we get the chunk position and size
             let uniforms = uniform! {
                 offset: position.float_coords(),
-                scale: position.float_size() as f32,
+                scale: position.float_size(),
                 state: chunk.cache_state,
                 selected: chunk.selected as i32,
             };

src/iter.rs

@@ -568,7 +568,7 @@ mod tests {
             );
 
             for (l, c) in tree.iter_chunks_in_aabb_mut(min, max) {
-                assert_eq!(c.visible, false, "no way any voxel is still visible");
+                assert!(!c.visible, "no way any voxel is still visible");
                 assert_eq!(
                     l.pos.depth, D,
                     "All chunks must be at max depth (as we did not insert any others)"

src/tree.rs

@@ -18,13 +18,11 @@
 //! Contains the tree struct, which is used to hold all chunks
 
 use crate::coords::*;
+use crate::util_funcs::*;
 use slab::Slab;
 use std::fmt::Debug;
 use std::num::NonZeroU32;
 use std::ops::ControlFlow;
-use crate::util_funcs::*;
-
-
 
 // type aliases to make iterators more readable
 pub(crate) type ChunkStorage<const N: usize, C, L> = Slab<ChunkContainer<N, C, L>>;
@@ -37,6 +35,7 @@ pub(crate) type NodeStorage<const B: usize> = Slab<TreeNode<B>>;
 /// Template parameters are:
 /// * N is the number bits needed to encode B, i.e. 3 for octrees and 4 for quadtrees.
 /// * B is the branch count per node, i.e. 8 for octrees and 4 for quadtrees. Has to be power of two.
+///
 /// An invariant between the two has to be ensured where 1<<N == B, else tree will fail to construct.
 /// This will look nicer once const generics fully stabilize.
 #[derive(Clone, Debug)]
@@ -451,7 +450,7 @@ where
             for (i, old_idx) in iter_treenode_children(&children) {
                 let old_node = self.nodes.remove(old_idx);
                 //eliminate empty nodes
-                if old_node.is_empty(){
+                if old_node.is_empty() {
                     self.new_nodes[n].children[i] = None;
                     continue;
                 }
@@ -751,7 +750,6 @@ mod tests {
         }
     }
 
-
     #[test]
     pub fn defragment() {
         let mut tree = QuadTree::<TestChunk, QuadVec>::new();
@@ -763,21 +761,20 @@ mod tests {
         ];
         tree.insert_many(targets.iter().copied(), |_| TestChunk {});
         // slab is a Vec, so it should have binary exponential growth. With 4 entires it should have capacity = len.
-        assert_eq!(tree.chunks.capacity(),tree.chunks.len());
+        assert_eq!(tree.chunks.capacity(), tree.chunks.len());
         tree.pop_chunk_by_position(targets[1]);
-        assert_eq!(tree.chunks.capacity(),4);
-        assert_eq!(tree.chunks.len(),3);
+        assert_eq!(tree.chunks.capacity(), 4);
+        assert_eq!(tree.chunks.len(), 3);
         tree.defragment_chunks();
         tree.shrink_to_fit();
-        assert_eq!(tree.chunks.capacity(),tree.chunks.len());
+        assert_eq!(tree.chunks.capacity(), tree.chunks.len());
         dbg!(tree.nodes.len());
         tree.pop_chunk_by_position(targets[0]);
         //TODO!
         //tree.prune();
         dbg!(tree.nodes.len());
     }
 
-
     #[test]
     pub fn alignment() {
         assert_eq!(

src/util_funcs.rs

@@ -15,8 +15,8 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-use std::num::NonZeroU32;
 use crate::coords::*;
+use std::num::NonZeroU32;
 
 /// Utility function to cast random structures into arrays of bytes
 /// This is mostly for debugging purposes
@@ -26,8 +26,6 @@ pub unsafe fn any_as_u8_slice<T: Sized>(p: &T) -> &[u8] {
     ::core::slice::from_raw_parts((p as *const T) as *const u8, ::core::mem::size_of::<T>())
 }
 
-
-
 /// Type for relative pointers to nodes in the tree. Kept 32bit for cache locality during lookups.
 /// Should you need > 4 billion nodes in the tree do let me know who sells you the RAM.
 pub type NodePtr = Option<NonZeroU32>;
@@ -67,13 +65,13 @@ impl ChunkPtr {
     #[inline]
     pub(crate) fn from(x: Option<usize>) -> Self {
         match x {
-            Some(v) => Self ( v as i32 ),
+            Some(v) => Self(v as i32),
             None => Self::None,
         }
     }
     // Cheat for "compatibility" with option.
     #[allow(non_upper_case_globals)]
-    pub const None: Self = ChunkPtr( -1 );
+    pub const None: Self = ChunkPtr(-1);
 }
 
 //TODO: impl Try once stable
@@ -91,12 +89,12 @@ impl ChunkPtr {
  *    }
  * }*/
 
-
 //TODO - use struct of arrays?
 /// Tree node that encompasses multiple children at once. This just barely fits into one cache line for octree.
 /// For each possible child, the node has two relative pointers:
 ///  * children will point to the TreeNode in a given branch direction
 ///  * chunk will point to the data chunk in a given branch direction
+///
 /// both pointers may be "None", indicating either no children, or no data
 #[derive(Clone, Debug)]
 pub struct TreeNode<const B: usize> {
@@ -117,26 +115,24 @@ impl<const B: usize> TreeNode<B> {
     }
 
     #[inline]
-    pub fn iter_existing_chunks(
-        &self,
-    ) -> impl Iterator<Item = (usize, usize)>  +'_ {
+    pub fn iter_existing_chunks(&self) -> impl Iterator<Item = (usize, usize)> + '_ {
         self.chunk.iter().filter_map(|c| c.get()).enumerate()
     }
 
     #[inline]
     pub fn is_empty(&self) -> bool {
-         self.children.iter().all(|c| c.is_none()) && self.chunk.iter().all(|c| *c== ChunkPtr::None)
+        self.children.iter().all(|c| c.is_none()) && self.chunk.iter().all(|c| *c == ChunkPtr::None)
     }
 }
 
 #[inline]
-pub fn iter_treenode_children< const N: usize>(
+pub fn iter_treenode_children<const N: usize>(
     children: &[NodePtr; N],
 ) -> impl Iterator<Item = (usize, usize)> + '_ {
     children
-    .iter()
-    .filter_map(|c| Some((*c)?.get() as usize))
-    .enumerate()
+        .iter()
+        .filter_map(|c| Some((*c)?.get() as usize))
+        .enumerate()
 }
 
 // utility struct for holding actual chunks and the node that owns them