Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

How ncv chooses a terminal renderer

The map is a true-color image, but terminals speak different graphics languages. ncv selects the best one automatically — and guarantees a usable view when none exists.

Capability detection, carefully

After entering the terminal session, the viewer settles on one of four renderers — Kitty, Sixel, iTerm2, or the cell fallback. Capability detection is deliberately conservative: querying capabilities over SSH or through multiplexers can hang for seconds while waiting for escape-sequence responses, so ncv avoids the blocking query path. Instead it derives the choice from the observed window size and environment hints. Those hints can only identify iTerm2 automatically; Kitty and Sixel are used when you request them explicitly with NCVIEW_IMAGE_PROTOCOL, and the user can override anything it gets wrong.

The header always reports the active renderer (Kitty truecolor, Sixel truecolor, iTerm2 truecolor, cell fallback, or cells (graphics unavailable) after a protocol encoding failure), so you never have to guess what is actually being used.

The fallback is a first-class mode

If no image protocol is available — plain OpenSSH, tmux with passthrough disabled, an older terminal — ncv renders the map with its own cell rasterizer: one truecolor background block per terminal cell. Everything still works: hover readouts, clicking, zoom, export. The project rule is capability enhancement must never become capability lockout: the fanciest protocol is never required for any workflow.

Explicit protocol selection

NCVIEW_IMAGE_PROTOCOL is honored as given, even when the terminal may not support that protocol correctly. To force the portable renderer, set NCVIEW_IMAGE_PROTOCOL=cells.

  • iTerm2 uses its own protocol rather than Kitty/Sixel.
  • tmux and other multiplexers may swallow capability queries; set NCVIEW_IMAGE_PROTOCOL explicitly to bypass capability detection for the protocol choice.

Scaling choices

By default the image is nearest-neighbor upsampled so a zoomed scientific cell remains one crisp cell — the pixels you see correspond to source values. Interpolation filters (Lanczos, Catmull-Rom, triangle, Gaussian) are available only after unlocking scientific rendering (NCVIEW_SCIENTIFIC_RENDERING=0), making it explicit when a display is smoothing data rather than showing it.