0xSero/ascii-art

What it does

ascii-art turns a source image into a dot map on a fixed tall-cell grid: a flat dark ground, two grey tones, and rare crimson accent dots used only on moving elements. From that map you build a scene and render a seamless animated loop in the browser — disintegration into dust, emerging forms, voids, tentacles — then export frames as PNG and encode them to MP4. The project packages the method, the rendering engine and the command-line scripts, and is aimed at people producing generative dot-lattice artwork rather than at image-to-ASCII text conversion.

The pipeline has three stages: image to dot map (text), dot map to still image or to a scene JSON, and scene JSON to a self-contained HTML page that exposes render(tt) for frame capture.

Quickstart

Prerequisites: Python 3.10+ with numpy, scipy, Pillow, scikit-image, Playwright with a Chromium build, and ffmpeg for encoding. Install with:

pip install numpy scipy pillow scikit-image playwright
python -m playwright install chromium

Then run the documented flow from the repository root:

# 1. image -> dot map: rows, then bright/mid percentiles of the subject's tones
python scripts/photo_dots.py photo.jpg map.txt 52 58 86

# 2. preview the still before animating
python scripts/render_map.py map.txt still 0.6

# 3. scene JSON -> animated HTML page
python scripts/build_scene.py examples/scenes/bust-dust.scene.json out.html

# 4. capture frames, then encode
python scripts/grab_frames.py out.html frames 30 12   # fps, seconds
ffmpeg -framerate 30 -i frames/f%04d.png -c:v libx264 -crf 16 -pix_fmt yuv420p \
       -movflags +faststart piece.mp4

scripts/grab_frames.py can write a contact sheet (grab_frames.py out.html sheet.png sheet) instead of the full frame set. Worked commands and tool signatures are in the README quickstart and the tool table.

Use constraints

• The bundled scene files under examples/scenes/ reference third-party photographs that are not shipped, so they document scene structure rather than running as-is. examples/bust-skull.map.txt is provided and is enough to build the figure layers (README examples).
• Rendering frames requires headed or headless Chromium via Playwright; the scripts are Python and shell oriented, with no GUI beyond the generated HTML page.
• The MIT license covers the code and text only. Images you process remain yours or their owner's; the repo grants no rights to them (license note).
• The look is deliberately constrained — fixed grid, flat near-black ground, two grey tones, crimson reserved for moving elements — so output follows those rules rather than being freely stylable.

Docs

• SKILL.md covers the craft: anatomy, step-by-step method, motion vocabulary, loop maths and a review checklist.
• references/engine.md documents the scene JSON format, layers and parameters.
• references/case-study.md walks through one finished piece, including each round of feedback.

HotRepo's take

ascii-art has no recorded GitHub all-language daily rank, but it appeared on HotRepo's new-project board: the 2026-11-01 all-language new list recorded 81 stars gained over a roughly 24-hour window from 2026-10-31T09:45Z to 2026-11-01T09:45Z, with 235 stars and 12 forks at the end. The hourly star samples over that period show steady growth from 100 to around 200 within the first 12 hours and then flattening to 235 by the final samples, which is consistent with a burst of early attention rather than sustained acceleration. The repository is JavaScript-flagged but is driven by Python scripts and a browser renderer, so readers should judge it by the workflow above rather than the language label.