viewinline 0.2.0

Quick look geospatial viewer for iTerm2 compatible terminals

viewinline

Quick-look geospatial viewer for compatible terminals.
Displays rasters, vectors, and CSV data directly in the terminal with no GUI and no temporary files.

Think of it as ls for geospatial files — designed for quick visual inspection at the command line, not a replacement for QGIS, ArcGIS, or analytical workflows.

This tool combines the core display logic of viewtif and viewgeom, but is non-interactive: you can't zoom, pan, or switch colormaps on the fly. Instead, you control everything through command-line options (e.g. --display, --color-by, --colormap).

It uses the iTerm2 inline image protocol (OSC 1337) to render previews. In incompatible terminals, the escape codes are silently ignored with no errors or crashes.

Installation

Requires Python 3.9 or later.

pip install viewinline

Usage

viewinline path/to/file.tif
viewinline path/to/vector.geojson
viewinline R.tif G.tif B.tif                 # RGB composite
viewinline path/to/multiband.tif --rgb-bands 3,2,1
viewinline path/to/folder --gallery 4x3      # show image gallery (e.g. 4x3 grid)
viewinline data.csv                          # preview rows and columns
viewinline data.csv --describe               # summary statistics for all numeric columns
viewinline data.csv --describe Income        # summary statistics for one column
viewinline data.csv --hist                   # histograms for all numeric columns
viewinline data.csv --hist area_km2          # histogram for one column
viewinline data.csv --scatter X Y            # scatter plot
viewinline data.csv --where "year > 2010"    # filter rows
viewinline data.csv --sort population        # sort rows
viewinline data.csv --sql "SELECT * FROM data WHERE area > 100 ORDER BY year"  # full SQL

Compatible terminals

The iTerm2 inline image protocol is supported by:

• iTerm2 (macOS)
• WezTerm (cross-platform)
• Konsole (Linux/KDE)
• Rio, Contour (Linux)

Not supported: Mac Terminal, GNOME Terminal, Kitty, Ghostty, Alacritty.

Note: Does not work inside tmux or screen.

Features

• Previews rasters, vectors and CSV files directly in the terminal
• Non-interactive: everything is controlled through command-line options

Supported formats

Rasters

• GeoTIFF (.tif, .tiff)
• PNG, JPEG (.png, .jpg, .jpeg)
• Single-band or multi-band composites

Composite inputs

• You can pass three rasters (e.g. R.tif G.tif B.tif) to create an RGB composite

Vectors

• GeoJSON (.geojson)
• Shapefile (.shp, .dbf, .shx)
• GeoPackage (.gpkg)

CSV

• Preview file summary (rows, columns, and names)
• Summary statistics with --describe
• Show all numeric columns, or specify one (e.g. --describe height)
• Inline histograms with --hist
• Show all numeric columns, or specify one (e.g. --hist area_km2)
• Scatter plots with --scatter X Y
• Filter rows with --where, sort with --sort, limit output with --limit
• Full SQL queries with --sql (DuckDB required) — use data as the table name (e.g. --sql "SELECT State, AVG(Income) FROM data GROUP BY State")

Gallery view

• Display all images in a folder with --gallery 4x4

Dependencies

Core dependencies (installed automatically):

• rasterio — raster reading
• geopandas, pyogrio — vector reading
• matplotlib — vector rendering
• Pillow — image encoding
• numpy, pandas — data handling

Optional:

• duckdb — required for --where, --sort, --sql, and --limit with filtering. Install separately with pip install duckdb.

Available options

General:
  --display DISPLAY     Resize only the displayed image (0.5=smaller, 2=bigger). Default: auto-fit to terminal.

Raster:
  --band BAND           Band number to display for single-band rasters. (default: 1)
  --colormap            Apply colormap to single-band rasters. Flag without value → 'terrain'.
  --rgb-bands RGB_BANDS Comma-separated band numbers for RGB display (e.g., '3,2,1'). Overrides default 1-3.
  --vmin VMIN           Minimum pixel value for raster display scaling.
  --vmax VMAX           Maximum pixel value for raster display scaling.
  --nodata NODATA       Override nodata value for rasters if dataset metadata is incorrect.
  --gallery [GRID]      Display all PNG/JPG/TIF images in a folder as thumbnails (e.g., 5x5 grid).

Vector:
  --color-by COLUMN     Column to color vector features by.
  --colormap            Apply colormap to vector coloring. Flag without value → 'terrain'.
  --width WIDTH         Line width for vector boundaries. (default: 0.7)
  --edgecolor COLOR     Edge color for vector outlines (hex or named color). (default: #F6FF00)
  --layer LAYER         Layer name for GeoPackage or multi-layer files.

CSV:
  --describe [COLUMN]   Show summary statistics for all numeric columns or specify one column name.
  --hist [COLUMN]       Show histograms for all numeric columns or specify one column name.
  --bins BINS           Number of bins for histograms (used with --hist). (default: 20)
  --scatter X Y         Plot scatter of two numeric CSV columns (e.g. --scatter area_km2 year).
  --unique COLUMN       Show unique values for a categorical column.
  --where EXPR          Filter rows using SQL WHERE clause (DuckDB required) (e.g. --where "year > 2010")
  --sort COLUMN         Sort rows by values in the specified column, ascending by default. Use --desc to reverse.
  --desc                Sort in descending order (used with --sort).
  --limit N             Limit number of rows shown (e.g. --limit 100).
  --select COLUMNS      Select specific columns (space separated) (e.g. --select Country City).
  --sql QUERY           Execute full DuckDB SQL query. Use 'data' as the table name (e.g. --sql "SELECT * FROM data WHERE Poverty > 40").

Need help?

You can ask questions about usage via the documentation-based assistant:

👉 Ask the viewtif + viewgeom + viewinline Helper

👉 For NASA staff: find 'viewtif + viewgeom + viewinline Helper' via the ChatGSFC Agent Marketplace

License

This project is released under the Apache License 2.0 © 2025 Keiko Nomura.

If you find this tool useful, please consider supporting or acknowledging it in your work.

Useful links

• YouTube demo playlist
• Demo at the initial release
• Demo for the v0.1.3
• Demo with GDAL
• User feedback (thank you!)