Crate fast_poisson

source ·
Expand description

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

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 Definitions