Crate fast_poisson

Generate a Poisson disk distribution.

This is an implementation of Bridson’s “Fast Poisson Disk Sampling” algorithm in arbitrary dimensions.

• Iterator-based generation lets you leverage the full power of Rust’s Iterators
• Lazy evaluation of the distribution means that even complex Iterator chains are as fast as O(N); with other libraries operations like mapping into another struct become O(N²) or more!
• Using Rust’s const generics allows you to consume the distribution with no additional dependencies

Features

These are the optional features you can enable in your Cargo.toml:

• single_precision changes the output, and all of the internal calculations, from using double-precision f64 to single-precision f32. Distributions generated with the single_precision feature are not required nor expected to match those generated without it. This also changes the default PRNG; see Poisson for details.
• derive_serde automatically derives Serde’s Serialize and Deserialize traits for Poisson. This relies on the serde_arrays crate to allow (de)serializing the const generic arrays used by Poisson.

Examples

use fast_poisson::Poisson2D;

// Easily generate a simple `Vec`
let points: Vec<[f64; 2]> = Poisson2D::new().generate();

// To fill a box, specify the width and height:
let points = Poisson2D::new().with_dimensions([100.0, 100.0], 5.0);

// Leverage `Iterator::map` to quickly and easily convert into a custom type in O(N) time!
// Also see the `Poisson::to_vec()` method
struct Point {
    x: f64,
    y: f64,
}
let points = Poisson2D::new().iter().map(|[x, y]| Point { x, y });

// Distributions are lazily evaluated; here only 5 points will be calculated!
let points = Poisson2D::new().iter().take(5);

// `Poisson` can be directly consumed in for loops:
for point in Poisson2D::new() {
    println!("X: {}; Y: {}", point[0], point[1]);
}

Higher-order Poisson disk distributions are generated just as easily:

use fast_poisson::{Poisson, Poisson3D, Poisson4D};

// 3-dimensional distribution
let points_3d = Poisson3D::new().iter();

// 4-dimensional distribution
let mut points_4d = Poisson4D::new();
// To achieve desired levels of performance, you should set a larger radius for higher-order
// distributions
points_4d.set_dimensions([1.0; 4], 0.2);
let points_4d = points_4d.iter();

// For more than 4 dimensions, use `Poisson` directly:
let mut points_7d = Poisson::<7>::new().with_dimensions([1.0; 7], 0.6);
let points_7d = points_7d.iter();

Upgrading

1.0.2

As of this release we no longer guarantee an MSRV beyond the current stable and beta.

1.0

This release raises the MSRV from 1.51 to 1.67.

This release fixes several bugs found in earlier versions, and removes the small_rng feature flag; see Poisson for details on what to use instead.

The builder pattern methods have been changed and now directly consume the Poisson. This means that this will no longer work:

let mut poisson = Poisson2D::new();
poisson.with_seed(0x5ADBEEF);
// This line will fail with "borrow of moved value"
let points = poisson.generate();

Instead use either of these approaches:

// Builder pattern
let builder = Poisson2D::new().with_seed(0xCAFEF00D);
let points = builder.generate();

// New `set_*` methods
let mut setters = Poisson2D::new();
setters.set_seed(0xCAFEF00D);
let points2 = setters.generate();

assert_eq!(points, points2);

Distributions are not expected to match those generated in earlier versions, even with identical seeds.

Structs

Iter

An iterator over the points in the Poisson disk distribution

Poisson

Poisson disk distribution in N dimensions

Type Aliases

Point

A Point is simply an array of Float values

Poisson2D

Poisson disk distribution in 2 dimensions

Poisson3D

Poisson disk distribution in 3 dimensions

Poisson4D

Poisson disk distribution in 4 dimensions