Crate dithereens

Expand description

Functions and traits for quantizing values with deterministic hash-based error-diffusion.

Quantizing from f64/f32/f16 to u32/u16/u8 without dithering creates banding. This crate provides deterministic hash-based dithering to reduce quantization artifacts.

§Overview

Deterministic: Same input with same seed always produces same output.
Multiple methods: Hash, R2, GoldenRatio for 1D; IGN, SpatialHash, BlueNoise for 2D.
Single values: dither(), simple_dither().
Iterator processing: dither_iter(), simple_dither_iter().
In-place operations: dither_slice(), simple_dither_slice().
2D support: dither_slice_2d(), simple_dither_slice_2d() for images.
no_std support: Works in embedded environments.
Generic types: f32, f64, or any type implementing DitherFloat.

§Quick Start


let value: f32 = 0.5;

// Dither `value` to `127u8` or `128u8` deterministically
// The same index and seed will always produce the same result
let dithered_value: u8 =
    simple_dither(value, 255.0, 0, 42).clamp(0.0, 255.0) as u8;

assert!(dithered_value == 127 || 128 == dithered_value);

§Using Different Methods

let value = 0.5f32;
 
// Create method instances with a seed
let hash = Hash::new(42);
let r2 = R2::new(42);
let golden = GoldenRatio::new(42);

// Apply different dithering methods
let dithered_hash = simple_dither_with_method(value, 255.0, 0, &hash);
let dithered_r2 = simple_dither_with_method(value, 255.0, 0, &r2);
let dithered_golden = simple_dither_with_method(value, 255.0, 0, &golden);

§2D Image Dithering

let width = 256;
let height = 256;
let mut pixels: Vec<f32> = vec![0.5; width * height];

// Use IGN for fast 2D dithering
let method = InterleavedGradientNoise::new(42);
simple_dither_slice_2d(&mut pixels, width, 255.0, &method);

§Performance Guide

Benchmarks with 10,000 values:

Single values: dither(), simple_dither().
In-place slice operations: dither_slice(), simple_dither_slice() (fastest, zero allocation)
Iterator chains: dither_iter(), simple_dither_iter() (allocation overhead)

§Parallel Processing

Via rayon (enabled by default). With rayon enabled, _iter and _slice functions use parallel processing automatically.

§`no_std` Support

This crate supports no_std environments. The libm crate provides a native round() implementation. Without libm, a manual implementation is used.

[dependencies]
# `no_std`
dithereens = { version = "0.3", default-features = false }

[dependencies]
# Optional: uses `libm`'s `round()` function instead of a manual
# implementation for `no_std`.
dithereens = {
   version = "0.3",
   default-features = false,
   features = ["libm"]
}

§Native `f16` Support

Enable the nightly_f16 feature to use native f16 types (requires nightly Rust):

[dependencies]
dithereens = { version = "0.3", features = ["nightly_f16"] }

§Blue Noise Support

Enable the blue_noise feature to use true blue noise dithering with a precomputed 256×256×4 table (adds ~5MB to binary size):

[dependencies]
dithereens = { version = "0.3", features = ["blue_noise"] }

This enables the [BlueNoise] struct which provides high-quality blue noise dithering with stable seed-based variation.

Structs§

BlueNoiseApprox: Blue noise approximation using multiple octaves.
GoldenRatio: Golden ratio sequence for 1D low-discrepancy sampling.
Hash: Hash-based dithering (default method).
InterleavedGradientNoise: Interleaved Gradient Noise for 2D dithering.
R2: R2 low-discrepancy sequence for improved distribution.
SpatialHash: Spatial hash for 2D blue noise-like properties.

Traits§

DitherFloat: Minimal trait requirements for dithering.
DitherIteratorExt: Iterator adapter trait for dithering operations.
DitherMethod: Trait for 1D dithering methods.
DitherMethod2D: Trait for 2D dithering methods.
DitherParallelIteratorExt: Parallel iterator adapter trait for dithering operations.

Functions§

dither: Dither a value using the default hash method (backward compatible).
dither_2d: Dither a value using 2D coordinates.
dither_iter
dither_iter_with_method
dither_slice
dither_slice_2d
dither_slice_with_method
dither_with_method: Dither a value using a specific method.
simple_dither: Simple dither with default hash method (backward compatible).
simple_dither_2d: Simple dither with 2D coordinates.
simple_dither_iter
simple_dither_iter_with_method
simple_dither_slice
simple_dither_slice_2d
simple_dither_slice_with_method
simple_dither_with_method: Simple dither with specific method.