Blue Noise Dithering

A CLI to dither images with blue noise, and generate blue noise textures using the void-and-cluster algorithm.

!Dithered profile image

What is Blue Noise?

Blue noise distributes pixels evenly, avoiding the clusters and voids of white noise and the repetitive patterns of Bayer dithering. The result is natural-looking dithered images that preserve detail without obvious artefacts.

!Blue noise texture

_64×64 tileable blue noise texture_

Installation

``bash
npm install
`

Usage

`bash


Basic usage

npm run dither

Custom colours

npm run dither -- -f -b
`

$3

`bash


Black and white

npm run dither input/claude-shannon-mouse-mit-00.jpg

Custom colours

npm run dither input/claude-shannon-mouse-mit-00.jpg -- -f "#ff0000" -b "#ffffff"

Different noise texture

npm run dither input/claude-shannon-mouse-mit-00.jpg -- -n custom-noise.png
`

CLI Options

$3

- - Path to input image (required)
- -o, --output - Output directory (default: "output")
- -n, --noise - Path to blue noise texture (default: "./blue-noise.png")
- -f, --foreground - Foreground colour in hex (default: "#000000")
- -b, --background - Background colour in hex (default: "#ffffff")
- -w, --width - Resize image width
- -h, --height - Resize image height
- -c, --contrast - Adjust contrast (default: 1.0)

$3

`bash
npm run start generate -- --size 64 --sigma 1.9 --verbose
`

- -s, --size - Texture size (8-512, default: 64)
- --sigma - Gaussian sigma (1.0-3.0, default: 1.9)
- --seed - Random seed for reproducibility
- -v, --verbose` - Show generation progress

How It Works

Each pixel in the input image is compared against the corresponding blue noise threshold value. If brighter than the threshold, use the background colour; if darker, use the foreground colour. The noise texture tiles seamlessly across the image.

Generating Blue Noise

Uses the void-and-cluster algorithm (Ulichney, 1993): identifies clusters and voids using Gaussian blur, then redistributes pixels until evenly spread. Each pixel gets a rank determining its threshold value.

The texture tiles seamlessly using torus topology. Power-of-two dimensions (64×64, 128×128) use FFT optimisation for ~50% faster generation.

Performance: 64×64 in ~2-5s, 128×128 in ~30-60s. Pre-generate textures for production use.

References

- Void-and-cluster method for dither array generation - Ulichney (1993)
- Dithering with blue noise - Ulichney (1988)

Additional Resources

- Ditherpunk - Interactive dithering playground
- Dithering - Part 1 - Deep dive into dithering techniques
- Dither Asteroids - Dithering asteroids game