blue_noise/
lib.rs

1//! Blue Noise Library
2//!
3//! A comprehensive Rust implementation of Robert Ulichney's void-and-cluster
4//! algorithm for generating blue noise textures and applying high-quality
5//! dithering to images.
6//!
7//! # Features
8//!
9//! - Generate blue noise textures using the void-and-cluster algorithm
10//! - Apply blue noise dithering to images with customizable colors
11//! - FFT-optimized Gaussian blur for power-of-two dimensions
12//! - Seamless tiling with toroidal topology
13//! - Reproducible results with seeded random number generation
14//!
15//! # Quick Start
16//!
17//! ## Generating Blue Noise
18//!
19//! ```no_run
20//! use blue_noise::{BlueNoiseGenerator, BlueNoiseConfig, save_blue_noise_to_png};
21//!
22//! let config = BlueNoiseConfig {
23//!     width: 64,
24//!     height: 64,
25//!     sigma: 1.9,
26//!     seed: Some(42),
27//!     verbose: false,
28//!     ..Default::default()
29//! };
30//!
31//! let generator = BlueNoiseGenerator::new(config).unwrap();
32//! let result = generator.generate().unwrap();
33//! save_blue_noise_to_png(&result, "noise.png").unwrap();
34//! ```
35//!
36//! ## Dithering Images
37//!
38//! ```no_run
39//! use blue_noise::{
40//!     BlueNoiseTexture,
41//!     Color,
42//!     DitherOptions,
43//!     apply_dithering
44//! };
45//!
46//! let noise = BlueNoiseTexture::load("noise.png").unwrap();
47//! let options = DitherOptions {
48//!     foreground: Color::from_hex("#000000").unwrap(),
49//!     background: Color::from_hex("#ffffff").unwrap(),
50//!     width: Some(800),
51//!     height: None,
52//!     contrast: Some(1.2),
53//! };
54//!
55//! apply_dithering("input.jpg", "output.png", &noise, options).unwrap();
56//! ```
57//!
58//! # Algorithm
59//!
60//! The void-and-cluster algorithm works in 5 phases:
61//!
62//! 1. **Phase 0**: Generate initial binary pattern with random points
63//! 2. **Phase 1**: Serialize initial points by removing from tightest clusters
64//! 3. **Phase 2**: Fill to half capacity by adding to largest voids
65//! 4. **Phase 3**: Invert and fill to completion
66//! 5. **Phase 4**: Convert ranks to threshold map (0-255)
67//!
68//! All operations use toroidal topology (wraparound edges) to ensure
69//! seamless tiling.
70//!
71//! # Performance
72//!
73//! For power-of-two dimensions, Gaussian blur is performed using FFT,
74//! providing approximately 50% performance improvement. Generation times:
75//!
76//! - 64×64: ~2-5 seconds
77//! - 128×128: ~30-60 seconds
78//! - 256×256: Several minutes
79//!
80//! # References
81//!
82//! - Ulichney, R. (1993). "Void-and-cluster method for dither array generation"
83//! - Ulichney, R. (1988). "Dithering with blue noise"
84
85#![doc(html_root_url = "https://docs.rs/blue-noise/0.2.0")]
86#![warn(missing_docs)]
87#![warn(rust_2018_idioms)]
88
89/// Image dithering module
90pub mod dither;
91/// Blue noise generation module
92pub mod generator;
93
94// Re-export main types for convenience
95pub use dither::{
96    apply_dithering, BlueNoiseTexture, Color, DitherError, DitherOptions,
97};
98pub use generator::{
99    save_blue_noise_to_png, BlueNoiseConfig, BlueNoiseGenerator,
100    BlueNoiseResult, GeneratorError,
101};
blue_noise/lib.rs

blue_noise/
lib.rs
