# `Easel.Terminal`
[🔗](https://github.com/jasonstiebs/easel/blob/v0.3.4/lib/easel/terminal.ex#L1)

Experimental terminal backend for Easel.

This backend renders Easel canvas ops by rasterizing off-screen with
`Easel.WX.rasterize/2`, then converting pixels into terminal glyphs.

It is currently optimized for feasibility over perfect fidelity.

# `animate`

Runs a terminal animation loop.

The `fun` receives the current animation state and must return
`{%Easel{}, new_state}`.

Press `q` (or Ctrl+C) to stop.

## Options

  * `:fps` - frames per second (default `30`)
  * `:interval` - frame interval in ms (overrides `:fps`)
  * `:columns`, `:rows` - output frame size (defaults to terminal size)
  * `:on_key_down` - `fn key_event, state -> new_state end`
  * `:alt_screen` - use alternate screen buffer (default `true`)
  * `:hide_cursor` - hide cursor during rendering (default `true`)
  * `:title` - terminal title (OSC)
  * `:charset`, `:invert`, `:fit`, `:cell_aspect`, `:samples`, `:char_cache`, `:char_cache_size`, `:theme`, `:auto_contrast`, `:color`, `:dpr`

# `available?`

Returns `true` when both wx rasterization and Termite terminal I/O are available.

# `frame_from_rgb`

Converts raw RGB pixels into a terminal frame string.

## Arguments

  * `image` - `%{width: w, height: h, rgb: <<r, g, b, ...>>}`
  * `columns` - output character columns
  * `rows` - output character rows

## Options

  * `:charset` - set a manual luma ramp string, or `:auto` (default) for silhouette fitting
  * `:invert` - invert luma ramp mapping (only for manual charset mode, default `false`)
  * `:fit` - `:contain` (default) or `:fill`
  * `:cell_aspect` - character cell height/width ratio (default `2.0`)
  * `:samples` - per-cell supersampling edge length (manual charset mode, default `2`)
  * `:background_threshold` - brightness below which pixels are treated as background in silhouette mode (default `0.05`)
  * `:glyph_width` / `:glyph_height` - silhouette glyph mask size (defaults `9x19`)
  * `:glyph_threshold` - threshold for binarizing glyph masks (default `0.5`)
  * `:char_cache` - cache silhouette mask→glyph lookups (default `true`)
  * `:char_cache_size` - max cached masks before reset (default `8192`)
  * `:theme` - `:auto` (default), `:dark`, or `:light` for optional contrast adaptation
  * `:auto_contrast` - adapt colors to terminal theme (default `false`)
  * `:dark_min_luma` - minimum foreground luma on dark terminals (default `0.28`)
  * `:light_max_luma` - maximum foreground luma on light terminals (default `0.72`)
  * `:color` - `:none` (default) or `:ansi256`

# `render`

Renders a canvas in the terminal.

Defaults to alt-screen mode and waits for `q` (or Ctrl+C) before returning.

## Options

  * `:columns`, `:rows` - output frame size (defaults to terminal size)
  * `:charset`, `:invert`, `:fit`, `:cell_aspect`, `:samples`, `:char_cache`, `:char_cache_size`, `:theme`, `:auto_contrast`, `:color` - see `frame_from_rgb/4`
  * `:dpr` - rasterization DPR (default `1.0`, higher looks better but costs more)
  * `:title` - terminal title (OSC)
  * `:wait` - wait for quit key (default `true`)
  * `:alt_screen` - use alternate screen buffer (default `true`)
  * `:hide_cursor` - hide cursor during rendering (default `true`)
  * `:on_key_down` - callback for key events in wait loop (`fn key_event -> ... end`)

---

*Consult [api-reference.md](api-reference.md) for complete listing*