poisson_diskus/lib.rs
1//! Sampling of a Poisson disk distribution in multiple dimensions.
2//!
3//! The Poisson disk distribution produces samples of which no two samples are too close
4//! to each other. This results in a more uniform distribution than from pure random sampling.
5//!
6//! This library is an implementation of the algorithm introduced by Robert Bridson \[1\]
7//! which is O(N) for producing N samples. That is, the sampling time increases linearly
8//! with the number of produced samples. For two-dimensional sampling, the sampling time
9//! increases with the area and for three-dimensional sampling with the volume.
10//!
11//! # Examples
12//! ## Three dimensions
13//! ```rust
14//! use poisson_diskus::bridson;
15//!
16//! let box_size = [3.0, 5.0, 7.0];
17//! let rmin = 0.5;
18//! let num_attempts = 30;
19//! let use_pbc = true;
20//!
21//! let coords = bridson(&box_size, rmin, num_attempts, use_pbc).unwrap();
22//! ```
23//!
24//! ## Larger number of dimensions
25//! ```rust
26//! use poisson_diskus::bridson;
27//!
28//! let box_size = [3.0, 5.0, 3.0, 2.0, 1.0];
29//! let rmin = 1.0;
30//! let num_attempts = 30;
31//! let use_pbc = true;
32//!
33//! // Output sample dimension is same as input box size
34//! let coords: Vec<[f64; 5]> = bridson(&box_size, rmin, num_attempts, use_pbc).unwrap();
35//!
36//! for coord in coords {
37//! assert_eq!(coord.len(), box_size.len());
38//! }
39//! ```
40//!
41//! # Citations
42//! \[1\] Bridson, R. (2007). Fast Poisson disk sampling in arbitrary dimensions. SIGGRAPH sketches, 10, 1.
43//!
44
45mod bridson;
46mod coord;
47mod error;
48mod grid;
49mod sample;
50
51pub use bridson::{bridson, bridson_rng};
52pub use error::Error;