Community이미지github.com

dith

dith CLI를 사용하여 사진과 로고를 디더링하고, 절차적 텍스처를 생성하며, 재사용 가능한 레시피에서 레트로 또는 인쇄용 애니메이션을 내보냅니다.

dith란 무엇인가요?

dith는 에이전트를 위해 설계된 결정론적 디더링 CLI 도구입니다. 모든 명령어는 `--json` 플래그를 지원하며, 팔레트에 정확한 출력을 생성하고 기계 판독 가능한 보고서를 반환합니다. 동일한 입력과 플래그는 항상 바이트 단위로 동일한 파일을 생성하므로 완벽한 재현성을 보장합니다. 개발자, 디자이너 및 AI 에이전트는 dith를 사용하여 사진, 로고, 아이콘 등에 대해 Mac 클래식, 편집 인쇄, 필름 스티플, 리소그래프, 게임보이, CRT, 목판화, 청사진 등 다양한 스타일을 적용할 수 있습니다. 이 도구는 PNG, WebP, SVG 및 애니메이션 GIF와 같은 여러 출력 형식을 지원하며, 접촉 시트 생성, 드라이 런 검증, 레시피 내보내기 등을 통해 반복 가능한 워크플로우를 제공합니다. dith는 색 공간 관리, 선명도, 감마 보정, 대비 조정, 투명도 처리 및 패턴 스케일링을 위한 다양한 크래프트 규칙을 제공하여 정밀한 제어가 가능합니다. CLI 에이전트, CI/CD 파이프라인 및 배치 처리 시나리오에 이상적입니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lassejlv/dith/tree/HEAD/skills/dith

Installed? Explore more 이미지 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

dith은(는) 무엇을 하나요?

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

  1. Check for the binary with dith --version.
    • Inside the dith source checkout without a global install, run it via cargo run --release -- <args> (or mbx run -- <args> when mbx is available).
    • If dith is missing, tell the user and offer an install command from references/cli.md. Wait for their approval before installing anything.
  2. 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 capabilities for the full manifest of commands, parameter ranges, and the default recipe (about 40 KB, so prefer list when one catalog is enough)

Core workflow

  1. 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.
  2. 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
  3. Validate complex flag sets first with --dry-run --json. This catches bad values and shows planned output_dimensions without writing files.
  4. Render with apply, generate, animate, or batch, always with --json. Single-file commands overwrite existing outputs by default. Add --no-clobber when existing files must not be touched; in batch it applies to each file.
  5. Verify before reporting success. See Verify the result.
  6. Make it reproducible when the look will be reused. Pass --emit-recipe (adds a recipe object 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.

GoalStart withNotes
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-duoDuotone and two-drum overprint looks on warm paper.
Comic / zine halftone--preset halftone-zinePair with --format svg --svg-shape circle for vector dots.
Game Boy / pixel art--preset gameboy, pico8Ordered Bayer plus chunky --pixel-size.
CRT / terminal glow--preset crt-amber, phosphorDark-key images suit these best.
Engraving / woodcut--preset woodcut, --algorithm crosshatchLine screens; tune with --pattern-scale.
Blueprint / technical--preset blueprintPrussian blue and chalk duotone.
Keep the photo's own colors--preset lo-fi-photo or --auto-palette NExtracts 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-levels or --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).
  • Size first. Cap with --max-dim (or --width/--height plus --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 N downsamples, dithers, then nearest-upscales, so output dimensions are unchanged.
  • Ordered screen size. --pattern-scale 2..4 enlarges Bayer, halftone, line, and blue-noise cells for bolder, more graphic texture.
  • Color space. Keep the default oklab. Use srgb only to mimic legacy hardware math; linear is physically linear light.
  • Determinism. Stochastic algorithms (blue-noise, random, ign), --noise, and --auto-palette use --seed (default 42). Change the seed for variations and keep it fixed for reproducibility.
  • Transparency. Logos and icons with alpha: --alpha-mode preserve keeps the alpha channel, threshold gives a crisp 1-bit mask, dither gives a stippled fade, and flatten --background "#hex" composites onto a color.
  • Turning off preset parts. Most monochrome presets turn on --grayscale and --auto-levels. Use --no-grayscale, --no-auto-levels, and --no-serpentine to 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), or dot (inset dots). --svg-skip-bg drops the dominant background color for overlays. SVG grows with pixel count, and circles are much larger than rects, so keep --max-dim around 120–320.
  • Terminal text: --format braille|ascii with --text-width N. -o is 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); the motion field of dith list generators --json describes 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 boil is 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, and threshold. 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. The temporally_stable field of dith list algorithms --json says which is which. boil gives a hand-drawn shimmer on purpose; set --boil-rate 2 to animate "on twos". grain re-randomizes stipple every frame.
  • Seamless loops. Procedural patterns loop by construction. For sweeps, use --sweep-mode pulse or --ping-pong.
  • Sweeps animate a parameter over time: --sweep-bias, --sweep-brightness, --sweep-contrast, --sweep-gamma, --sweep-strength, --sweep-pixel-size, each written START..END. Shape them with --easing, and pause on keyframes with --hold-start and --hold-end.
  • Palette. One shared global palette is the default and keeps colors steady. Use --per-frame-palette only for footage whose colors change a lot.
  • Timing. Frames are capped at 2..=240. --duration S is 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|50 gives 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 (also 500KB, 1.5MiB, or bytes). Dith shrinks the frame dimensions, keeping frame count and fps, until the file fits, and reports size_fit_scale (1.0 = untouched). If size_fit_scale comes 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).
  • Procedural colors. Without --stops, patterns use a plain near-black → near-white ramp. Pass --stops to 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>, and compare/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". batch can instead return "partial_failure" with exit code 1; check failed and each items[].error.
  • output_dimensions for images, or frame_count, frame_dimensions, and total_duration_ms for animations, match the intent.
  • bytes_written > 0; it is 0 on --dry-run.
  • palette_colors and color_usage are 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_PRESET and similar codes (valid_values lists the options), and OUTPUT_EXISTS (--no-clobber hit 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. batch also 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).

관련 스킬