dither

Image in, terminal splash script out. render/<name>/show.sh renders truecolor Unicode quadrant-block art, auto-sized to the caller's terminal. Stdlib bash at runtime — no dependencies beyond bash 4+ and stty. Generation needs numpy + pillow.

Quick start

git clone git@github.com:TGPSKI/dither.git
cd dither
make venv
make check
render/cadillac/show.sh

make new NAME=myimage SRC=some-source.png
make render NAME=myimage CAPTION="optional caption"
render/myimage/show.sh

Shipped example

render/cadillac/ — a '67 Cadillac lowrider, front three-quarter, shown as a hero splash before a TUI launches. The only render this repo ships; everything else under render/ is gitignored (make new scaffolds local-only renders).

Layout

src/                        generation scripts: convert, quadrant, embed, inspect, ansi-to-png
render/cadillac/             the shipped example: target.png, frames/, captures/, show.sh
tests/                       unit tests for the deterministic pipeline logic
.agents/skills/splash-ascii-render/   the generation workflow as an agent skill

AGENTS.md has the full directory map and the rules three prior bugs paid for.

State

v0.1.0, 2026-08-15. Three rendering generations shipped in one session — single-glyph, half-block, quadrant-block — plus the bug pass each one forced. CHANGELOG.md has the version log; LINEAGE.md has the timeline and what each generation's bug taught the next one.

Verify

make check   # unit tests + smoke test of render/cadillac/show.sh
make lint    # ruff

src/ansi_to_png.py rasterizes a captured ANSI stream to PNG — how every rendering claim in this repo's history was actually checked, not assumed from reading escape codes.

Docs

AGENTS.md · CHANGELOG.md · LINEAGE.md · splash-ascii-render skill

License

GPL-3.0 — see LICENSE.