What does dith do?
dith is a deterministic dithering CLI built for agents. Every command takes --json, writes palette-exact output, and returns a machine-readable report. The same inputs and flags always produce byte-identical files.
Setup
- Check for the binary with
dith --version.- Inside the dith source checkout without a global install, run it via
cargo run --release -- <args>(ormbx run -- <args>whenmbxis available). - If dith is missing, tell the user and offer an install command from references/cli.md. Wait for their approval before installing anything.
- Inside the dith source checkout without a global install, run it via
- Do not rely on memorized catalogs when the exact set matters. Ask the binary:
dith list presets|algorithms|palettes|generators|formats --json, filterable with--tag <substr>or--category <name>dith capabilitiesfor the full manifest of commands, parameter ranges, and the default recipe (about 40 KB, so preferlistwhen one catalog is enough)
Core workflow
- Understand the source. For an existing image, run
dith inspect <image> --json. It reports dimensions, transparency, luminance percentiles (p5/p50/p95),dynamic_range, dominant colors, and preset recommendations with ready-to-run commands. - Pick a starting point from the style guide below. When the direction is open, render a contact sheet and look at it before committing:
dith compare <image> -o sheet.png --presets mac-classic,editorial-print,risograph,film-stipple --json - Validate complex flag sets first with
--dry-run --json. This catches bad values and shows plannedoutput_dimensionswithout writing files. - Render with
apply,generate,animate, orbatch, always with--json. Single-file commands overwrite existing outputs by default. Add--no-clobberwhen existing files must not be touched; inbatchit applies to each file. - Verify before reporting success. See Verify the result.
- Make it reproducible when the look will be reused. Pass
--emit-recipe(adds arecipeobject to the report) or--save-preset <name>(writes.dith/presets/<name>.json).
Choose a look
Start from a preset, then override individual flags. Explicit flags always win over the preset.
| Goal | Start with | Notes |
|---|---|---|
| Classic 1-bit Mac / editorial portrait | --preset mac-classic (atkinson) | Atkinson drops 2/8 of the error, so highlights stay airy. Add --sharpen 0.4 on soft photos. |
| Refined monochrome print / newspaper | --preset editorial-print (ostromoukhov) | Smoothest gradients of the error-diffusion family. |
| Filmic stipple, no grid artifacts | --preset film-stipple (blue-noise) | Best general modern look; also stable in animation. |
| Risograph poster | --preset risograph, risograph-red, risograph-duo | Duotone and two-drum overprint looks on warm paper. |
| Comic / zine halftone | --preset halftone-zine | Pair with --format svg --svg-shape circle for vector dots. |
| Game Boy / pixel art | --preset gameboy, pico8 | Ordered Bayer plus chunky --pixel-size. |
| CRT / terminal glow | --preset crt-amber, phosphor | Dark-key images suit these best. |
| Engraving / woodcut | --preset woodcut, --algorithm crosshatch | Line screens; tune with --pattern-scale. |
| Blueprint / technical | --preset blueprint | Prussian blue and chalk duotone. |
| Keep the photo's own colors | --preset lo-fi-photo or --auto-palette N | Extracts N Oklab colors (2–64) from the image. |
| Exact brand colors | --colors "#0f172a,#2563eb,#f5efe6" | Combine with any algorithm or preset. |
| Neon hero gradients / dark UI | --preset vapor-mesh with generate mesh |
references/catalog.md has every preset, palette, algorithm, and generator with when to use each.
Craft rules
- Tone before dithering. Dithering amplifies flat or muddy input.
- Low
dynamic_range(under about 0.5) or a narrow p5–p95 spread: add--auto-levelsor--contrast 0.1..0.3. - Soft photo going to 1-bit or Atkinson:
--sharpen 0.3..0.6. - Dark midtones:
--gamma 0.7..0.9(values under 1 brighten). Bright, washed-out input:--gamma 1.2..1.5. - Nudging overall density:
--bias(negative is darker, positive is lighter, range ±0.5).
- Low
- Size first. Cap with
--max-dim(or--width/--heightplus--fit contain|cover|stretch). Dither patterns are per-pixel, so a dithered image must never be resized afterwards. Render at the final display size instead. - Chunky pixels.
--pixel-size Ndownsamples, dithers, then nearest-upscales, so output dimensions are unchanged. - Ordered screen size.
--pattern-scale 2..4enlarges Bayer, halftone, line, and blue-noise cells for bolder, more graphic texture. - Color space. Keep the default
oklab. Usesrgbonly to mimic legacy hardware math;linearis physically linear light. - Determinism. Stochastic algorithms (
blue-noise,random,ign),--noise, and--auto-paletteuse--seed(default 42). Change the seed for variations and keep it fixed for reproducibility. - Transparency. Logos and icons with alpha:
--alpha-mode preservekeeps the alpha channel,thresholdgives a crisp 1-bit mask,dithergives a stippled fade, andflatten --background "#hex"composites onto a color. - Turning off preset parts. Most monochrome presets turn on
--grayscaleand--auto-levels. Use--no-grayscale,--no-auto-levels, and--no-serpentineto disable what a preset turned on.
Output formats
The format is inferred from the -o extension; pass --format to override it.
- PNG (default): lossless and pixel-exact. The right choice almost always.
- WebP: compact for the web. JPEG destroys dither patterns, so never use it for dithered output unless the user insists.
- SVG:
--svg-shape rect(run-length merged rectangles, smallest),circle(halftone dots), ordot(inset dots).--svg-skip-bgdrops the dominant background color for overlays. SVG grows with pixel count, and circles are much larger than rects, so keep--max-dimaround 120–320. - Terminal text:
--format braille|asciiwith--text-width N.-ois optional and the text goes to stdout. - Stdin/stdout: pass
-as input or as-o -.
Animation
dith animate takes one of four kinds of input:
- a pattern name (
sphere,waves,mesh,plasma, ...) for a seamless procedural loop. Each pattern moves differently (the sphere stays still while its light orbits, for example); themotionfield ofdith list generators --jsondescribes it. To check the motion cheaply before a full render, export a small spritesheet (--anim-format spritesheet --sheet-cols <frames> --canvas-width 160 --canvas-height 120) and look at it. - an animated GIF, APNG, or WebP to re-dither
- several image files as a frame sequence
- a single static image, which gets film boil (
--temporal boilis the default for this case)
Output goes to .gif (exact palette, smallest), .apng (full RGBA), a spritesheet .png via --anim-format spritesheet --sheet-cols N, or numbered PNG frames via --frames-dir DIR.
- Flicker.
--temporal locked(the default) fixes the screen and seed across frames, but it only makes static regions rock-solid with per-pixel algorithms: ordered screens (bayer*,halftone, line screens),blue-noise,ign,random, andthreshold. Error diffusion (floyd-steinberg,atkinson,stucki,riemersma, ...) passes every change on to neighbouring pixels, so anything that moves makes the stipple shimmer below and to the right of it. Atkinson shimmers least. Thetemporally_stablefield ofdith list algorithms --jsonsays which is which.boilgives a hand-drawn shimmer on purpose; set--boil-rate 2to animate "on twos".grainre-randomizes stipple every frame. - Seamless loops. Procedural patterns loop by construction. For sweeps, use
--sweep-mode pulseor--ping-pong. - Sweeps animate a parameter over time:
--sweep-bias,--sweep-brightness,--sweep-contrast,--sweep-gamma,--sweep-strength,--sweep-pixel-size, each writtenSTART..END. Shape them with--easing, and pause on keyframes with--hold-startand--hold-end. - Palette. One shared global palette is the default and keeps colors steady. Use
--per-frame-paletteonly for footage whose colors change a lot. - Timing. Frames are capped at 2..=240.
--duration Sis an alternative to--frames(frames = S × fps); passing both is an error. GIF delays are stored in 10 ms steps, so--fps 10|20|25|50gives exact GIF timing (15 fps becomes 70 ms per frame). APNG is exact. - Size. File size grows with frames × pixels, and dither noise barely compresses.
- GIFs are delta-encoded automatically: each frame after the first only stores what changed. Locked per-pixel algorithms with static areas are therefore far smaller than error diffusion or
boil/grain, where nearly every pixel changes each frame. - To hit a budget, pass
--max-size 2MB(also500KB,1.5MiB, or bytes). Dith shrinks the frame dimensions, keeping frame count and fps, until the file fits, and reportssize_fit_scale(1.0 = untouched). Ifsize_fit_scalecomes back small (under about 0.5), the result may be too small to use. Lower the size another way instead: fewer frames, a locked ordered algorithm, or fewer palette colors. - Keep procedural canvases modest (defaults are 480×360).
- GIFs are delta-encoded automatically: each frame after the first only stores what changed. Locked per-pixel algorithms with static areas are therefore far smaller than error diffusion or
- Procedural colors. Without
--stops, patterns use a plain near-black → near-white ramp. Pass--stopsto choose the source tones deliberately; it usually looks better, especially with a colored palette. - Presets on procedural sources. Presets are tuned for photos. For
generate,animate <pattern>, andcompare/preview --pattern, dith skips their auto-levels, contrast, and sharpen, because those clip clean gradients into flat patches. Pass those flags explicitly to apply them anyway.
Verify the result
Read the JSON report rather than assuming success:
"status": "ok".batchcan instead return"partial_failure"with exit code 1; checkfailedand eachitems[].error.output_dimensionsfor images, orframe_count,frame_dimensions, andtotal_duration_msfor animations, match the intent.bytes_written > 0; it is0on--dry-run.palette_colorsandcolor_usageare as expected. If one color covers more than about 95% of pixels, the image is nearly blank: adjust--bias,--gamma, or--contrast, or try--invert.
When aesthetics matter, look at the output. Open PNG files with an image-viewing tool if you have one; otherwise add --preview to get a Braille thumbnail in preview_braille. For animations, export a spritesheet or --frames-dir and view the PNG frames. For SVGs, render a PNG with the same flags and view that.
Errors
With --json, errors go to stderr as {"status":"error","code","message","suggestion","valid_values"?}.
- Exit 2: invalid input from you. Codes include
CLI_USAGE_ERROR,INVALID_ARGUMENT(an out-of-range value; the message includes the range),UNKNOWN_PRESETand similar codes (valid_valueslists the options), andOUTPUT_EXISTS(--no-clobberhit an existing file). Fix the flags and retry. - Exit 1: runtime or I/O failure (
RUNTIME_ERROR), such as a missing input or an undecodable file.batchalso exits 1 when any item fails.
Interactive vs headless
--view, preview (fullscreen by default), and compare --view are interactive Kitty-protocol viewers meant for a human at a terminal. In non-interactive agent shells, render to files, use --preview or --format braille, or pass --inline (for example dith preview img.png --inline --mode braille --cols 60). Only use the fullscreen viewer when the user explicitly wants to watch in their own terminal.
References
- references/cli.md: every subcommand and flag, with ranges, defaults, and JSON report fields.
- references/catalog.md: presets, palettes, algorithms, and generators, and when to choose each.
- references/recipes.md: copy-ready recipes for common jobs (web hero, avatar, logo SVG, social card, CSS spritesheet, reveal GIF, brand preset, batch export).