Documentation

Algorithm reference and usage guide

Overview

Dither is a browser-based image dithering library built for the modern web. It implements three classic dither algorithms that run entirely on the Canvas API — no server processing required.

Each algorithm reduces the color palette of an image while using spatial patterns to approximate the original tones. The result is a distinctive, retro-luxury aesthetic reminiscent of early digital graphics and high-end instrument displays.

Floyd-Steinberg Dithering

Floyd-Steinberg is an error diffusion algorithm. For each pixel, it finds the closest color in the target palette, then distributes the quantization error to neighboring pixels using fixed ratios.

error = old_pixel - new_pixel

pixel[x+1][y]     += error × 7/16
pixel[x-1][y+1]   += error × 3/16
pixel[x][y+1]     += error × 5/16
pixel[x+1][y+1]   += error × 1/16

Best for: photographic images, smooth gradients. Produces the highest perceived quality of the three algorithms.

Atkinson Dithering

Developed by Bill Atkinson for the original Macintosh. It spreads error to six neighboring pixels but keeps only 6/8 of the total error, leaving 2/8 unquantized. This preserves highlights and creates a characteristic look.

error = old_pixel - new_pixel

pixel[x+1][y]     += error × 1/8
pixel[x+2][y]     += error × 1/8
pixel[x-1][y+1]   += error × 1/8
pixel[x][y+1]     += error × 1/8
pixel[x+1][y+1]   += error × 1/8
pixel[x][y+2]     += error × 1/8

Best for: retaining highlight detail, screen-like display aesthetics. A gentler look than Floyd-Steinberg.

Bayer Matrix (Ordered Dithering)

Ordered dithering uses a fixed Bayer threshold matrix. Each pixel's intensity is compared against a threshold from the repeating matrix to determine its quantized value. The result is a predictable, grid-like pattern.

Bayer 2×2 matrix:
┌─────┬─────┐
│  0  │  2  │
├─────┼─────┤
│  3  │  1  │
└─────┴─────┘

threshold = matrix[x % n][y % n]
pixel = luminance < threshold ? 0 : 255

Best for: graphic design, logo treatments, and any application where a consistent repeating texture is desired. Matrix size (2, 4, or 8) controls pattern density.

Palette Reference

Each palette defines the target color space for the dither output. The algorithm maps every pixel to the closest color in this palette.

Black & White2 colors

Pure binary output. Every pixel becomes either black or white.

Grayscale16 colors

16 levels of gray. Smooth tonal range with no color.

RGB 2-bit64 colors

2 bits per channel — 64 total colors. Dense but visible quantization.

RGB 3-bit512 colors

3 bits per channel — 512 colors. Good balance of size and quality.

RGB 4-bit4096 colors

4 bits per channel — 4096 colors. Near-photographic quality.

Component Usage

Import and use the component library in any React project. Components are styled for dark-themed, instrument-grade interfaces.

import { DitheredButton } from "./components/ui/DitheredButton";
import { DitheredCard } from "./components/ui/DitheredCard";
import { DitheredSlider } from "./components/ui/DitheredSlider";

// Example: a control panel
&lt;DitheredCard variant="glass"&gt;
  &lt;DitheredSlider label="Bit Depth" min={1} max={8} /&gt;
  &lt;DitheredButton variant="primary"&gt;Apply&lt;/DitheredButton&gt;
&lt;/DitheredCard&gt;

API Reference

applyDither(imageData, options)

The core function that processes an ImageData object and returns a dithered copy.

Parameter	Type	Description
imageData	ImageData	Source image pixel data
options.algorithm	"floyd-steinberg" \| "atkinson" \| "bayer"	Dither algorithm to apply
options.palette	"bw" \| "grayscale" \| "rgb2" \| "rgb3" \| "rgb4"	Target color palette
options.bitDepth	number	Bits per channel (1-4)
options.bayerSize	number	Bayer matrix size (2, 4, or 8)

PALETTES

A record of available palette names and their human-readable labels.