Blue Noise Dithering

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

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.

64×64 tileable blue noise texture

Installation

npm install

Usage

# Basic usage
npm run dither <input-image>

# Custom colours
npm run dither <input-image> -- -f <foreground-hex> -b <background-hex>

Examples

# 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

Dithering Command

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

Generate Command

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

• -s, --size <pixels> - Texture size (8-512, default: 64)
• --sigma <value> - Gaussian sigma (1.0-3.0, default: 1.9)
• --seed <number> - 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