User Instructions

rez2ans (a.k.a. rez2ansi) — User Docs from the ANSI trenches 😎💾

Welcome, scene traveler. rez2ans is a GUI tool for turning your PNG/JPG into 80xN CP437 goodness — exporting either:

• ANSI: .ans / .ansi (BBS-ready)
• TheDraw/PabloDraw BIN: .bin (classic editor format)

Think of it as: open image → drag crop → render → save → post on the board like a legend.

Heads-up: the build you’ve got literally identifies itself as “rez2ans v .01 Alpha”. So yeah… it’s a spicy alpha. Expect rough edges, but also vibes.

---

Quickstart (the “get on the wire NOW” path)

1. File → Open Image…
2. Drag a selection box on the image (this defines your 80xN crop target).
3. Pick your Mode, tweak the Gamma / Contrast / Saturation / Dither knobs.
4. Smash F12 (Render).
5. Save… (or Alt+S) → pick ANSI (.ans/.ansi) or BIN (.bin).

If you forget step 2, the app will basically bark: “Open an image, drag a box to crop, then Render.”

---

Keyboard shortcuts (because real ones don’t click menus)

F12 — Render current mode (main “make it happen” key)
Alt+S — Save (ANSI/BIN)
Alt+R — RESET EVERYTHING to factory defaults (panic button)

There’s also a legacy Tronicshade render path mentioned as F11 in the codebase, but your day-to-day muscle memory is F12.

---

The Layout (what you’re looking at)

At a high level you’ve got:

• Left: Source image + your selection box (crop)
• Right: Preview of the ANSI/BIN render (your future fame)
• Controls for:
  • Mode
  • Palette
  • Glyph set
  • Dithering
  • Image tuning (gamma/contrast/etc)
  • Shaders / patchbooks / Tronicshade (advanced wizardry)

You’ll also see status text like:

• Selection: (x,y) - (x,y) size=... px
• Loaded: ... | Output: 80 x N | BIN bytes: ...

---

Modes (choose your flavor of crunchy)

rez2ans ships with a bunch of render modes:

• hires — sharper detail, more “pixel decisions”
• shades — shade/block driven, classic chunky ANSI feel
• hybrid — mix of hires + shades (often a sweet spot)
• cartoon — bolder simplification (good for line art / flat art)
• colorbook — more stylized color treatment
• glyphfit — tries harder to “fit” characters to shapes/texture
• autoshader — leans into shader-assisted styling
• tronicshade — a texture/style pass that can feel “dither-like” but character-driven

Practical advice (scene-tested energy):

• Photos → start with hybrid
• Line art → try cartoon or shades
• Pixel art → jump to ANSI Art Mode (see below)
• Want stylized grit → tronicshade / autoshader

---

ANSI Art Mode (pixel art enjoyers, assemble)

There’s a dedicated ANSI Art Mode aimed at ANSI-ish glyph workflows like:

• ansiblocks
• ansiblocks-pixel
• “Load ANSI…” support (bring in an existing .ans / .ansi)

Also includes Glyph-only options:

• Glyph-only (characters only)
• Glyph-only (keep existing colors; change characters only)

That’s super handy if you’ve already got a palette pass you like and just want to re-char the piece.

---

“Color Hints” (teach it your palette like a wise sysop)

Hints bias palette matching so pastel/saturated colors don’t wash out.

The hint workflow

1. Drag a selection on the image (left panel)
2. Choose the ANSI color index you want it to be
3. Click “Add hint from selection”

There’s also a Dropper mode:

• Turn it on, then click the image preview to sample + create a hint.

Hint knobs you’ll see

• Hint tolerance (0..255) How close a pixel has to be before it counts as “this hinted color”.
• Hint strength How hard it pushes palette matching toward that ANSI color.
• Options like:
  • Use hints to build a temporary palette (VGAPAL)
  • Refit hinted palette each pass (gentle)
  • Post-fix colors using hints (final pass) (snaps FG/BG to hinted index if very close)

When to use hints:

• Skin tones turning into swamp green
• Pastels getting murdered by the nearest ANSI neighbor
• Logos needing exact brand-ish colors in the 16-color prison

---

ANSIrez Mode (cleanup pass for less speckle, more “finished”)

ANSIrez Mode applies a post-quantization smoothing pass:

• Filters: median, blend, brite, 4x4
• Useful for: reducing pepper-noise, thickening thin lines a bit
• Tradeoff: may soften detail (worth it often)

Suggested starting knobs:

• Brightness: 0.90–1.10
• Gamma: 0.95–1.05
• Contrast: 1.10–1.25
• Saturation: 0.90–1.10

If your render looks like it got faxed through a toaster, back off contrast and try median.

---

Shaders, TronicShade styles, and Patchbooks (the black belt stuff)

Shader import (BIN/ANS)

You can Import shader (BIN/ANS)… and/or Use shader BIN (curated FG/BG ramps).

You’ll see status like:

• Shader: swatches=... pairs=... glyphPairs=... file=...

There’s also:

• “Shader rows to read (top N rows)” Useful if your shader file has multiple rows of swatches and you only want the top chunk.

Patchbook (learned style transfer)

Patchbooks are like a stash of learned glyph/color pair vibes.

You can:

• Load patchbook…
• Save patchbook…
• Clear patchbook

You may see:

• Patchbook: learned from import
• Or the app yelling: “Patchbook is empty. Import shader files first.”

Tronicshade styles

Tronicshade has its own style files:

• Load a TronicShade/Shader style profile from the styles folder
• Save as: *.tronic.json / *.tronic

It can also:

• Load ANSI into Tronicshade library (shade-only)

If you’re chasing a consistent “house look” across a pack, Tronicshade styles + patchbooks are your repeatability weapons.

---

Export options (BBS hygiene: SAUCE, iCE, line endings)

When saving ANSI, you’ll typically have options like:

Formatting / compatibility

• Trim trailing spaces (keeps lines from having pointless default cells)
• ClearScreenHome (adds the classic ESC[2J + ESC[H at the start)
• Line endings:
  • CRLF (Windows)
  • CR
  • LF

SAUCE metadata (for the collectors and archivists)

• Add SAUCE metadata
• Title / Author / Group
• Optional source comment (writes a comment like SOURCE: )
• Set iCE colors flag in SAUCE (bit0) (Use this if you intend iCE behavior and want viewers to know.)

Convenience

• Copy source image beside ANSI file as *_source. Great for showing “before/after” in release zips.

---

Common workflows (pick your mission)

1) Photo → ANSI poster

• Mode: hybrid
• Dither: moderate
• Contrast: 1.10–1.20
• Optional: ANSIrez median to reduce speckle

2) Pixel art → clean blocks

• ANSI Art Mode
• Try ansiblocks-pixel
• If colors are sacred: Glyph-only (keep existing colors)

3) “Make it look like that pack”

• Import shader BIN/ANS
• Let it learn patchbook
• Save patchbook + Tronicshade style
• Apply consistently across your set

---

Troubleshooting (aka “why does it hate me?”)

• “Open an image first.” You didn’t load an image.
• Render looks wrong / off-color Add Color Hints for the problem colors (logos/pastels).
• Too noisy Reduce dither strength, or enable ANSIrez (median/blend).
• Patchbook won’t save / is empty Import shader files first so it has something to learn from.
• Need maximum compatibility Enable Clear screen + home, use CRLF, and add SAUCE.

---

The vibe checklist ✅

Before you ship it to the BBS:

[ ] It’s 80 columns wide (always)
[ ] You’ve previewed it in something real (PabloDraw/TheDraw/SyncTerm/etc.)
[ ] SAUCE is set (Title/Author/Group) for proper cred
[ ] If it uses iCE tricks, you set the iCE flag
[ ] You didn’t accidentally Alt+R and nuke your perfect settings (RIP)