twhy

Whole-slide microscopy, ordinary images, and scientific PDFs, right in your terminal.

twhy is a zoomable, full-screen image viewer made of actual terminal characters. Open an OME-TIFF, SVS, or OME-Zarr slide, explore multichannel fluorescence and Z/T stacks, inspect a PNG, or page through a PDF. No browser, image server, X11, graphics protocol, or GPU required.

I had a use case for this on a remote cluster with thousands of images. Sometimes I just needed the tissue's shape, a rough count of regions of interest, or to tell a big chunk of tissue from a few tiny core needle biopsies. An ASCII-art representation of a preview from the image pyramid seemed like it would do the job.

Then working in tmux, switching the active area of the terminal with either the mouse or keyboard, got me wondering... just how far can we push a text-based image viewer? And thus began twhy. I've been having a little fun with AI slop along the way, and now it opens PDFs and lets me draw polygons on pathology images. It's ridiculous, but I'm actually going to use it.

Real terminal footage: 59-channel multiplex microscopy, DAPI and CD8. Channel selection and zoom, no mock interface.

See it in action

These are short, automatically looping recordings of twhy itself. Click any clip to view it at full GIF size.

Whole-slide H&E SVS Zoom from whole-slide tissue context into individual nuclei.	An ordinary PNG. Featuring a cat. PNG, JPEG, WebP: zoom and pan familiar images, too.
A scientific PDF Turn pages, then zoom into figures. PDF support is standard.	Polygon selections Select rectangles or polygons; export GeoJSON, text, ANSI art, or PNG.
Animated GIF in terminal ASCII Eadweard Muybridge's galloping horse, replayed as real terminal characters.	Live-cell microscopy: Z and T Fluorescence time series, navigating an IDR mitosis Z-stack.

Install

Python 3.11+. The PyPI distribution, terminal command, and Python import all share the name twhy.

Install the standalone command without changing packages in a scientific Python environment:

uv tool install twhy
# or: pipx install twhy
# or: python -m pip install twhy

From a cloned checkout, for development:

python -m pip install -e '.[dev]'

Z/T navigation uses Omeify 0.23.1 or newer, installed automatically as a package dependency. Z/T navigation and examples.

PDF support is included in the standard install. No special extra or system PDF converter is needed.

Quickstart

twhy photo.png                         # PNG, JPEG, WebP, and more
twhy paper.pdf                         # page navigation and progressive detail
twhy slide.svs                         # Aperio whole-slide RGB
twhy slide.ome.tif                     # OME-TIFF, grayscale or multichannel
twhy /data/sample.ome.zarr             # local OME-Zarr
twhy time-depth.ome.tif                # middle Z, T=0; d chooses navigation axis
twhy experiment.zarr --z-index 15 --t-index 12  # explicit zero-based startup plane
twhy animation.gif                     # animated GIF plays and loops automatically
twhy time-depth.ome.tif --play-fps 3   # T slideshow rate; press P to play

# Compose two fluorescence channels with chosen colors:
twhy slide.ome.tif --channel 0 --channel 2 \
  --channel-color 0 blue --channel-color 2 cyan

The initial view fits the image. Wheel zoom is anchored to the pointer; pan with the mouse or arrow keys. The terminal sidebar keeps channels, colors, and contrast controls at hand.

Navigating multidimensional images: Press d to choose which available dimension you are stepping through: Z, T, or Series (for a file with multiple image series). Use [ / ] or PageUp/PageDown to step; p, a zero-based index, and Enter to jump. You can also click Z/T/Series in the top navigation bar. For example, in a two-series OME-TIFF with Z/T in each series, select Series with d, step into series 1, then select Z or T to browse that series. Each series has its own dimensional extents. Switching series fits the new image, resets its channel selection, and starts at middle Z and T=0; stepping Z/T inside one series preserves your camera and display limits. H opens the focused channel's histogram, with draggable lower/upper display limits; l/u/g remain the primary direct contrast/gamma controls in the image view.

Z/T changes preserve the camera, channels, colors and contrast. OME time series start paused; press P for best-effort looping slideshow playback, R to set frames/second. Animated GIFs play and loop by default using their encoded delays. Manual stepping pauses playback. A new series still fits and initializes its own channels. Omitted startup indices use middle Z (size // 2) and T=0 for present axes; invalid explicit indices fail. Only exact-section pyramid levels are used automatically, including when the input stores an XYZ pyramid. Navigation, playback, limitations, and public test inputs.

Why a terminal viewer?

• Whole-slide without whole-slide RAM use: regional TIFF/SVS reads and pyramids, with bounded previews and useful zoomed-out overviews.
• Multichannel, not just RGB: select channels, change pseudocolors, and adjust each marker's display window and gamma without modifying source pixels.
• PDFs and everyday images: ordinary images use in-memory pyramids; PDFs refine progressively from a quick preview to higher-detail pages.
• Real characters: colored ▀ half-blocks, Braille detail, shape-oriented Unicode art, and portable ASCII modes.
• Selection and export: copy/save terminal text, colored ANSI, shareable PNGs, and GeoJSON polygons/rectangles.
• Reusable Python library: sampling, intensity normalization, composition, and rendering are available without opening the interactive terminal UI.

twhy works over ordinary terminal sessions, including environments where a desktop image viewer is inconvenient. It is an exploratory display, not a color-managed diagnostic viewer and not a substitute for measuring the original pixels.

The keys you'll actually use

Action	Key or gesture
Zoom; pan; fit image	Wheel or +/-; arrows or drag; r/Home
Choose navigation dimension	d, or click Z / T / Series in the navigation bar
Step/jump within that dimension	] / [ or PageDown / PageUp; p to jump (PDF pages remain one-based)
GIF / time playback	P plays/pauses; R sets 0.1–30 frames/s; animated GIFs loop by default
Toggle a channel; focus another	Click channel/Space; , and .
Inspect histogram / refine contrast	H toggles histogram; drag its lower/upper range handles; L toggles log counts
Adjust channel color or contrast	h (hue); l/u (limits); g (gamma); a (preview auto window)
Switch artwork / strict ASCII	m / M; t toggles artwork color; f toggles fullscreen
Select region	s rectangle; v polygon
Export a selection	y/Y text, i/I PNG, t/T ANSI, j/J GeoJSON (copy/save)
Help or quit	? / q

Channel histograms and display contrast

Press H to inspect the focused channel's intensity distribution. Drag the ^L / ^U markers to adjust the display range, or enter exact limits with l / u; g adjusts gamma. L switches between logarithmic and linear histogram counts. These controls affect only the display, not the source pixels.

twhy starts preparing the focused channel after a short pause, so opening H can reuse a ready histogram. Scrolling through channels does not queue work for every channel you pass. Time-series playback takes priority over this background work. Display limits stay fixed as you move through Z, T, or the image; preparation never changes them behind your back. Histograms of large images are estimates, not exhaustive pixel counts.

In the histogram view, A offers an experimental suggested display range, applied only when you ask. Lowercase a retains its existing visible-preview auto-window behavior. Use --no-stack-contrast to turn off automatic preparation.

Method, Python API, sampling limits and caveats.

From terminal annotations to full-resolution ROIs

The useful part of the joke: draw regions in twhy, save their coordinates as GeoJSON, and let Omeify extract them from the original image. This example uses a calibrated OME-TIFF, series 0. You also need the omeify command on your PATH; with isolated tool installs, install it separately using uv tool install omeify.

# Open the source and choose where to save the annotations.
twhy slide.ome.tif --series 0 --output-geojson-clip regions.geojson

Zoom to the view you need, then press s for a rectangle or v for a polygon and draw. Close a polygon with Enter; a adds another region in the same view. Press Shift+J to save all the regions before quitting.

# Export one full-resolution image per region, with lossless compression.
omeify crop slide.ome.tif --series 0 \
  --geojson regions.geojson -o regions.ome.tif \
  --shatter by_index --compression Deflate --no-overwrite

This writes regions-01.ome.tif, regions-02.ome.tif, and so on, retaining all channels from the selected series. Omit --shatter by_index to put the regions into separate image series in one OME-TIFF instead.

Full-resolution pixels, not a screenshot: Omeify reads the original image, not the terminal preview. Omeify writes each polygon's enclosing rectangle and masks pixels outside the polygon by default; keep the GeoJSON for the outlines. Use the same source image, series, Z/T plane, and orientation in both steps. Z/T indices are not embedded in the anonymous GeoJSON; record them and pass matching --z-index/--t-index to Omeify when cropping a stack. Annotation placement follows the terminal grid, so zoom in before drawing for finer boundaries. More crop options.

Supported files

Format	What twhy does
OME-TIFF	Regional microscopy viewing, channels, series, Z slices and time points
Aperio SVS	RGB whole-slide viewing using available stored levels
OME-Zarr	Local/HTTP(S)/optional S3, regional reads, series and Z/T navigation
PNG, JPEG, WebP, BMP, TGA, PPM	Ordinary raster viewing with zoom and pan
Animated GIF	Loop by default using GIF delays, with frame stepping and a bounded prepared-frame cache
APNG, animated WebP	View a selected frame; interactive playback is not implemented
PDF	Navigate pages; progressively improve raster detail; copy embedded text from a rectangular selection

For advanced flags, channel/series semantics, color modes, cache limits, clipboard behavior, and format caveats, use the full reference. Architecture notes are in docs/architecture.md.

Try a synthetic microscopy example

The repo includes a deterministic fixture generator that creates public-safe, synthetic tissue-like RGB and multichannel OME-TIFFs. It is a renderer demonstration, not a biological simulation.

python examples/make_demo.py --output-directory /tmp/twhy-demo
twhy /tmp/twhy-demo/synthetic-mif.ome.tif --channel 0 --channel 2

Try a multi-series Z/T OME-TIFF

To try a TIFF containing two separate image series, each with its own Z and T axes, use the included synthetic example:

python examples/make_multiseries_zt_demo.py \
  -o ~/Scratch/twhy-multiseries-zt.ome.tif
twhy ~/Scratch/twhy-multiseries-zt.ome.tif

Press d until Series is selected, then ] to change series. Choose Z or T with d to navigate the stack within it. No input microscope file is needed.

Python API

import numpy as np
from twhy import TextRenderer

pixels = np.linspace(0, 1, 256**2).reshape(256, 256)
frame = TextRenderer(mode="detail", color=False).render(pixels, columns=80)
print(frame.to_text())

Optional remote sources

Local files are the main workflow. twhy also supports HTTP(S) images/PDFs (bounded download) and HTTP(S) OME-Zarr (regional chunk reads). For native S3 or S3-compatible stores, install twhy[s3] and use your normal AWS credentials or an endpoint override. No S3 setup is needed for local images, slides, or PDFs. Remote input reference.

Release media and provenance

These GIFs are edited recordings of the real twhy terminal viewer. Showcase sources:

• mIF: Tan, Y. & Kempchen, T. (2024), SPACEc demo dataset, Dryad.
• H&E whole-slide demo: CMU-1.svs, OpenSlide test data, Carnegie Mellon University, CC0 1.0.
• PDF: Vaswani, A. et al. (2017), Attention Is All You Need, NeurIPS.
• Cat: Illustration generated with ChatGPT (OpenAI).
• Galloping horse: Eadweard Muybridge, Animal Locomotion (1887), plate 626; animation assembled by Wikimedia Commons contributor Waugsberg (2006), source and public-domain status. The showcase is a recording of twhy playing that public-domain GIF.
• Mitotic chromosomes (Z/T): Walther N et al. (2018), A quantitative map of human Condensins provides new insights into mitotic chromosome architecture, J. Cell Biol. doi:10.1083/jcb.201801048. Image Data Resource idr0052, image 5514375, data DOI:10.17867/10000123, OME-NGFF sample catalog, CC BY 4.0. The showcase is a recording of twhy viewing a derived OME-Zarr representation.

License

Apache-2.0. See LICENSE.