iv: Terminal Image Viewer for Geospatial Data

iv is a highly-optimized, dependency-light Python script for viewing high-resolution geospatial imagery directly inside your terminal emulator.

It leverages ANSI TrueColor half-blocks (▀) to natively render satellite imagery, hyperspectral data, and machine learning outputs directly to your command line without requiring X11, Wayland, or a specialised terminal protocol.

Relationship to bv

iv is a substantial derivative of bv by Dale Roberts. The CLI interface, GDAL band-reading logic, colormap handling, stacking/srcwin pattern, and GNU screen width workaround all originate from bv.

The core differences in iv are:

Feature	bv	iv
Rendering	iTerm2 inline image protocol (base64 PNG)	ANSI TrueColor half-blocks (▀/▄) — works in any TrueColor terminal
Contrast stretch	Min/max	2nd/98th percentile with stable stretch_cache for zoom/pan
Interactive mode	None	Full pan/zoom with keyboard navigation, adaptive frame pacing, signal handling
NoData handling	Alpha mask	Transparent rendering using terminal background
Terminal fit	Fixed -w 800 default	Auto-fits to terminal size via fit_to_terminal()
gdal import	import gdal	from osgeo import gdal

In short: bv is purpose-built for iTerm2; iv replaces the display layer to work in any TrueColor terminal (including Crostini/ChromeOS) and adds interactive navigation.

Features

• Interactive Pan & Zoom: Navigate massive GeoTIFFs seamlessly in the terminal using the arrow keys and +/- with adaptive pacing and zero screen-tearing.
• Robust Auto-Contrast: Automatically applies a GIS-standard 2% - 98% percentile stretch to eliminate wash-out from clouds, shadows, or outlier pixels.
• NoData Awareness: Detects GDAL NoData values and renders them transparently using your terminal's native background color.
• Multi-Band & Single-Band: Renders RGB composites by mapping specific bands, or applies matplotlib colormaps (e.g., viridis, bone) to single-band data.
• On-the-fly Resampling: Dynamically downsamples imagery using GDAL kernels (nearest, bilinear, cubic, lanczos, average, mode).
• Flexible Inputs: Load images from local files, stack multiple files into an RGB composite, or pipe in a list of /vsicurl/ URLs from stdin.

Requirements

• Python 3
• numpy
• gdal (Python bindings)
• Optional: matplotlib (required for applying colormaps to single-band images; if missing, falls back to grayscale).

Usage

Make sure the script is executable and in your PATH:

chmod +x iv

Basic Commands

Display a basic image (auto-scales width to terminal size):

iv image.tif

Launch interactive pan/zoom mode:

iv -interactive image.tif

Display specific bands as an RGB composite (e.g., bands 5, 4, 3):

iv -b 5 -b 4 -b 3 image.tif

Apply a specific colormap to a single-band image:

iv -cm viridis single_band.tif

Stack three separate images into RGB channels:

iv -stack red.tif green.tif blue.tif

Subset a specific region manually (xoff, yoff, xsize, ysize):

iv -srcwin 12000 11000 1000 1000 image.tif

Interactive Mode Controls

When running iv -interactive <file>, use the following keys:

• Arrow Keys: Pan around the image
• + / -: Zoom in and out
• r: Cycle through GDAL resampling algorithms live to fix Moiré/aliasing patterns
• q or Ctrl-C: Quit

Command-Line Options

-w WIDTH        Output width in characters (defaults to terminal width)
-b BAND         Band to display (can be specified multiple times)
-r ALGO         Resampling algorithm (nearest, bilinear, cubic, average, etc.)
-cm MAP         Matplotlib colormap for single-band images (default: bone)
-scale MIN MAX  Min and max values to stretch contrast (overrides 2-98% stretch)
-quiet          Suppress printing image details (dimensions/bands)
-stack          Stack bands from multiple input images
-revstack       Reverse stack bands
-nofn           Do not print filenames before the image
-interactive    Start interactive pan/zoom mode
-srcwin X Y W H Source window offset and size

Performance Technicals

iv contains several low-level optimizations to maintain high framerates over slow terminal transports:

• ANSI Run-Length Encoding: SGR color sequences are only emitted when the pixel color changes, dramatically shrinking the frame payload size.
• Atomic Screen Updates: Uses the \033[?2026h synchronized update wrapper to freeze the terminal state until the frame is fully painted, eliminating flicker.
• Adaptive Transport Pacing: Dynamically measures the terminal emulator's ingestion speed and applies micro-sleeps to batch-write rows, preventing the OS buffer overruns and color fragmentation seen on slow transports like Crostini's vsh relay.