dithereens

Before (top) and after (bottom) dithering a gradient (uses simple_dither(), i.e. defaults).

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 dithering 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().
• Image support: Both 1D methods (processing as flat array) and 2D methods (using coordinates).
• Custom methods: Use specific dithering algorithms via *_with_method() functions.
• no_std support: Works in embedded environments.
• Generic types: f32, f64, f16 (with nightly_f16 feature), or any type implementing DitherFloat.
• Blue noise: High-quality blue noise dithering (with blue_noise feature).

Quick Start

use dithereens::simple_dither;

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);

Dithering Methods

1D Methods (for sequential data and images as flat arrays)

• Hash (default): Fast hash-based dithering, good general-purpose quality.
• R2: Low-discrepancy sequence using the R2 sequence.
• GoldenRatio: Golden ratio-based sequence.

1D methods have been used successfully for image dithering for years by processing images as flat arrays. They work well when you don't need spatial correlation between pixels.

2D Methods (for images using spatial coordinates)

• InterleavedGradientNoise (IGN): Fast, good quality for real-time graphics.
• SpatialHash: Spatial hash function for blue noise-like properties.
• BlueNoiseApprox: Approximation combining IGN and SpatialHash.
• BlueNoise (requires blue_noise feature): True blue noise from precomputed tables.

2D methods use pixel coordinates to create spatially-aware dithering patterns, which can produce more visually pleasing results for images.

Using Custom Methods

use dithereens::{GoldenRatio, Hash, R2, simple_dither_with_linear_rng};

let value = 0.5f32;
let seed = 42;

// Use different dithering methods.
let hash_method = Hash::new(seed);
let r2_method = R2::new(seed);
let golden_method = GoldenRatio::new(seed);

let dithered_hash =
    simple_dither_with_linear_rng(value, 255.0, 0, &hash_method);
let dithered_r2 =
    simple_dither_with_linear_rng(value, 255.0, 0, &r2_method);
let dithered_golden =
    simple_dither_with_linear_rng(value, 255.0, 0, &golden_method);

Image Dithering with 1D Methods

1D methods work great for images when processed as flat arrays:

use dithereens::{Hash, simple_dither_slice};

// Example: dither a grayscale image.
let width = 256;
let height = 256;
let mut pixels: Vec<f32> = vec![0.5; width * height];

// Process entire image as flat array with 1D dithering.
simple_dither_slice(&mut pixels, 255.0, 42);

// pixels now contains dithered values.

2D Dithering for Images

2D methods use spatial coordinates for better visual results:

use dithereens::{InterleavedGradientNoise, simple_dither_slice_2d};

// Example: dither a grayscale image.
let width = 256;
let height = 256;
let mut pixels: Vec<f32> = vec![0.5; width * height];

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

// pixels now contains dithered values.

Performance Guide

Benchmarks with 10,000 values:

• Single values: dither(), simple_dither().
• In-place slice operations: dither_slice(), [simple_dither_slice()] (~5.6x faster than iterator methods).
• Iterator chains: dither_iter(), simple_dither_iter(), or DitherIteratorExt adapters (allocation overhead).

Parallel Processing

Via rayon (enabled by default). With rayon enabled, _iter and _slice functions use parallel processing automatically for better performance on large datasets.

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 for high-quality blue noise dithering:

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

This adds the BlueNoise struct which provides true blue noise dithering using a precomputed 256×256×4 table. Note: This increases binary size by ~5MB.

#[cfg(feature = "blue_noise")]
use dithereens::{BlueNoise, simple_dither_slice_2d};

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

let blue_noise = BlueNoise::new(42);
simple_dither_slice_2d(&mut pixels, width, 255.0, &blue_noise);

License

Apache-2.0 OR BSD-3-Clause OR MIT OR Zlib at your discretion.