# plntrprotocol/risomorphism-1911 architecture

> Architecture diagram of the GitHub repository plntrprotocol/risomorphism-1911, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/plntrprotocol/risomorphism-1911
- Repository: https://github.com/plntrprotocol/risomorphism-1911

## Overview

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: [`ascii_pipeline/presets.py`](https://github.com/plntrprotocol/risomorphism-1911/blob/main/ascii_pipeline/presets.py) (Presets), [`ascii_pipeline/cli.py`](https://github.com/plntrprotocol/risomorphism-1911/blob/main/ascii_pipeline/cli.py) (CLI), [`ascii_pipeline/converter.py`](https://github.com/plntrprotocol/risomorphism-1911/blob/main/ascii_pipeline/converter.py) (Converter), [`ascii_pipeline/eikon.py`](https://github.com/plntrprotocol/risomorphism-1911/blob/main/ascii_pipeline/eikon.py) (Eikon)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_core["Core pipeline"]
  node_n_converter["Converter<br/>transform core<br/>[converter.py]"]
  node_n_downsampling["Downsampling<br/>resolution stage<br/>[downsampling.py]"]
  node_n_image_modes["Image modes<br/>glyph mapping<br/>[image_modes.py]"]
  node_n_video_modes["Video modes<br/>motion mapping<br/>[video_modes.py]"]
  node_n_presets["Presets<br/>preset catalog<br/>[presets.py]"]
  node_n_eikon["Eikon<br/>artifact format<br/>[eikon.py]"]
  node_n_preview["Preview<br/>qa renderer<br/>[preview.py]"]
  node_n_diagnostics["Diagnostics<br/>metrics<br/>[diagnostics.py]"]
end

subgraph group_grp_cli["CLI boundary"]
  node_n_cli["CLI<br/>orchestrator<br/>[cli.py]"]
end

subgraph group_grp_assets["Reference assets"]
  node_n_examples_portrait["Portrait<br/>example set"]
  node_n_examples_dense["Dense field<br/>example set"]
  node_n_examples_scene["Cosmic scene<br/>example set"]
  node_n_examples_animated["Animated eikon<br/>example set"]
  node_n_gallery["Gallery<br/>static showcase"]
end

subgraph group_grp_quality["Quality layer"]
  node_n_tests["Tests<br/>verification"]
  node_n_docs["Canonical docs<br/>design baseline"]
  node_n_readme["README<br/>project guide<br/>[README.md]"]
end

node_n_cli -->|"selects"| node_n_presets
node_n_cli -->|"runs"| node_n_converter
node_n_cli -->|"renders"| node_n_preview
node_n_cli -->|"analyzes"| node_n_diagnostics
node_n_cli -->|"builds"| node_n_eikon
node_n_converter -->|"uses"| node_n_downsampling
node_n_converter -->|"applies"| node_n_image_modes
node_n_converter -->|"configured by"| node_n_presets
node_n_image_modes -->|"combines"| node_n_downsampling
node_n_presets -->|"includes"| node_n_video_modes
node_n_video_modes -->|"feeds"| node_n_eikon
node_n_eikon -->|"previewed by"| node_n_preview
node_n_diagnostics -->|"benchmarks"| node_n_presets
node_n_examples_portrait -->|"demonstrates"| node_n_presets
node_n_examples_dense -->|"demonstrates"| node_n_presets
node_n_examples_scene -->|"demonstrates"| node_n_presets
node_n_examples_animated -->|"shows"| node_n_eikon
node_n_examples_animated -->|"demonstrates"| node_n_video_modes
node_n_gallery -->|"showcases"| node_n_examples_portrait
node_n_gallery -->|"showcases"| node_n_examples_dense
node_n_gallery -->|"showcases"| node_n_examples_scene
node_n_tests -->|"covers"| node_n_cli
node_n_tests -->|"covers"| node_n_diagnostics
node_n_tests -->|"covers"| node_n_presets
node_n_docs -->|"reinforces"| node_n_readme

click node_n_cli "https://github.com/plntrprotocol/risomorphism-1911/blob/main/ascii_pipeline/cli.py"
click node_n_converter "https://github.com/plntrprotocol/risomorphism-1911/blob/main/ascii_pipeline/converter.py"
click node_n_downsampling "https://github.com/plntrprotocol/risomorphism-1911/blob/main/ascii_pipeline/downsampling.py"
click node_n_image_modes "https://github.com/plntrprotocol/risomorphism-1911/blob/main/ascii_pipeline/image_modes.py"
click node_n_video_modes "https://github.com/plntrprotocol/risomorphism-1911/blob/main/ascii_pipeline/video_modes.py"
click node_n_presets "https://github.com/plntrprotocol/risomorphism-1911/blob/main/ascii_pipeline/presets.py"
click node_n_eikon "https://github.com/plntrprotocol/risomorphism-1911/blob/main/ascii_pipeline/eikon.py"
click node_n_preview "https://github.com/plntrprotocol/risomorphism-1911/blob/main/ascii_pipeline/preview.py"
click node_n_diagnostics "https://github.com/plntrprotocol/risomorphism-1911/blob/main/ascii_pipeline/diagnostics.py"
click node_n_examples_portrait "https://github.com/plntrprotocol/risomorphism-1911/tree/main/examples/portrait"
click node_n_examples_dense "https://github.com/plntrprotocol/risomorphism-1911/tree/main/examples/dense-field"
click node_n_examples_scene "https://github.com/plntrprotocol/risomorphism-1911/tree/main/examples/scene-cosmic-pyramid"
click node_n_examples_animated "https://github.com/plntrprotocol/risomorphism-1911/tree/main/examples/animated-eikon"
click node_n_gallery "https://github.com/plntrprotocol/risomorphism-1911/tree/main/gallery"
click node_n_tests "https://github.com/plntrprotocol/risomorphism-1911/tree/main/tests"
click node_n_docs "https://github.com/plntrprotocol/risomorphism-1911/blob/main/docs/canonical-foundation.md"
click node_n_readme "https://github.com/plntrprotocol/risomorphism-1911/blob/main/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_converter,node_n_downsampling,node_n_image_modes,node_n_video_modes,node_n_presets,node_n_eikon,node_n_preview,node_n_diagnostics toneBlue
class node_n_cli toneAmber
class node_n_examples_portrait,node_n_examples_dense,node_n_examples_scene,node_n_examples_animated,node_n_gallery toneMint
class node_n_tests,node_n_docs,node_n_readme toneRose
```

## Components

### Core pipeline

Production rendering and analysis modules in the ascii_pipeline package.

- [Converter](https://github.com/plntrprotocol/risomorphism-1911/blob/main/ascii_pipeline/converter.py): transform core · Central image-to-grid transformation engine for still rendering flows. · `ascii_pipeline/converter.py`
- [Downsampling](https://github.com/plntrprotocol/risomorphism-1911/blob/main/ascii_pipeline/downsampling.py): resolution stage · Reduces source imagery into the grid scales used by dense and block-oriented modes. · `ascii_pipeline/downsampling.py`
- [Image modes](https://github.com/plntrprotocol/risomorphism-1911/blob/main/ascii_pipeline/image_modes.py): glyph mapping · Defines still-image rendering strategies and character-family mapping rules. · `ascii_pipeline/image_modes.py`
- [Video modes](https://github.com/plntrprotocol/risomorphism-1911/blob/main/ascii_pipeline/video_modes.py): motion mapping · Defines motion-oriented rendering strategies for animated content. · `ascii_pipeline/video_modes.py`
- [Presets](https://github.com/plntrprotocol/risomorphism-1911/blob/main/ascii_pipeline/presets.py): preset catalog · Named rendering contracts that bind mode, scale, and processing behavior. · `ascii_pipeline/presets.py`
- [Eikon](https://github.com/plntrprotocol/risomorphism-1911/blob/main/ascii_pipeline/eikon.py): artifact format · Assembly and representation boundary for animated .eikon outputs. · `ascii_pipeline/eikon.py`
- [Preview](https://github.com/plntrprotocol/risomorphism-1911/blob/main/ascii_pipeline/preview.py): qa renderer · Generates side-by-side visual previews for checking rendered output against source media. · `ascii_pipeline/preview.py`
- [Diagnostics](https://github.com/plntrprotocol/risomorphism-1911/blob/main/ascii_pipeline/diagnostics.py): metrics · 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](https://github.com/plntrprotocol/risomorphism-1911/blob/main/ascii_pipeline/cli.py): orchestrator · 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](https://github.com/plntrprotocol/risomorphism-1911/tree/main/examples/portrait): example set · Reference inputs and preset renders for portrait-style still-image outputs. · `examples/portrait`
- [Dense field](https://github.com/plntrprotocol/risomorphism-1911/tree/main/examples/dense-field): example set · Reference inputs and preset renders for dense and Braille-heavy still-image outputs. · `examples/dense-field`
- [Cosmic scene](https://github.com/plntrprotocol/risomorphism-1911/tree/main/examples/scene-cosmic-pyramid): example set · Reference inputs and preset renders for larger-scale scene conversions. · `examples/scene-cosmic-pyramid`
- [Animated eikon](https://github.com/plntrprotocol/risomorphism-1911/tree/main/examples/animated-eikon): example set · Reference media, emitted .eikon artifacts, and player pages for animated output. · `examples/animated-eikon`
- [Gallery](https://github.com/plntrprotocol/risomorphism-1911/tree/main/gallery): static showcase · Static HTML presentation layer for comparing rendered outputs. · `gallery`

### Quality layer

Tests and documentation that define and verify stable behavior.

- [Tests](https://github.com/plntrprotocol/risomorphism-1911/tree/main/tests): verification · Behavioral checks for CLI behavior, diagnostics metrics, and preset contracts. · `tests`
- [Canonical docs](https://github.com/plntrprotocol/risomorphism-1911/blob/main/docs/canonical-foundation.md): design baseline · Documentation that captures the frozen architectural baseline and usage assumptions. · `docs/canonical-foundation.md`
- [README](https://github.com/plntrprotocol/risomorphism-1911/blob/main/README.md): project guide · Primary repository overview and workflow documentation. · `README.md`

## Connections

- 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.
