# `dithr`
[](https://crates.io/crates/dithr)
|  |  |
_Before (left) and after (right) using `yliluoma_2_in_place`._
Buffer-first rust dithering and halftoning library.
Quantizing grayscale/RGB/RGBA buffers without dithering creates visible
banding and contouring. `dithr` provides deterministic ordered dithering,
diffusion, stochastic binary methods, palette-constrained workflows, and
advanced halftoning methods over typed mutable slices.
### Overview
- **Buffer-first API**: Works directly on mutable pixel slices with explicit
width, height, and stride.
- **Typed formats**: Supports `u8`, `u16`, and `f32` sample types across Gray,
Rgb, and Rgba layouts.
- **Quantization control**: Uses `QuantizeMode` for grayscale levels, RGB
levels, palette mapping, or single-color workflows.
- **Broad algorithm coverage**: Includes stochastic, ordered,
palette-oriented ordered, diffusion, variable diffusion, and advanced
halftoning families.
- **Palette workflow**: Includes `Palette<S>` and `IndexedImage<S>` for
constrained output and indexed results.
- **Optional integrations**: `image` adapters for `DynamicImage` workflows and
`rayon` parallel wrappers for selected families.
### Installation
```bash
cargo add dithr
```
```toml
[dependencies]
dithr = "0.3.0"
```
```bash
cargo add dithr --features image
cargo add dithr --features rayon
```
### Quick Start
```rust
use dithr::{gray_u8, QuantizeMode, Result};
use dithr::ordered::bayer_8x8_in_place;
fn main() -> Result<()> {
let width = 64_usize;
let height = 64_usize;
let mut data = Vec::with_capacity(width * height);
for y in 0..height {
for x in 0..width {
let value = ((x + y * width) * 255 / (width * height - 1)) as u8;
data.push(value);
}
}
let mut buffer = gray_u8(&mut data, width, height, width)?;
bayer_8x8_in_place(&mut buffer, QuantizeMode::gray_bits(1)?)?;
assert!(data.iter().all(|&v| v == 0 || v == 255));
Ok(())
}
```
### Core Data Model
`dithr` is organized around a small set of types that are shared across
algorithm families.
- **`Buffer<'a, S, L>`**: Mutable typed view of image data (`S` = sample type,
`L` = layout).
- **`BufferKind` / `PixelFormat`**: Runtime format metadata (`PixelFormat` is
an alias of `BufferKind`).
- **`Palette<S>`**: Palette storage for fixed-color workflows (1 to 256
entries).
- **`IndexedImage<S>`**: Indexed output (`Vec<u8>` indices) paired with a typed
palette.
- **`QuantizeMode<'a, S>`**: Common quantization target model used by
ordered/diffusion/stochastic/dot/Riemersma families.
- **`Error` / `Result<T>`**: Crate-level error and result surface.
### Typed Buffers, Sample Types, and Layouts
Supported runtime kinds:
- `Gray8`, `Rgb8`, `Rgba8`
- `Gray16`, `Rgb16`, `Rgba16`
- `Gray32F`, `Rgb32F`, `Rgba32F`
Typed buffer aliases:
- `GrayBuffer8`, `RgbBuffer8`, `RgbaBuffer8`
- `GrayBuffer16`, `RgbBuffer16`, `RgbaBuffer16`
- `GrayBuffer32F`, `RgbBuffer32F`, `RgbaBuffer32F`
Constructor helpers:
- Gray: `gray_u8`, `gray_u16`, `gray_32f`
- Rgb: `rgb_u8`, `rgb_u16`, `rgb_32f`
- Rgba: `rgba_u8`, `rgba_u16`, `rgba_32f`
- Packed variants: `gray_u8_packed`, `rgb_u16_packed`, `rgba_32f_packed`, etc.
Generic constructors remain available on `Buffer`:
- `Buffer::new_typed(...)`
- `Buffer::new_packed_typed(...)`
- Compatibility constructors with runtime kind checking:
- `Buffer::new(...)`
- `Buffer::new_packed(...)`
### Choosing a Quantization Mode
`QuantizeMode<'a, S>` is the canonical quantization model:
- `GrayLevels(u16)`
- `RgbLevels(u16)`
- `Palette(&Palette<S>)`
- `SingleColor { fg: [S; 3], levels: u16 }`
Convenience constructors:
- Generic:
- `QuantizeMode::gray_levels(levels)`
- `QuantizeMode::rgb_levels(levels)`
- `QuantizeMode::palette(&palette)`
- `QuantizeMode::single_color(fg, levels)`
- `u8` compatibility helpers:
- `QuantizeMode::gray_bits(bits)`
- `QuantizeMode::rgb_bits(bits)`
- Shared conversion helper:
- `levels_from_bits(bits)`
Use `GrayLevels`/`gray_bits` when output should be grayscale levels,
`RgbLevels`/`rgb_bits` for uniform per-channel color quantization, `Palette`
for strict membership in a fixed color set, and `SingleColor` for
foreground-scaled tonal output.
### Dithering and Halftoning Method Families
#### Binary stochastic
Fast binary dithering with fixed or randomized threshold behavior.
- `threshold_binary_in_place`
- `random_binary_in_place`
Parallel variants (`rayon` feature):
- `threshold_binary_in_place_par`
- `random_binary_in_place_par`
#### Ordered methods
Deterministic threshold-map methods with predictable structure and
straightforward benchmarking.
Bayer:
- `bayer_2x2_in_place`
- `bayer_4x4_in_place`
- `bayer_8x8_in_place`
- `bayer_16x16_in_place`
Cluster-dot:
- `cluster_dot_4x4_in_place`
- `cluster_dot_8x8_in_place`
- `void_and_cluster_in_place`
Custom map:
- `custom_ordered_in_place`
- `adaptive_ordered_dither_in_place`
- `space_filling_curve_ordered_dither_in_place`
- `ranked_dither_in_place`
- `image_based_dither_screen_in_place`
- `polyomino_ordered_dither_in_place`
- `stochastic_clustered_dot_in_place`
- `am_fm_hybrid_halftoning_in_place`
- `clustered_am_fm_halftoning_in_place`
- `blue_noise_multitone_dither_in_place`
Parallel variants (`rayon` feature):
- `bayer_2x2_in_place_par`
- `bayer_4x4_in_place_par`
- `bayer_8x8_in_place_par`
- `bayer_16x16_in_place_par`
- `cluster_dot_4x4_in_place_par`
- `cluster_dot_8x8_in_place_par`
- `custom_ordered_in_place_par`
#### Palette-oriented ordered (Yliluoma)
Ordered methods designed for fixed-palette workflows.
- `yliluoma_1_in_place`
- `yliluoma_2_in_place`
- `yliluoma_3_in_place`
#### Classic diffusion
Scanline error diffusion kernels for higher local tonal quality.
- `floyd_steinberg_in_place`
- `false_floyd_steinberg_in_place`
- `jarvis_judice_ninke_in_place`
- `stucki_in_place`
- `burkes_in_place`
- `sierra_in_place`
- `two_row_sierra_in_place`
- `sierra_lite_in_place`
- `stevenson_arce_in_place`
- `atkinson_in_place`
#### Extended diffusion
Additional diffusion kernels with different spread patterns.
- `fan_in_place`
- `shiau_fan_in_place`
- `shiau_fan_2_in_place`
- `block_error_diffusion_in_place`
Scope note: `block_error_diffusion_in_place` is grayscale-only.
#### Variable diffusion
Tone-dependent coefficient families.
- `ostromoukhov_in_place`
- `zhou_fang_in_place`
- `hvs_optimized_error_diffusion_in_place`
- `gradient_based_error_diffusion_in_place`
- `multiscale_error_diffusion_in_place`
- `feature_preserving_msed_in_place`
- `green_noise_msed_in_place`
- `linear_pixel_shuffling_in_place`
- `tone_dependent_error_diffusion_in_place`
- `structure_aware_error_diffusion_in_place`
- `adaptive_vector_error_diffusion_in_place`
- `vector_error_diffusion_in_place`
- `semivector_error_diffusion_in_place`
- `hierarchical_error_diffusion_in_place`
- `mbvq_color_error_diffusion_in_place`
- `neugebauer_color_error_diffusion_in_place`
- `multichannel_green_noise_error_diffusion_in_place`
Scope note: variable diffusion methods are grayscale-only except
`adaptive_vector_error_diffusion_in_place`, `vector_error_diffusion_in_place`,
`semivector_error_diffusion_in_place`, and
`hierarchical_error_diffusion_in_place`,
`mbvq_color_error_diffusion_in_place`, and
`neugebauer_color_error_diffusion_in_place`, and
`multichannel_green_noise_error_diffusion_in_place`, which support Rgb/Rgba
with alpha preservation on Rgba.
#### Advanced halftoning
Specialized methods with narrower scope than the ordered/diffusion baseline.
- `riemersma_in_place`
- `knuth_dot_diffusion_in_place`
- `optimized_dot_diffusion_in_place`
- `direct_binary_search_in_place`
- `clustered_dot_direct_multibit_search_in_place`
- `direct_pattern_control_in_place`
- `hierarchical_colorant_dbs_in_place`
- `lattice_boltzmann_in_place`
- `electrostatic_halftoning_in_place`
- `model_based_med_in_place`
- `least_squares_model_based_in_place`
Scope notes:
- `direct_binary_search_in_place`,
`clustered_dot_direct_multibit_search_in_place`,
`lattice_boltzmann_in_place`, `electrostatic_halftoning_in_place`,
`model_based_med_in_place`, and `least_squares_model_based_in_place` require
integer grayscale buffers.
- `direct_pattern_control_in_place` supports integer `Rgb`/`Rgba` buffers;
alpha is preserved for `Rgba`.
- `hierarchical_colorant_dbs_in_place` supports integer `Rgb` buffers.
- `riemersma_in_place`, `knuth_dot_diffusion_in_place`, and
`optimized_dot_diffusion_in_place` support Gray/Rgb/Rgba layouts, with alpha
preserved for Rgba paths.
### Palette Workflow
`dithr` keeps palette workflows explicit: define a palette, dither into it, and
optionally build indexed output.
```rust
use dithr::{rgb_u8, IndexedImage, Palette, Result};
use dithr::ordered::yliluoma_1_in_place;
fn main() -> Result<()> {
let width = 32_usize;
let height = 32_usize;
let mut data = vec![0_u8; width * height * 3];
for y in 0..height {
for x in 0..width {
let i = (y * width + x) * 3;
data[i] = (x * 255 / (width - 1)) as u8;
data[i + 1] = (y * 255 / (height - 1)) as u8;
data[i + 2] = ((x + y) * 255 / (width + height - 2)) as u8;
}
}
let palette = Palette::new(vec![
[0, 0, 0],
[255, 255, 255],
[255, 0, 0],
[0, 0, 255],
])?;
let mut buffer = rgb_u8(&mut data, width, height, width * 3)?;
yliluoma_1_in_place(&mut buffer, &palette)?;
let mut indices = Vec::with_capacity(width * height);
for px in data.chunks_exact(3) {
indices.push(palette.nearest_rgb_index([px[0], px[1], px[2]]) as u8);
}
let indexed = IndexedImage::new(indices, width, height, palette)?;
assert_eq!(indexed.len(), width * height);
Ok(())
}
```
Built-in palette helpers are also exported:
- `cga_palette()`
- `grayscale_2()`
- `grayscale_4()`
- `grayscale_16()`
### Optional image Integration
Enable `image` to adapt `image` crate buffers into `dithr` buffers.
Typed adapters:
- `gray8_image_as_buffer`
- `rgb8_image_as_buffer`
- `rgba8_image_as_buffer`
- `gray16_image_as_buffer`
- `rgb16_image_as_buffer`
- `rgba16_image_as_buffer`
- `rgb32f_image_as_buffer`
- `rgba32f_image_as_buffer`
Dynamic adapter:
- `dynamic_image_as_buffer(&mut image::DynamicImage) -> Result<DynamicImageBuffer<'_>>`
Dynamic variants:
- `DynamicImageBuffer::Gray8`
- `DynamicImageBuffer::Rgb8`
- `DynamicImageBuffer::Rgba8`
- `DynamicImageBuffer::Gray16`
- `DynamicImageBuffer::Rgb16`
- `DynamicImageBuffer::Rgba16`
- `DynamicImageBuffer::Rgb32F`
- `DynamicImageBuffer::Rgba32F`
`DynamicImage::ImageLumaA8` and `DynamicImage::ImageLumaA16` are promoted to
`DynamicImageBuffer::Rgba8` and `DynamicImageBuffer::Rgba16` during adaptation.
Current manifest configuration enables PNG and JPEG codecs for the optional
`image` dependency.
### Optional rayon Integration
Enable `rayon` for parallel wrappers where available.
Parallelized families:
- Ordered: all `*_in_place_par` ordered wrappers
- Yliluoma: `yliluoma_1_in_place_par`, `yliluoma_2_in_place_par`,
`yliluoma_3_in_place_par`
- Binary stochastic: `threshold_binary_in_place_par`,
`random_binary_in_place_par`
Current serial-only families:
- Diffusion (classic/extended/variable)
- Advanced halftoning
### Example Programs
Raw buffer workflows:
```bash
cargo run --example gray_buffer
cargo run --example rgb_buffer
cargo run --example indexed_palette
```
Image workflows (`image` feature):
```bash
cargo run --example image_bayer_png --features image -- input.png output.png
cargo run --example image_palette_png --features image -- input.png output.png
```
### Benchmarks and Development
Bench families (`criterion`):
- `stochastic`
- `ordered`
- `yliluoma`
- `diffusion`
- `advanced`
```bash
cargo bench --no-run
cargo bench --bench stochastic
cargo bench --bench ordered
cargo bench --bench yliluoma
cargo bench --bench diffusion
cargo bench --bench advanced
```
Development checks:
```bash
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo check --all-features
cargo test --workspace --all-features --lib --tests --examples
cargo test --doc --all-features
```
### Limitations and Scope
- Core processing is in-memory and buffer-first; it does not provide general
image editing workflows.
- Not every algorithm supports every format/layout/sample combination.
- `am_fm_hybrid_halftoning_in_place` and
`clustered_am_fm_halftoning_in_place` are grayscale-only.
- `blue_noise_multitone_dither_in_place` is grayscale-only.
- Variable diffusion methods are grayscale-only except
`adaptive_vector_error_diffusion_in_place`,
`vector_error_diffusion_in_place`,
`semivector_error_diffusion_in_place`,
`mbvq_color_error_diffusion_in_place`, and
`neugebauer_color_error_diffusion_in_place`, and
`multichannel_green_noise_error_diffusion_in_place` for Rgb/Rgba.
- `block_error_diffusion_in_place` is grayscale-only.
- `direct_binary_search_in_place`,
`clustered_dot_direct_multibit_search_in_place`,
`lattice_boltzmann_in_place`, and `electrostatic_halftoning_in_place` are
integer grayscale-only.
- Parallel wrappers are currently provided for ordered, Yliluoma, and binary
stochastic families.
### References
- Dither: <https://en.wikipedia.org/wiki/Dither>
- Ordered dithering: <https://en.wikipedia.org/wiki/Ordered_dithering>
- Error diffusion: <https://en.wikipedia.org/wiki/Error_diffusion>
- Yliluoma positional dithering: <http://bisqwit.iki.fi/story/howto/dither/jy/>
- Dithering eleven algorithms:
<https://tannerhelland.com/2012/12/28/dithering-eleven-algorithms-source-code.html>
- Ostromoukhov variable-coefficient diffusion:
<https://www.iro.umontreal.ca/~ostrom/publications/pdf/SIGGRAPH01_varcoeffED.pdf>
- Zhou-Fang threshold modulation:
<https://history.siggraph.org/learning/improving-mid-tone-quality-of-variable-coefficient-error-diffusion-using-threshold-modulation-by-zhou-and-fang/>
- Multiscale error diffusion:
<https://doi.org/10.1109/83.557360>, <https://mcl.usc.edu/wp-content/uploads/2014/01/1997-03-A-multiscale-error-diffusion-technique-for-digital-Halftoning.pdf>
- Feature-preserving multiscale error diffusion:
<https://ira.lib.polyu.edu.hk/bitstream/10397/1524/1/J-JEI-Feature-preserving%20multiscale%20error%20diffusion_04.pdf>, <https://doi.org/10.1117/1.1758728>
- Green-noise multiscale error diffusion:
<https://pubmed.ncbi.nlm.nih.gov/20215075/>, <https://www.eie.polyu.edu.hk/~enyhchan/J-TIP-Green_noise_digital_halftoning_with_MED.pdf>
- Multichannel green-noise error diffusion:
<https://doi.org/10.1109/83.841537>, <https://doi.org/10.1364/JOSAA.16.001575>
- Adaptive vector error diffusion:
<https://pubmed.ncbi.nlm.nih.gov/18282985/>, <https://doi.org/10.1109/83.597270>
- HVS-optimized error diffusion (Kolpatzik-Bouman):
<https://engineering.purdue.edu/~bouman/publications/pdf/jei1scan.pdf>, <https://engineering.purdue.edu/~bouman/publications/pub_doc.html>
- Vector and semivector color error diffusion:
<https://pubmed.ncbi.nlm.nih.gov/18255498/>, <https://doi.org/10.1109/83.951540>, <https://users.ece.utexas.edu/~bevans/papers/2003/colorDiffusion/index.html>
- MBVQ/Neugebauer color error diffusion:
<https://www.mdpi.com/2313-433X/6/4/23>, <https://doi.org/10.3390/jimaging6040023>, <https://patents.google.com/patent/US5991438A/en>, <https://patents.google.com/patent/EP0895408A2/en>
- Block error diffusion:
<https://doi.org/10.1109/TIP.2005.859776>, <https://shiftleft.com/mirrors/www.hpl.hp.com/personal/Niranjan_Damera-Venkata/files/ibc.pdf>
- Hierarchical error diffusion:
<https://pubmed.ncbi.nlm.nih.gov/19473943/>, <https://doi.org/10.1109/TIP.2009.2019778>
- Tone-dependent error diffusion:
<https://pubmed.ncbi.nlm.nih.gov/15376941/>, <https://pubmed.ncbi.nlm.nih.gov/17283778/>
- Structure-aware error diffusion:
<https://perso.liris.cnrs.fr/ostrom/publications/pdf/SIGGRAPH-ASIA09_saed.pdf>
- Linear pixel shuffling error diffusion:
<https://repository.rit.edu/other/391/>, <https://www.imaging.org/common/uploaded%20files/pdfs/Papers/2000/PICS-0-81/1625.pdf>
- Riemersma dithering: <https://www.compuphase.com/riemer.htm>
- Knuth dot diffusion: <https://dl.acm.org/doi/10.1145/35039.35040>
- Optimized dot diffusion: <https://doi.org/10.1109/83.841944>
- Direct binary search halftoning: <https://doi.org/10.1117/12.135959>
- Model-based halftoning (MED + LSMB):
<https://pubmed.ncbi.nlm.nih.gov/18282991/>, <https://doi.org/10.1117/12.135965>, <https://users.eecs.northwestern.edu/~pappas/papers/pappas_neuhoff_tip99.pdf>
- Lattice-Boltzmann halftoning:
<https://www.mia.uni-saarland.de/Publications/hagenburg-isvc09.pdf>
- Electrostatic halftoning:
<https://onlinelibrary.wiley.com/doi/10.1111/j.1467-8659.2010.01716.x>
- Void-and-cluster dithering: <https://docslib.org/doc/9596963/the-void-and-cluster-method-for-dither-array-generation>, <https://cv.ulichney.com/papers/1994-filter-design.pdf>
- Adaptive ordered dither: <https://doi.org/10.1006/gmip.1996.0414>, <https://www.sciencedirect.com/science/article/pii/S1077316996904141>
- Space-filling curve ordered dither: <https://doi.org/10.1016/S0097-8493(98)00043-0>, <https://www.sciencedirect.com/science/article/pii/S0097849398000430>
- Ranked dither: <https://www.mayagupta.org/publications/GuptaBowenSPIE07.pdf>
- Image-based dither screens: <https://graphicsinterface.org/wp-content/uploads/gi1999-22.pdf>, <https://doi.org/10.20380/GI1999.22>
- Polyomino-based digital halftoning: <https://arxiv.org/abs/0812.1647>, <https://doi.org/10.48550/arXiv.0812.1647>
- Stochastic clustered-dot dithering: <https://perso.liris.cnrs.fr/victor.ostromoukhov/publications/pdf/SPIE99_StochasticClust.pdf>, <https://pubmed.ncbi.nlm.nih.gov/18255440/>
- AM/FM hybrid halftoning: <https://engineering.purdue.edu/~bouman/publications/orig-pdf/jei8.pdf>, <https://doi.org/10.1117/12.643690>
- Clustered AM/FM halftoning: <https://doi.org/10.2352/ISSN.2169-4451.2004.20.1.art00025_2>, <https://dblp.org/db/conf/clrimg/clrimg2006.html>
- Blue-noise multitone dithering: <https://doi.org/10.1109/TIP.2008.926145>, <https://www.eecis.udel.edu/~arce/files/Publications/5-Multitone.pdf>
- Clustered-dot direct multibit search: <https://pubmed.ncbi.nlm.nih.gov/28113172/>, <https://doi.org/10.1109/TIP.2016.2552723>, <https://research.ibm.com/publications/hybrid-halftoning-using-direct-multi-bit-search-dms-screen-algorithm>
- Direct pattern control halftoning: <https://pubmed.ncbi.nlm.nih.gov/28613170/>, <https://doi.org/10.1109/TIP.2017.2713939>, <https://cv.ulichney.com/papers/2017-PARAWACS-IEEE.pdf>
- Hierarchical colorant DBS (MBVQ-guided): <https://pubmed.ncbi.nlm.nih.gov/20236895/>, <https://doi.org/10.1109/TIP.2010.2045690>, <https://pubmed.ncbi.nlm.nih.gov/28613170/>
## License
MIT. See [LICENSE](LICENSE).
