# termimg

Picture-perfect image rendering in the native terminal. The library takes raw
RGBA pixel data and reproduces it using the highest-fidelity protocol the
terminal supports, falling back through progressively coarser Unicode block
characters when graphics protocols are unavailable.

## Rendering protocols

The terminal is inspected at runtime and the best available protocol is
selected automatically.

| Protocol      | Fidelity                       | Mechanism                                                    |
| ------------- | ------------------------------ | ------------------------------------------------------------ |
| Kitty         | Exact pixels                   | RGBA transmitted in base64 chunks via the kitty graphics protocol |
| iTerm2        | Exact                          | Raw file bytes via OSC 1337 inline image                     |
| Sixel         | 256-color palette              | DCS sixel bands with RLE compression and Floyd-Steinberg dithering |
| Quarter-block | Four sub-cells per character   | Unicode quadrant blocks (16 characters) with 24-bit fg/bg    |
| Half-block    | Two vertical samples per cell  | Unicode U+2580 with 24-bit foreground/background             |

### Protocol detection

Priority order: **kitty > iterm2 > sixel > quarterblock > halfblock**.

Detection uses environment variables as heuristics (live escape-sequence
queries are not used to avoid terminal lock-up edge cases):

| Variable / Heuristic                  | Detected protocol           |
| ------------------------------------- | --------------------------- |
| `KITTY_WINDOW_ID` is set              | kitty                       |
| `TERM_PROGRAM` is `kitty`/`ghostty`/`WezTerm` | kitty               |
| `WEZTERM_EXECUTABLE` is set           | kitty + sixel               |
| `TERM` contains `kitty`               | kitty                       |
| `TERM_PROGRAM` is `iTerm.app`/`vscode` | iterm2                     |
| `COLORTERM` contains `sixel`          | sixel                       |
| `TERM` contains `sixel`               | sixel                       |
| `TERM` is `foot`/`xterm-foot`/`mlterm` | sixel                     |
| `TERM_PROGRAM` is `tmux`              | none (passthrough required) |

Half-block is always available and serves as the universal fallback.

## Terminal compatibility

| Terminal          | kitty | iterm2 | sixel | quarterblock | halfblock |
| ----------------- | :---: | :----: | :---: | :----------: | :-------: |
| kitty             |   Y   |   -    |   -   |      Y       |     Y     |
| iTerm2            |   -   |   Y    |   -   |      Y       |     Y     |
| WezTerm           |   Y   |   -    |   Y   |      Y       |     Y     |
| Ghostty           |   Y   |   -    |   -   |      Y       |     Y     |
| Foot              |   -   |   -    |   Y   |      Y       |     Y     |
| xterm (compiled)  |   -   |   -    |   Y   |      Y       |     Y     |
| mlterm            |   -   |   -    |   Y   |      Y       |     Y     |
| VS Code terminal  |   -   |   Y    |   -   |      Y       |     Y     |
| GNOME Terminal    |   -   |   -    |   -   |      Y       |     Y     |
| Konsole           |   -   |   -    |   -   |      Y       |     Y     |
| tmux              |   -   |   -    |   -   |      Y       |     Y     |
| Windows Terminal  |   -   |   -    |   -   |      Y       |     Y     |

Any truecolor-capable terminal supports the block renderers.

## Block densities

The `density` field in `RenderOptions` controls how many pixel samples map to
each terminal cell. Higher densities produce finer detail at the cost of larger
output.

| Density | Enum        | Sub-cells per cell | Block characters used    | Best for                |
| ------- | ----------- | ------------------ | ------------------------ | ----------------------- |
| Full    | `bdFull`    | 1                  | One color per cell       | Minimal output          |
| Half    | `bdHalf`    | 2 vertical         | `U+2580` half block      | General use (default)   |
| Quarter | `bdQuarter` | 2x2 quadrant       | All 16 Unicode quadrants | Thumbnails, fine detail |

## Presets

| Preset              | Protocol | Fit    | Width  | Density  | Dither | Best use                  |
| ------------------- | -------- | ------ | ------ | -------- | ------ | ------------------------- |
| `defaultOptions()`  | Auto     | Contain| 90%    | Half     | No     | Full-size display         |
| `thumbnailOptions()`| Auto     | Contain| 40 cols| Quarter  | Yes    | Thumbnails, previews      |

## Scaling

All renderers use **bilinear interpolation** for high-quality upscaling and
downscaling. Edge-clamped sampling ensures no black borders appear at edges.
**Floyd-Steinberg error diffusion dithering** is available for the block-character
and sixel renderers (enable with `opts.dither = true`), reducing banding in
gradients when downscaling.

## Requirements

Nim 2.0 or newer. A truecolor-capable terminal is required for block-character
output; kitty, iTerm2, or sixel support enables exact pixel rendering.

## Installation

Add to your project's `.nimble` file:

```nim
requires "termimg"
```

Then install locally or from a path:

```
nimble install          # from the project root
nimble install /path/to/termimg
```

Or use directly without nimble:

```
nim c --path:src your_app.nim
```

## Quick start

```nim
import termimg

# Detect terminal capabilities once at startup
let caps = detectCapabilities()

# Default rendering — half-block, contain fit, 90% width
let output = renderImageRgba(pixelBytes, 640, 480, caps, defaultOptions())
stdout.write(output)

# Thumbnail — quarter-block, 40 cols max, dithered
let thumb = renderImageRgba(pixelBytes, 640, 480, caps, thumbnailOptions())
stdout.write(thumb)

# Raw file bytes (iTerm2 protocol requires raw image bytes)
let raw = readFile("image.png")
let output2 = renderImageRaw(raw, 800, 600, caps, defaultOptions())
stdout.write(output2)
```

## Demo program

A complete demo is at `examples/demo.nim`:

```
make example
```

It renders four synthetic patterns (checkerboard, rainbow bars, target circles,
warm glow) using every available protocol and prints terminal capability
information. Includes:

- **Gallery**: 3 patterns (checkerboard, rainbow, target) side-by-side
- **All four patterns** in a column via `thumbnailOptions()`
- **Column layout**: Same rainbow pattern at all 3 block densities stacked
- **Fit-mode grid**: Target circles rendered under each of 4 fit modes
- **Extreme aspect ratios**: Wide and tall checkerboard renders

```
make example
```

## API reference

### Types

| Type | Fields | Description |
| ---- | ------ | ----------- |
| `Protocol` | enum: `ptKitty`, `ptSixel`, `ptIterm2`, `ptQuarterBlock`, `ptHalfBlock`, `ptAuto` | Image protocol |
| `FitMode` | enum: `fmContain`, `fmStretch`, `fmWidth`, `fmOriginal`, `fmCellExact` | Scaling strategy |
| `BlockDensity` | enum: `bdFull`, `bdHalf`, `bdQuarter` | Pixel samples per cell |
| `ImageData` | `width`, `height`: int; `data`: seq[uint8] | RGBA pixel buffer |
| `RenderOptions` | `protocol`, `fit`, `maxWidth`, `maxHeight`, `maxWidthRatio`, `maxHeightRatio`, `backgroundRgb`, `dither`, `density` | Rendering parameters |
| `TerminalCapabilities` | `columns`, `rows`, `cell`, `protocols` | Detected terminal state |
| `Geometry` | `pixelWidth`, `pixelHeight`, `columns`, `sampleHeight` | Computed render dimensions |
| `CellSize` | `width`, `height`: int | Terminal cell dimensions in pixels |

### Procs

| Proc | Signature | Description |
| ---- | --------- | ----------- |
| `detectCapabilities` | `(): TerminalCapabilities` | Resolve terminal size and protocol support |
| `selectProtocol` | `(caps, preferred): Protocol` | Pick the best available protocol |
| `computeGeometry` | `(imgW, imgH, caps, opts): Geometry` | Compute aspect-preserving render dimensions |
| `renderImageRgba` | `(data, w, h, caps, opts): string` | Render RGBA pixels to escape sequence string |
| `renderImageRaw` | `(rawBytes, w, h, caps, opts): string` | Render raw file bytes (iTerm2 path) |
| `defaultOptions` | `(): RenderOptions` | Half-block, contain fit, 90% width, no dither |
| `thumbnailOptions` | `(): RenderOptions` | Quarter-block, 40 cols, 50% area, dithered |
| `bilinearResizeRgba` | `(img, dstW, dstH): seq[uint8]` | Bilinear RGBA scaling |
| `bilinearResizeRgb` | `(rgb, srcW, srcH, dstW, dstH): seq[uint8]` | Bilinear RGB scaling |
| `terminalIsInteractive` | `(): bool` | Check if both stdout and stdin are TTYs |
| `animated` | `(src: ImageSource): bool` | Check if an image source has multiple frames |

### Protocol-specific renderers

| Proc | Description |
| ---- | ----------- |
| `renderKitty(img, targetW, targetH): string` | Kitty graphics protocol |
| `renderKittyFile(filePath): string` | Kitty file-based PNG render |
| `renderSixel(img, bg, targetW, targetH, dither): string` | Sixel with 256-color palette |
| `renderIterm2(rawBytes, w, h): string` | iTerm2 OSC 1337 inline image |
| `renderHalfBlock(img, bg, columns, sampleHeight, dither): string` | Unicode half-block |
| `renderQuarterBlock(img, bg, columns, sampleHeight, dither): string` | Unicode quarter-block |

### ImageSource (multi-frame / animated images)

| Type | Description |
| ---- | ----------- |
| `Frame` | `image: ImageData`, `duration: float` (seconds) |
| `ImageSource` | `frames: seq[Frame]`, `loop: int` (0 = infinite) |

The library imports the data types but does not decode animated formats.
Use a separate library (e.g. `stb_image` bindings) to produce `ImageSource`.

### TerminalCapabilities helpers

| Proc | Description |
| ---- | ----------- |
| `caps.pixelWidth` | Total pixel width: `columns * cell.width` |
| `caps.pixelHeight` | Total pixel height: `rows * cell.height` |
| `caps.supports(proto)` | Check if a protocol is in the detected set |

## Fit modes

| Mode | Behavior |
| ---- | -------- |
| `fmContain` | Scale to fit within terminal bounds, preserving aspect ratio (default) |
| `fmStretch` | Fill the terminal bounds, ignoring aspect ratio |
| `fmWidth` | Scale to fit terminal width, height follows aspect ratio |
| `fmOriginal` | Use native size if it fits, otherwise scale to contain |
| `fmCellExact` | User specifies exact column count, height derives from aspect ratio |

## Makefile targets

| Target    | Description                                  |
| --------- | -------------------------------------------- |
| `all`     | Run check, test, and example                 |
| `check`   | Type-check library, test suite, and examples |
| `test`    | Compile and run the test program             |
| `example` | Compile and run the demo program             |
| `clean`   | Remove build artifacts                       |

```
make all        # full pipeline
make test       # compile and run tests
make example    # run the demo
make clean      # remove nimcache and binaries
```

## Architecture

```
.gitignore
Makefile
README.md
termimg.nimble

src/termimg.nim      top-level module, re-exports public API (`import termimg`)
src/termimg/
  types.nim            shared types, Geometry, RenderOptions, computeGeometry
  capabilities.nim     terminal size, cell dimensions, protocol detection
  renderer.nim         protocol selector, renderImageRgba, renderImageRaw
  scaling.nim          bilinear RGBA/RGB interpolation, Floyd-Steinberg dithering
  kitty.nim            kitty graphics protocol encoder
  sixel.nim            sixel protocol encoder with palette quantization
  iterm2.nim           iTerm2 inline image protocol encoder
  halfblock.nim        Unicode half-block renderer (universal fallback)
  quarterblock.nim     Unicode quadrant-block renderer (2x density)

tests/
  test_termimg.nim     integration test: 31 test cases across all features (gallery, columns, comparisons, corruption)

examples/
  demo.nim             standalone demo program with gallery, column layout, fit-grid comparisons
```

## How the block renderers work

### Half-block (U+2580)

Each terminal cell displays two pixels vertically. Upper pixel = foreground
colour (CSI 38;2;R;G;Bm), lower pixel = background colour (CSI 48;2;R;G;Bm).
Colour sequences are emitted only when the colour changes between adjacent
columns, minimizing output size.

```
┌────────────────────┐
│  fg: upper pixel   │  ← CSI 38;2;R;G;Bm
│  bg: lower pixel   │  ← CSI 48;2;R;G;Bm
│       ▀            │  ← U+2580 UPPER HALF BLOCK
└────────────────────┘
```

### Quarter-block (16 quadrant characters)

Each terminal cell covers a 2x2 pixel region. The four sub-pixels are clustered
into two colour groups (foreground and background) by luminance thresholding,
then mapped to one of 16 Unicode block-drawing characters:

```
TL TR    mask bits:  ▖▗▘▙▚▛▜▝▞▟▀▄▌▐█
BL BR    3:TL 2:TR 1:BL 0:BR     spaces
```

## Dithering

Floyd-Steinberg error diffusion is available for halfblock, quarterblock, and
sixel renderers. Enable via `opts.dither = true`. Error is distributed to four
neighboring pixels (7/16 right, 3/16 bottom-left, 5/16 bottom, 1/16
bottom-right), smoothing gradient banding at the cost of slight grain.

## Verification

The library compiles without errors or warnings under Nim 2+. The test suite
runs 31 test cases covering:

- Protocol detection and capability reporting
- Geometry computation at multiple aspect ratios
- All five fit modes (contain, stretch, width, original, cellexact)
- All three block densities (full, half, quarter)
- Bilinear scaling (up and down)
- Floyd-Steinberg dithering
- Full `renderImageRgba` pipeline
- `thumbnailOptions` preset pipeline
- Zero/negative/invalid dimensions (guard rails)
- Short RGBA buffer (guard against underflow)
- Empty raw bytes (guard against underflow)
- Non-terminal / fake environment (no crash)
- Gallery layout (3 patterns side-by-side)
- Column layout (3 densities stacked for comparison)
- Fit-mode comparison grid (4 fit modes stacked)
- Extreme aspect ratios (wide vs tall)
- Off-by-one buffer sizes (1 byte short, 1 byte extra)
- Tiny images (1x1, 1x10, 10x1)
- Fully transparent image (alpha=0 everywhere)
- Monochrome image (all same colour)
- Extreme opts (maxWidth=0, maxWidth=-1, maxHeight=0)
- Empty protocol set (fallback to half-block)
- Extreme pixel aspect ratios (200x1, 1x200)
- Zero background + dithering on black
- Random-stress (20 renders at random sizes/fit modes/densities)
- Tiny buffer claimed as huge image (guard rail)