Skip to content
Quickly view (satellite) imagery directly in your terminal
Branch: master
Clone or download
Pull request Compare This branch is 7 commits behind daleroberts:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

tv ("textview") is a small tool to quickly view high-resolution multi-band imagery directly in your terminal. It was designed for working with (very large) satellite imagery data over a low-bandwidth connection. For example, you can directly visualise a Himawari 8 (11K x 11K pixel) image of the Earth directly from its URL:

It is built upon the wonderful GDAL library so it is able to load a large variety of image formats (GeoTiff, PNG, Jpeg, NetCDF, ...) and subsample the image as it reads from disk so it can handle very large files quickly. It has the ability to read filenames (or URLs) from stdin and load files directly from URLs without writing locally to disk. Command line options are styled after gdal_translate such as:

  • -b to specify the bands (and ordering) to use,
  • -srcwin xoff yoff xsize ysize to view a subset of the image,
  • -r to specify the subsampling algorithm (nearest, bilinear, cubic, cubicspline, lanczos, average, mode).

tv is completely implemented in Python 3 using only Numpy and GDAL 2.0.

My rendering approach is different from other tools such as hiptext as I use more unicode characters and true color. This means that you get amazingly better results as long as your terminal and font supports it. Here is a comparison between hiptext (left) and tv (right) using their benchmark image of Barack Obama using the standard MacOS font 'Menlo Regular' at size 11 in iTerm 2.0.

You can easily zoom in to get better detail or make the output smaller.

You can quickly view very large files over low-bandwidth connections (e.g., mobile). For example, visualising a 46GB single-band 176000 x 140000 pixel image using nearest neighbour subsampling located on the raijin supercomputer.

It can detect URLs on the standard input which allows you to use it in combination with other tools such as landsat-util to quickly visualise thumbnails before you perform a full download.

You can directly give a URL on the command line.

If you have a image with more than 3 bands (channels), you can specify the ordering and the bands that you would like to load into the RGB channels.

You can stack multiple images into the red/green/blue channel or handle multiple subsets of a NetCDF file.

If you really want to throttle back the number of unicode characters used (e.g., if your font or terminal doesn't support many unicode characters), you can do it with a command line option. The following example shows how to use only the block character or a half-height character as well.

Using a GNU parallel, you can do silly things like create a low-fi animation of the Earth viewed from the Himawari-8 satellite.

parallel --willcite --tty --header : tv -w 60 -urls{dy}/{hr}{tenmin}000_0_0.png  ::: dy 06 ::: hr 06 ::: tenmin {0..5}


How do I install it?

It is just a single-file script so all you'll need to do it put it in your PATH.

Dependencies are Python 3, GDAL 2.0, and Numpy. I've installed GDAL 2.0 on MacOS using homebrew and the osgeo tap. On Linux, I typically install GDAL 2.0 by hand-compiling it.

What about imgcat?

imgcat is nice but it needs to (1) be a file format that MacOS supports (2) transfer the full file across the connection encoded as Base64.

You can’t perform that action at this time.