static_aabb2d_index/
lib.rs

1//! This crate implements a static/fixed size indexing data structure for two dimensional axis
2//! aligned bounding boxes. The index allows for fast construction and fast querying but cannot be
3//! modified after creation.
4//!
5//! 2D axis aligned bounding boxes are represented by two extent points (four values):
6//! (min_x, min_y), (max_x, max_y).
7//!
8//! This is a port of the [flatbush](https://github.com/mourner/flatbush) javascript library.
9//!
10//! By default no unsafe code is used (`#![forbid(unsafe_code)]` is applied). Some unsafe
11//! optimizations can be enabled by toggling on the `unsafe_optimizations` flag.
12//!
13//! # Examples
14//! ```
15//! use static_aabb2d_index::*;
16//! // create builder for index containing 4 axis aligned bounding boxes
17//! // index also supports integers and custom types that implement the IndexableNum trait
18//! let mut builder: StaticAABB2DIndexBuilder<f64> = StaticAABB2DIndexBuilder::new(4);
19//! // add bounding boxes to the index
20//! // add takes in (min_x, min_y, max_x, max_y) of the bounding box
21//! builder.add(0.0, 0.0, 2.0, 2.0);
22//! builder.add(-1.0, -1.0, 3.0, 3.0);
23//! builder.add(0.0, 0.0, 1.0, 3.0);
24//! builder.add(4.0, 2.0, 16.0, 8.0);
25//! // note build() may return an error if the number of added boxes does not equal the static size
26//! // given at the time the builder was created or the type used fails to cast to/from a u16
27//! let index: StaticAABB2DIndex<f64> = builder.build().unwrap();
28//! // query the created index (min_x, min_y, max_x, max_y)
29//! let query_results = index.query(-1.0, -1.0, -0.5, -0.5);
30//! // query_results holds the index positions of the boxes that overlap with the box given
31//! // (positions are according to the order boxes were added the index builder)
32//! assert_eq!(query_results, vec![1]);
33//! // the query may also be done with a visiting function that can stop the query early
34//! let mut visited_results: Vec<usize> = Vec::new();
35//! let mut visitor = |box_added_pos: usize| -> Control<()> {
36//!     visited_results.push(box_added_pos);
37//!     // return continue to continue visiting results, break to stop early
38//!     Control::Continue
39//! };
40//!
41//! index.visit_query(-1.0, -1.0, -0.5, -0.5, &mut visitor);
42//! assert_eq!(visited_results, vec![1]);
43//! ```
44
45#![cfg_attr(not(feature = "unsafe_optimizations"), forbid(unsafe_code))]
46
47extern crate num_traits;
48mod core;
49mod static_aabb2d_index;
50pub use crate::core::*;
51pub use crate::static_aabb2d_index::*;
static_aabb2d_index/lib.rs

static_aabb2d_index/
lib.rs
