Riso

RISO — Risomorphism-1911 ASCII Pipeline

Package: ascii-art-pipeline (installed at ~/riso/) CLI: ascii-pipeline Base grid: 48×24 (Herm avatar default)

Pure-Python ASCII rendering with edge-aware downsampling, four curated presets, and automatic quality verdicts. No external binaries required. See references/preprocessing.md for the session-specific image preprocessing patterns.

Preset Quick Reference

When to use what

Preprocessing for Clean Backgrounds

CRITICAL: The pipeline maps pure black (0,0,0) to @ (the darkest character), NOT to spaces. The converter at converter.py:_map_intensity maps pixel brightness 0–255 linearly to charset indices with floor(pixels * n). Black → index 0 → @. There is no special handling for black-as-background.

If you send an image with a black background, the output fills with @, $, # — the background looks like solid dense character fill, not empty space.

Fix: set background to white (255) before running through the pipeline. White maps to the lightest characters (. / , / ;) which are visually near-invisible. The autocontrast preprocess then stretches the character's contrast range independently, so the subject stays crisp.

Preprocessing Workflow for Subject Isolation

1. Crop tight to the subject — remove background at the image level first
2. Analyze brightness histogram — find the valley between background peak and subject peak
3. Threshold — create a boolean mask with the threshold set at that valley:

   gray = np.mean(arr, axis=2)
   mask = gray > threshold  # True = subject, False = background
   

4. Set background to white — replace background pixels with (255,255,255):

   result = np.full_like(arr, 255)  # all white
   for c in range(3):
       result[:,:,c] = np.where(mask, arr[:,:,c], 255)
   

5. Median filter — smooth mask boundary artifacts:

   Image.fromarray(result).filter(ImageFilter.MedianFilter(3))
   

6. Run through pipeline — stroke-clarity at scale 2 (96×48) is a good starting point for portraits

Quality Check

After rendering, inspect fill_ratio in the diagnostics JSON:

• 0.65–0.75: clean result — ~25–35% background rendered as space
• ~1.0: background wasn't removed — redo the threshold with a higher value
• Heavy ratio > 0.50 with fill near 1.0: likely @/$/# background fill, not character

Commands

Render a still image

ascii-pipeline render-image \
  --input <image> \
  --preset <preset> \
  --out <output.txt> \
  [--preview-out preview.png] \
  [--diagnostics-out metrics.json] \
  [--scale N]           # default 1, range 1–16
  [--fullsize]          # alias for --scale 4 (192×96)

Workflow:

1. Preprocess image if background needs isolation (see above)
2. Run with --diagnostics-out to get quality verdict
3. Check verdict: high-contrast → ship; low-contrast-garble-risk → increase scale or switch preset
4. Use --preview-out for side-by-side visual QA

Diagnose an existing file

ascii-pipeline diagnose --input <file.txt> --pretty

Checks dimensions, glyph diversity, fill ratio, heavy/light balance. Verdict is authoritative.

Render preview from text/eikon

ascii-pipeline render-preview --input <file.txt> --out preview.png

Build animated eikon from video (mirror workflow)

ascii-pipeline build-eikon-from-video \
  --video <input.mp4> \
  --fps 24 \
  --states 3 \
  --id <eikon-name> \
  [--grid 192x96] \
  [--charset d30-dense]

Outputs: <id>.eikon + <id>-player.html (offline HTML5 canvas player).

Workflow for mirror deployment:

1. Use build-eikon-from-video with source video
2. Output .eikon file can be served to the mirror
3. HTML player is self-contained (base64-encoded, no server needed)

Scaling Guide

Performance: d30-dense at scale ≥8 is slow and memory-heavy (up to 4GB at N=16). stroke-clarity stays fast at all scales (0.3s at N=16). Prefer stroke-clarity for quick previews, then switch to d30-dense for the final render.

Quality Gates

Always run --diagnostics-out before shipping to mirror or avatar. Don't ship low-contrast-garble-risk.

Integration with Other Skills

• ascii-art skill — Use riso instead of jp2a/ascii-image-converter when you want quality-gated output with preset control. The ascii-art skill handles text banners, cowsay, and borders — this handles high-fidelity image → ASCII.
• ascii-video skill — riso's build-eikon-from-video is a lighter alternative to the full ascii-video pipeline when you just need an animated eikon for the mirror (no scene composition, shaders, or audio reactivity needed).
• animated-eikon-from-base skill — Upstream pipeline that generates real animated video clips (idle/listening/thinking/speaking/working/error) from a single base image via fal.ai/Kling. Once you have the MP4s, either feed them through riso's build-eikon-from-video for ASCII eikon conversion, or install them directly into Herm Studio source at ~/.hermes/eikons/<name>/source/ for native rendering. riso handles ASCII/braille eikons; animated-eikon-from-base handles real video eikons — complementary, not competing.
• animated-eikon-from-base skill — Use this upstream to generate animated video clips from a single base image via fal.ai/Kling (idle/listening/thinking/speaking/working/error). Once you have those MP4s, feed them into riso's build-eikon-from-video for ASCII eikon conversion, or install them directly into Herm Studio's source folder (~/.hermes/eikons/<name>/source/) for native rendering.

Pitfalls

• Black background → @ fill, NOT spaces — The core converter maps black (0) → index 0 → @. If the output is @-dense with fill_ratio ~1.0, the background is pure black. Set it to white (255) instead. This is the #1 gotcha.
• d30-dense at scale ≥8 can memory-spike — intermediate grid goes to 6144×3072 at N=16. Use stroke-clarity at N=16 instead.
• stroke-clarity beats d30-dense for portraits — The 12-glyph charset produces cleaner face silhouettes. d30-dense with 68 glyphs adds texture noise that obscures facial features at scale ≤2.
• Edge-aware downsampling is automatic for d30-dense at scale ≥8 — don't try to override it, it's wired into the preset.
• braille-detail needs a Braille-capable terminal — standard terminals don't render U+2800+ well. Use for file output / preview PNG, not terminal display.
• Eikon videos require source MP4 to be high-contrast, well-lit, minimal motion blur — the ASCII pipeline amplifies noise.
• Clean up temp frames after build-eikon-from-video: rm -rf tmp/ in the working directory.