How plntrprotocol/risomorphism-1911 works
1. Repository purpose
- ascii_pipeline is a pure-Python rendering foundation for turning images and video into ASCII-art text outputs and Herm-style .eikon artifacts.
- The architecture is centered on a small rendering core plus several CLI-facing workflows: still-image conversion, preview generation, diagnostics, and animated eikon assembly.
2. Primary package boundary
- The production code lives in the ascii_pipeline/ package.
- cli.py is the user-facing orchestration layer.
- converter.py, downsampling.py, image_modes.py, video_modes.py, eikon.py, preview.py, diagnostics.py, and presets.py form the functional core beneath the CLI.
- This separation matters: the CLI coordinates work, while the core modules implement the rendering and analysis logic.
3. Still-image rendering flow
- The main still-image path is: source image → preprocessing/scaling → mode-specific conversion → ASCII grid → .txt output.
- converter.py appears to be the central transformation engine, with image_modes.py defining how different character families or rendering strategies are applied.
- presets.py binds a named preset like stroke-clarity, d30-dense, or braille-detail to the correct backend, target grid, and intermediate processing behavior.
4. Rendering modes and their boundary
- The repo clearly distinguishes between direct text-grid rendering and higher-fidelity block/bitmap-style reduction.
- downsampling.py handles the resolution reduction logic that underpins dense/block modes.
- image_modes.py likely contains the glyph-selection and mapping rules for still images.
- video_modes.py provides the analogous logic for motion content, especially for the eikon-motion preset.
5. Resolution and scaling model
- The project uses a fixed base grid of 48×24 and scales it by integer factors up to 16.
- That scaling policy is an architectural constraint: it affects the final output grid, any intermediate grid, and the source-image sampling scale.
- Some presets are direct-path and scale efficiently, while block-mode presets expand an intermediate grid and therefore become much more memory-intensive at high scale factors.
6. Animated eikon pipeline
- eikon.py is the artifact boundary for the animated format.
- The build-eikon CLI path assembles a sequence of PNG frames into a .eikon file, optionally with a secondary collapse grid for deployment-sized output.
- The repo’s example assets show that animated eikons are treated as a distinct publication format, not just a sequence of text frames.
7. Preview and human QA path
- preview.py supports side-by-side PNG previews for validating the rendered text against the source image or frame.
- This is a quality-assurance boundary: the canonical output is text or .eikon, but preview images are generated for visual verification.
- The README’s emphasis on --preview-out shows that visual confirmation is part of the intended workflow, not optional tooling.
8. Diagnostics and quality gates
- diagnostics.py analyzes rendered .txt or .eikon outputs and produces JSON metrics.
- The diagnostics subsystem measures things like unique glyph count, fill ratio, heavy/light character distribution, Braille usage, and motion deltas for video.
- This is a separate analytical lane from rendering: it does not create art, it assesses whether the generated output matches the expected fidelity profile.
9. Preset catalog as architectural contract
- presets.py is the contract layer that encodes the canonical presets and their intended usage.
- The presets define meaningful boundaries between visual goals: high-contrast silhouettes, dense D30-style texture, Braille-detail rendering, and motion-oriented eikon generation.
- This keeps rendering behavior reproducible and makes the CLI behavior largely declarative rather than ad hoc.
10. Command-line surface
- cli.py exposes four core commands: list presets, diagnose outputs, render previews, render images, and build eikons.
- The CLI is the main integration point for all other modules and is the boundary where filesystem I/O happens.
- It supports both image-to-text and frame-directory-to-eikon workflows, which are the two main data flows in the repo.
11. Repository artifacts and examples
- examples/ contains curated inputs and expected outputs for still-image, portrait, dense-field, and animated-cosmic-pyramid scenarios.
- The preset-renders/ directories act as reference outputs for multiple presets and scales, which makes the repository useful as a visual regression and documentation corpus.
- gallery/ is a static HTML presentation layer for comparing outputs; it is downstream of the pipeline, not part of the core renderer.
12. Testing and canonicalization
- tests/ covers the CLI, diagnostics, and presets, indicating that the main behavioral boundaries are command behavior, metric computation, and preset contracts.
- docs/canonical-foundation.md and the top-level README establish frozen baseline decisions, so the architecture is intentionally stable and opinionated.
- SKILL.md suggests a dual publication model, but the core architecture remains the same: pure-Python rendering plus packaged CLI entry points.
13. External technology footprint
- The only materially important runtime dependencies called out are Python 3.11+, Pillow, and NumPy.
- Architecturally, that means the project is self-contained: no external rendering binaries are required, and the pipeline is designed to be deterministic and portable.
14. How to draw the system
- A good diagram would show three main lanes:
- Input lane: image files or frame directories
- Core processing lane: presets → conversion/downsampling/mode logic → text grid or .eikon
- Output/validation lane: .txt, .eikon, preview PNGs, and diagnostics JSON
- Around those lanes, place the static example/gallery assets and the test/docs layer as supporting, non-runtime subsystems.
Main entry points: presets.py Presets · cli.py CLI · converter.py Converter · eikon.py Eikon
Components 17
Core pipeline
Production rendering and analysis modules in the ascii_pipeline package.
- Converter · Central image-to-grid transformation engine for still rendering flows.
ascii_pipeline/converter.py - Downsampling · Reduces source imagery into the grid scales used by dense and block-oriented modes.
ascii_pipeline/downsampling.py - Image modes · Defines still-image rendering strategies and character-family mapping rules.
ascii_pipeline/image_modes.py - Video modes · Defines motion-oriented rendering strategies for animated content.
ascii_pipeline/video_modes.py - Presets · Named rendering contracts that bind mode, scale, and processing behavior.
ascii_pipeline/presets.py - Eikon · Assembly and representation boundary for animated .eikon outputs.
ascii_pipeline/eikon.py - Preview · Generates side-by-side visual previews for checking rendered output against source media.
ascii_pipeline/preview.py - Diagnostics · Analyzes rendered text or eikon outputs and emits fidelity metrics in JSON form.
ascii_pipeline/diagnostics.py
CLI boundary
User-facing orchestration and command entry points.
- CLI · Top-level command interface that dispatches rendering, preview, diagnostics, and eikon assembly.
ascii_pipeline/cli.py
Reference assets
Curated examples, gallery output, and sample artifacts.
- Portrait · Reference inputs and preset renders for portrait-style still-image outputs.
examples/portrait - Dense field · Reference inputs and preset renders for dense and Braille-heavy still-image outputs.
examples/dense-field - Cosmic scene · Reference inputs and preset renders for larger-scale scene conversions.
examples/scene-cosmic-pyramid - Animated eikon · Reference media, emitted .eikon artifacts, and player pages for animated output.
examples/animated-eikon - Gallery · Static HTML presentation layer for comparing rendered outputs.
gallery
Quality layer
Tests and documentation that define and verify stable behavior.
- Tests · Behavioral checks for CLI behavior, diagnostics metrics, and preset contracts.
tests - Canonical docs · Documentation that captures the frozen architectural baseline and usage assumptions.
docs/canonical-foundation.md - README · Primary repository overview and workflow documentation.
README.md
Connections 25
- CLI → Presets: selects · CLI resolves the requested named preset before running a workflow.
- CLI → Converter: runs · CLI drives still-image conversion through the core transformation engine.
- CLI → Preview: renders · CLI can produce preview images for human validation.
- CLI → Diagnostics: analyzes · CLI exposes diagnostics for rendered outputs.
- CLI → Eikon: builds · CLI assembles animated .eikon artifacts from frame inputs.
- Converter → Downsampling: uses · Conversion relies on resolution reduction for scale and dense modes.
- Converter → Image modes: applies · Conversion delegates glyph selection and still-image strategy to mode definitions.
- Converter → Presets: configured by · Presets provide the converter with the intended backend and scaling behavior.
- Image modes → Downsampling: combines · Some image modes depend on downsampling to express block or dense rendering.
- Presets → Video modes: includes · Motion-oriented presets bind to video-mode behavior for animated rendering.
- Video modes → Eikon: feeds · Video-mode output is packaged into animated eikon artifacts.
- Eikon → Preview: previewed by · Animated artifacts can be rendered into preview imagery for QA.
- Diagnostics → Presets: benchmarks · Diagnostics provide a way to assess preset outputs against expected fidelity profiles.
- Portrait → Presets: demonstrates · Example renders document how presets behave on portrait inputs.
- Dense field → Presets: demonstrates · Example renders document dense-field behavior across presets and scales.
- Cosmic scene → Presets: demonstrates · Example renders document large-scene behavior across presets and scales.
- Animated eikon → Eikon: shows · Animated examples illustrate the .eikon publication format and playback variants.
- Animated eikon → Video modes: demonstrates · Animated examples exercise motion-specific rendering behavior.
- Gallery → Portrait: showcases · Gallery content is downstream of example renders.
- Gallery → Dense field: showcases · Gallery content is downstream of example renders.
- Gallery → Cosmic scene: showcases · Gallery content is downstream of example renders.
- Tests → CLI: covers · Tests verify command behavior and integration points exposed by the CLI.
- Tests → Diagnostics: covers · Tests verify metrics and output analysis behavior.
- Tests → Presets: covers · Tests verify the preset catalog as an architectural contract.
- Canonical docs → README: reinforces · Design documentation and README establish the repo's frozen baseline.