viewinline 0.3.2__tar.gz → 0.4.0__tar.gz

viewinline-0.4.0/CITATION.cff

@@ -0,0 +1,44 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it using the metadata from this file."
+title: "viewinline"
+abstract: >-
+  A tiny, non-interactive command-line viewer that displays rasters/photos,
+  vectors, and tabular data (CSV/Parquet) inline in the terminal — no GUI,
+  no X11, and no file downloads. Designed for quick visual inspection at the
+  command line, and especially useful on HPC systems and remote servers over
+  SSH, where images render on the local terminal.
+type: software
+authors:
+  - given-names: Keiko
+    family-names: Nomura
+    # orcid: "https://orcid.org/0000-0000-0000-0000"   # optional: add if you have one
+  - given-names: Filip
+    family-names: Kral
+    # orcid: "https://orcid.org/0000-0000-0000-0000"   # optional: add if you have one
+repository-code: "https://github.com/nkeikon/inlineviewer"
+url: "https://github.com/nkeikon/inlineviewer"
+license: Apache-2.0
+version: 0.3.2
+date-released: 2026-06-06
+# ---------------------------------------------------------------------------
+# The DOI below is the VERSION DOI for v0.3.2 (a specific archived snapshot).
+# To make citations always resolve to your LATEST release, replace it with the
+# Zenodo CONCEPT / "all versions" DOI, shown on the record under "Cite all
+# versions". The version DOI stays useful in `identifiers` for reproducibility.
+# ---------------------------------------------------------------------------
+doi: "10.5281/zenodo.20564266"
+identifiers:
+  - type: doi
+    value: "10.5281/zenodo.20564266"
+    description: "Zenodo archive of version v0.3.2"
+keywords:
+  - geospatial
+  - raster
+  - vector
+  - terminal
+  - command-line
+  - visualization
+  - GeoTIFF
+  - NetCDF
+  - GeoParquet
+  - remote-sensing

{viewinline-0.3.2 → viewinline-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: viewinline
-Version: 0.3.2
+Version: 0.4.0
 Summary: Quick look geospatial viewer for the terminal, with inline image previews
 Project-URL: Homepage, https://github.com/nkeikon/viewinline
 Project-URL: Repository, https://github.com/nkeikon/viewinline
@@ -81,6 +81,11 @@ viewinline hyperspectral.nc --subset 22 --bands 10-54 --gallery 5x11
 viewinline path/to/vector.geojson
 viewinline boundaries.geoparquet --color-by population --colormap viridis
 
+# Save to file
+viewinline path/to/file.tif --export out.png   # save the rendered image as PNG (or .jpg)
+viewinline scene.tif --rgb 4 3 2 --export rgb.png
+viewinline dem.tif --colormap terrain --display 1 --export dem.png   # full-res with colormap
+
 # CSV and Parquet
 viewinline data.csv                          # preview rows and columns
 viewinline data.parquet --describe           # summary statistics
@@ -134,6 +139,7 @@ You can also force the chafa path on any terminal by setting `INLINE_VIEWER_ENGI
 - **NetCDF/HDF Support:** Display variables from NetCDF (.nc) and HDF5 (.h5, .hdf5) files with automatic nodata detection and multi-slice navigation
 - **Parquet/GeoParquet:** Render GeoParquet as vector maps or view as tabular data
 - **Tabular View for Vectors:** Use `--table` to access CSV-style operations (filter, sort, describe, hist) on any vector file  
+- **AI-agent inspection:** `--info` returns file metadata and statistics as JSON; `--export` saves a quick-look image for an agent to inspect. Designed for AI coding-agent workflows.
 
 ## Supported formats  
 **Rasters**  
@@ -180,6 +186,7 @@ You can also force the chafa path on any terminal by setting `INLINE_VIEWER_ENGI
 - Variables with 4+ dimensions are not supported
 - For a complete variable list, use `ncdump -h file.nc` or `viewtif`
 
+
 ## Dependencies
 
 **Core dependencies** (installed automatically):
@@ -213,6 +220,8 @@ You can also force the chafa path on any terminal by setting `INLINE_VIEWER_ENGI
 ```
 General:
   --display DISPLAY     Resize only the displayed image (0.5=smaller, 2=bigger). Default: auto-fit to terminal.
+  --info                Print file metadata and statistics as JSON, then exit (agent-facing). For NetCDF/HDF, lists variables; combine with --subset N to inspect one. Always returns JSON, including on error.
+  --export PATH         Save the rendered image to PATH (.png/.jpg) and open it. Works with any display flag. Prints {"path": "..."} as the final line.
 
 Raster:
   --band BAND           Band number to display (single raster), or slice number for NetCDF. (default: 1)
@@ -249,6 +258,95 @@ CSV and Parquet:
   --select COLUMNS      Select specific columns (space separated). Example: --select Country City
   --sql QUERY           Execute full DuckDB SQL query. Use 'data' as table name. Example: --sql "SELECT * FROM data WHERE Poverty > 40"
 ```
+## AI-agent inspection (`--info`, `--export`)
+
+An optional command aimed at AI coding-agent workflows (Claude Code, Codex, Cursor, and similar). An agent can confirm its code *ran*, but not whether the geospatial file it produced is *sensible* — wrong CRS, unexpected dimensions, all-NoData, NaN/Inf values, or a flipped output. `--info` answers **"what did I create?"** as machine-readable JSON.
+
+```bash
+viewinline result.tif --info                 # metadata + statistics as JSON, then exit
+```
+
+It reports facts, not judgments: format, dimensions, bands, dtype, CRS, resolution, bounds, nodata, and per-band statistics. For NetCDF/HDF it lists variables; add `--subset N` to inspect one:
+
+```bash
+viewinline data.nc --info                    # list variables
+viewinline data.nc --subset 7 --info         # inspect variable 7
+viewinline scene.hdf --subset 1 --info       # inspect HDF subdataset 1
+```
+
+`--info` always returns JSON, including a `{"readable": false, "error": ...}` object on unreadable input, so an agent can always parse the result. Pairs well with `--export` (see Usage) when the agent wants to *see* the output too, not just read its metadata.
+
+### `--info` — structured inspection
+
+Prints file metadata as JSON and exits (no image is drawn). Reports facts, not judgments — the agent interprets them in context.
+
+```bash
+viewinline result.tif --info
+```
+```json
+{
+  "format": "GTiff",
+  "filename": "result.tif",
+  "dimensions": [1001, 1001],
+  "bands": 3,
+  "dtype": "uint16",
+  "crs": "EPSG:32631",
+  "resolution": [10.0, 10.0],
+  "bounds": [590520.0, 5780620.0, 600530.0, 5790630.0],
+  "nodata": null,
+  "statistics": {
+    "method": "full",
+    "bands_total": 3,
+    "bands_reported": 3,
+    "per_band": [
+      {"band": 1, "min": 0.0, "max": 10964.0, "mean": 1009.32, "valid_fraction": 1.0, "naninf_fraction": 0.0}
+    ]
+  }
+}
+```
+
+For **NetCDF and HDF**, `--info` lists the file's variables/subdatasets; add `--subset N` to inspect one:
+
+```bash
+viewinline data.nc --info                    # list variables
+viewinline data.nc --subset 7 --info         # inspect variable 7 (dims, dtype, units, stats)
+viewinline scene.hdf --subset 1 --info       # inspect HDF subdataset 1
+```
+
+`--info` **always returns JSON**, including on failure. Unsupported or unreadable inputs return a structured error rather than crashing, so an agent can always parse the result:
+
+```json
+{"error": "no directly-readable bands (file has subdatasets)", "readable": false, "subdataset_count": 22}
+```
+
+Notes on the output:
+- `crs` is an `EPSG:code` when one can be resolved, the full WKT string when the CRS has no EPSG code (e.g. MODIS Sinusoidal), or `null` when the file has no CRS.
+- Statistics exclude NoData and non-finite pixels; `valid_fraction` and `naninf_fraction` report how much was excluded.
+- For files with many bands, per-band stats are capped (a `bands_reported` < `bands_total` and a `note` indicate truncation — absence of a band's stats does **not** imply a problem).
+- Large rasters are sampled for statistics (`"method": "sampled"`); small ones use every pixel (`"method": "full"`).
+
+### `--export` — visual inspection
+
+Saves the rendered image to a file (PNG or JPEG, chosen by extension) so an agent can also inspect it with its vision capabilities, then prints the path as JSON:
+
+```bash
+viewinline result.tif --export out.png
+```
+```json
+{"path": "/abs/path/out.png"}
+```
+
+`--export` works with **any display option** — the saved image is exactly what viewinline would render, after all flags are applied:
+
+```bash
+viewinline scene.tif --rgb 4 3 2 --export rgb.png
+viewinline dem.tif --colormap terrain --export dem.png
+viewinline result.tif --display 1 --export full_res.png   # full resolution instead of terminal-fit
+```
+
+The exported image is a quick-look representation for catching problems metadata can't reveal — blank output, stripes, artifacts, holes, wrong orientation, unexpected extent, or bad color scaling — **not** a publication-quality rendering.
+
+> **Scope:** `--info` and `--export` tell you what a file *is* and what it *looks like*. Neither claims the scientific result is *correct* — that judgment stays with the agent.
 
 ## Need help?
 NASA staff can ask questions about usage via the documentation-based assistant 'viewtif + viewgeom + viewinline Helper' via the ChatGSFC Agent Marketplace.

{viewinline-0.3.2 → viewinline-0.4.0}/README.md

@@ -48,6 +48,11 @@ viewinline hyperspectral.nc --subset 22 --bands 10-54 --gallery 5x11
 viewinline path/to/vector.geojson
 viewinline boundaries.geoparquet --color-by population --colormap viridis
 
+# Save to file
+viewinline path/to/file.tif --export out.png   # save the rendered image as PNG (or .jpg)
+viewinline scene.tif --rgb 4 3 2 --export rgb.png
+viewinline dem.tif --colormap terrain --display 1 --export dem.png   # full-res with colormap
+
 # CSV and Parquet
 viewinline data.csv                          # preview rows and columns
 viewinline data.parquet --describe           # summary statistics
@@ -101,6 +106,7 @@ You can also force the chafa path on any terminal by setting `INLINE_VIEWER_ENGI
 - **NetCDF/HDF Support:** Display variables from NetCDF (.nc) and HDF5 (.h5, .hdf5) files with automatic nodata detection and multi-slice navigation
 - **Parquet/GeoParquet:** Render GeoParquet as vector maps or view as tabular data
 - **Tabular View for Vectors:** Use `--table` to access CSV-style operations (filter, sort, describe, hist) on any vector file  
+- **AI-agent inspection:** `--info` returns file metadata and statistics as JSON; `--export` saves a quick-look image for an agent to inspect. Designed for AI coding-agent workflows.
 
 ## Supported formats  
 **Rasters**  
@@ -147,6 +153,7 @@ You can also force the chafa path on any terminal by setting `INLINE_VIEWER_ENGI
 - Variables with 4+ dimensions are not supported
 - For a complete variable list, use `ncdump -h file.nc` or `viewtif`
 
+
 ## Dependencies
 
 **Core dependencies** (installed automatically):
@@ -180,6 +187,8 @@ You can also force the chafa path on any terminal by setting `INLINE_VIEWER_ENGI
 ```
 General:
   --display DISPLAY     Resize only the displayed image (0.5=smaller, 2=bigger). Default: auto-fit to terminal.
+  --info                Print file metadata and statistics as JSON, then exit (agent-facing). For NetCDF/HDF, lists variables; combine with --subset N to inspect one. Always returns JSON, including on error.
+  --export PATH         Save the rendered image to PATH (.png/.jpg) and open it. Works with any display flag. Prints {"path": "..."} as the final line.
 
 Raster:
   --band BAND           Band number to display (single raster), or slice number for NetCDF. (default: 1)
@@ -216,6 +225,95 @@ CSV and Parquet:
   --select COLUMNS      Select specific columns (space separated). Example: --select Country City
   --sql QUERY           Execute full DuckDB SQL query. Use 'data' as table name. Example: --sql "SELECT * FROM data WHERE Poverty > 40"
 ```
+## AI-agent inspection (`--info`, `--export`)
+
+An optional command aimed at AI coding-agent workflows (Claude Code, Codex, Cursor, and similar). An agent can confirm its code *ran*, but not whether the geospatial file it produced is *sensible* — wrong CRS, unexpected dimensions, all-NoData, NaN/Inf values, or a flipped output. `--info` answers **"what did I create?"** as machine-readable JSON.
+
+```bash
+viewinline result.tif --info                 # metadata + statistics as JSON, then exit
+```
+
+It reports facts, not judgments: format, dimensions, bands, dtype, CRS, resolution, bounds, nodata, and per-band statistics. For NetCDF/HDF it lists variables; add `--subset N` to inspect one:
+
+```bash
+viewinline data.nc --info                    # list variables
+viewinline data.nc --subset 7 --info         # inspect variable 7
+viewinline scene.hdf --subset 1 --info       # inspect HDF subdataset 1
+```
+
+`--info` always returns JSON, including a `{"readable": false, "error": ...}` object on unreadable input, so an agent can always parse the result. Pairs well with `--export` (see Usage) when the agent wants to *see* the output too, not just read its metadata.
+
+### `--info` — structured inspection
+
+Prints file metadata as JSON and exits (no image is drawn). Reports facts, not judgments — the agent interprets them in context.
+
+```bash
+viewinline result.tif --info
+```
+```json
+{
+  "format": "GTiff",
+  "filename": "result.tif",
+  "dimensions": [1001, 1001],
+  "bands": 3,
+  "dtype": "uint16",
+  "crs": "EPSG:32631",
+  "resolution": [10.0, 10.0],
+  "bounds": [590520.0, 5780620.0, 600530.0, 5790630.0],
+  "nodata": null,
+  "statistics": {
+    "method": "full",
+    "bands_total": 3,
+    "bands_reported": 3,
+    "per_band": [
+      {"band": 1, "min": 0.0, "max": 10964.0, "mean": 1009.32, "valid_fraction": 1.0, "naninf_fraction": 0.0}
+    ]
+  }
+}
+```
+
+For **NetCDF and HDF**, `--info` lists the file's variables/subdatasets; add `--subset N` to inspect one:
+
+```bash
+viewinline data.nc --info                    # list variables
+viewinline data.nc --subset 7 --info         # inspect variable 7 (dims, dtype, units, stats)
+viewinline scene.hdf --subset 1 --info       # inspect HDF subdataset 1
+```
+
+`--info` **always returns JSON**, including on failure. Unsupported or unreadable inputs return a structured error rather than crashing, so an agent can always parse the result:
+
+```json
+{"error": "no directly-readable bands (file has subdatasets)", "readable": false, "subdataset_count": 22}
+```
+
+Notes on the output:
+- `crs` is an `EPSG:code` when one can be resolved, the full WKT string when the CRS has no EPSG code (e.g. MODIS Sinusoidal), or `null` when the file has no CRS.
+- Statistics exclude NoData and non-finite pixels; `valid_fraction` and `naninf_fraction` report how much was excluded.
+- For files with many bands, per-band stats are capped (a `bands_reported` < `bands_total` and a `note` indicate truncation — absence of a band's stats does **not** imply a problem).
+- Large rasters are sampled for statistics (`"method": "sampled"`); small ones use every pixel (`"method": "full"`).
+
+### `--export` — visual inspection
+
+Saves the rendered image to a file (PNG or JPEG, chosen by extension) so an agent can also inspect it with its vision capabilities, then prints the path as JSON:
+
+```bash
+viewinline result.tif --export out.png
+```
+```json
+{"path": "/abs/path/out.png"}
+```
+
+`--export` works with **any display option** — the saved image is exactly what viewinline would render, after all flags are applied:
+
+```bash
+viewinline scene.tif --rgb 4 3 2 --export rgb.png
+viewinline dem.tif --colormap terrain --export dem.png
+viewinline result.tif --display 1 --export full_res.png   # full resolution instead of terminal-fit
+```
+
+The exported image is a quick-look representation for catching problems metadata can't reveal — blank output, stripes, artifacts, holes, wrong orientation, unexpected extent, or bad color scaling — **not** a publication-quality rendering.
+
+> **Scope:** `--info` and `--export` tell you what a file *is* and what it *looks like*. Neither claims the scientific result is *correct* — that judgment stays with the agent.
 
 ## Need help?
 NASA staff can ask questions about usage via the documentation-based assistant 'viewtif + viewgeom + viewinline Helper' via the ChatGSFC Agent Marketplace.

viewinline-0.4.0/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: viewinline
+description: Terminal viewer for rasters, vectors, and tabular data. Use for quick visual inspection without leaving the shell—preview images in a folder gallery, inspect geospatial files after GDAL workflows, explore CSV data with histograms/scatter plots, or verify files before commit. Provides machine-readable `--info` (metadata + statistics as JSON) and `--export` (save the rendered image) for programmatically checking generated geospatial files. Non-interactive; everything controlled via command-line flags.
+tags: [visualization, terminal, raster, vector, csv, geospatial, gdal, ml, inspection, workflow]
+---
+
+# Viewinline Skill
+
+Quick-look terminal viewer for geospatial and tabular data. Think of it as `ls` for visual files—designed for command-line workflows where you want to inspect data without leaving the terminal or opening a separate application.
+
+Renders natively in iTerm2, WezTerm, Konsole, Rio, and Contour. Falls back to `chafa` (ASCII art with 24-bit color) in other terminals like kitty, Ghostty, Terminal.app, VS Code, and Linux terminals. Works over SSH without X11 forwarding or VNC.
+
+## When to Use
+
+- **File browsing**: `find . -name "*.jpg" | xargs -n1 viewinline` to visually scan results
+- **Gallery view**: `viewinline path/to/folder --gallery 4x3` to preview all images in a directory
+- **Band inspection**: Display specific bands of a raster as a grid: `--bands 10-50` or `--bands 11,15,30,45`
+- **Geospatial workflows**: Inspect raster/vector outputs after GDAL transformations
+- **ML training data**: Review training image galleries without switching windows
+- **Data exploration**: Quick CSV visualizations (histograms, scatter plots, summary stats)
+- **Pre-commit checks**: Verify images, maps, and data files before pushing
+- **Remote servers**: Works over SSH from your local terminal
+- **Verify generated files (agent workflows)**: After writing a GeoTIFF/NetCDF/vector with GDAL, rasterio, or xarray, run `viewinline FILE --info` to check the result is sensible (correct CRS, dimensions, value range, not all-NoData/NaN) as JSON, and `viewinline FILE --export out.png` to visually inspect it
+
+## Supported Formats
+
+**Rasters:** GeoTIFF, PNG, JPEG, NetCDF, HDF5, HDF4  
+**Vectors:** GeoJSON, Shapefile, GeoPackage, GeoParquet  
+**Tabular:** CSV, Parquet (with `pyarrow`)
+
+## Inspecting Files (JSON output)
+
+For programmatic checks, two flags return machine-readable output instead of drawing an image. Useful after generating a file to confirm it's sensible before continuing.
+
+- `--info` — print file metadata and statistics as JSON, then exit. Reports facts, not judgments (the caller interprets them).
+  - Rasters (GeoTIFF, NetCDF, HDF): format, dimensions, bands, dtype, CRS, resolution, bounds, nodata, per-band stats (min/max/mean, valid_fraction, naninf_fraction).
+  - Vectors (GeoJSON, Shapefile, GeoPackage, GeoParquet): feature count, geometry type, CRS, bounds, columns.
+  - For NetCDF/HDF: `--info` lists variables/subdatasets; add `--subset N` to inspect one.
+  - Always returns JSON, including `{"readable": false, "error": ...}` on unreadable input — safe to parse in all cases.
+- `--export PATH` — save the rendered image to PATH (`.png`/`.jpg`) and print `{"path": "..."}`. Works with any display flag (`--rgb`, `--colormap`, `--band`, `--display`), saving exactly what would be drawn.
+
+```bash
+# check a raster you just wrote
+viewinline result.tif --info
+
+# check a vector
+viewinline boundaries.geojson --info
+
+# NetCDF: list variables, then inspect one
+viewinline data.nc --info
+viewinline data.nc --subset 7 --info
+
+# save a quick-look image to inspect visually
+viewinline result.tif --export out.png
+viewinline scene.tif --rgb 4 3 2 --export rgb.png
+```
+
+Note: `--info` and `--export` report what a file *is* and what it *looks like* — not whether the scientific result is correct.
+
+## Core Flags
+
+**Inspection (JSON output, no image):**
+- `--info` — print metadata + statistics as JSON, then exit (rasters and vectors; lists variables for NetCDF/HDF with `--subset N`)
+- `--export PATH` — save the rendered image to PATH (`.png`/`.jpg`); prints `{"path": "..."}`
+
+**Raster Display:**
+- `--rgb R G B` — Specify band order for RGB (e.g., `--rgb 4 3 2`)
+- `--rgbfiles R.tif G.tif B.tif` — Create RGB composite from separate files
+- `--band N` — Display specific band or NetCDF timestep
+- `--bands RANGE` — Display multiple bands as a grid (e.g., `10-50` or `11,15,30,45`)
+- `--gallery NxM` — Show all images in folder as thumbnails (e.g., `4x3` grid)
+- `--colormap NAME` — Apply colormap (e.g., `plasma`, `viridis`, `terrain`)
+- `--vmin VAL --vmax VAL` — Set min/max for scaling
+- `--display SCALE` — Resize displayed output (0.5=smaller, 2=bigger)
+
+**Vector Display:**
+- `--color-by COLUMN` — Color features by attribute value
+- `--colormap NAME` — Apply colormap to coloring
+- `--width W` — Line width for boundaries
+- `--edgecolor COLOR` — Edge color (hex or named)
+- `--table` — Display as tabular data instead of rendering geometry
+
+**Tabular Data (CSV/Parquet):**
+- `--describe [COL]` — Summary statistics for all numeric columns or one
+- `--hist [COL]` — Histograms for numeric columns
+- `--scatter X Y` — Scatter plot of two columns
+- `--where EXPR` — Filter rows (DuckDB required): `--where "year > 2010"`
+- `--sort COL` — Sort by column (ascending); use `--desc` for descending
+- `--limit N` — Limit output rows
+- `--select COL1 COL2` — Choose specific columns to display
+- `--sql QUERY` — Full DuckDB SQL (use `data` as table name)
+
+**NetCDF/HDF:**
+- `--subset N` — Select variable by index
+- `--band N` or `--timestep N` — Select slice along time/band axis
+- `--reduce DIM_NAME` — Override auto-detected band axis for non-standard dimensions
+
+## Examples
+
+### Image browsing
+```bash
+# Browse all JPGs in directory
+find . -name "*.jpg" | xargs viewinline
+
+# Gallery of all images in a folder (4 columns × 3 rows)
+viewinline path/to/images --gallery 4x3
+```
+
+### Raster workflows
+```bash
+# Display single band
+viewinline data.tif --band 2
+
+# RGB composite from three bands
+viewinline multiband.tif --rgb 4 3 2
+
+# Create RGB from separate files
+viewinline R.tif G.tif B.tif
+
+# Display band range as gallery
+viewinline hyperspectral.tif --bands 10-50 --gallery 5x5
+
+# Apply colormap with min/max scaling
+viewinline temp.nc --subset 1 --colormap plasma --vmin 273 --vmax 310
+```
+
+### GDAL verification
+```bash
+# Reproject and check result
+gdalwarp -t_srs EPSG:3857 input.tif temp.tif
+viewinline temp.tif --colormap terrain
+
+# Resample and verify
+gdal_translate -outsize 50% 50% temp.tif output.tif
+viewinline output.tif
+```
+
+### Vector inspection
+```bash
+# View vector file
+viewinline boundaries.geojson
+
+# Color features by attribute, with colormap
+viewinline boundaries.geoparquet --color-by population --colormap viridis
+
+# View vector as tabular data
+viewinline counties.shp --table
+viewinline data.geoparquet --table --where "POP > 100000" --sort POP --desc
+```
+
+### Data exploration
+```bash
+# Preview CSV
+viewinline data.csv
+
+# Summary statistics
+viewinline data.parquet --describe
+
+# Histograms for all numeric columns
+viewinline data.csv --hist
+
+# Scatter plot
+viewinline data.csv --scatter area_km2 year
+
+# Filter and sort
+viewinline data.csv --where "year > 2010" --sort population --desc
+
+# SQL query
+viewinline data.csv --sql "SELECT * FROM data WHERE area > 100 ORDER BY year"
+
+# Batch CSV inspection with xargs (use -I {} to control argument order)
+find . -name "*.csv" | xargs -n1 -I {} viewinline {} --describe
+```
+
+### Verify generated files (agent workflows)
+```bash
+# Reproject, then check the result is sensible as JSON
+gdalwarp -t_srs EPSG:3857 input.tif output.tif
+viewinline output.tif --info
+
+# Confirm a written raster isn't all-NoData / has expected CRS and range
+viewinline result.tif --info
+
+# List a NetCDF's variables, then inspect the data variable
+viewinline output.nc --info
+viewinline output.nc --subset 7 --info
+
+# Save a quick-look PNG to inspect visually
+viewinline result.tif --export check.png
+```
+
+## Tips
+
+- Use `--gallery` to quickly preview batches of training images or search results
+- Pipe with `xargs`: `find . -newer file.txt | xargs viewinline` to inspect recent changes
+- Add aliases: `alias check='viewinline --describe --hist'`
+- Works in tmux if outer terminal is iTerm2; falls back to ASCII art in other terminals
+- Install `chafa` for better coverage: `brew install chafa` (macOS), `apt install chafa` (Linux)
+- SSH-friendly: images render on your local terminal, not the remote server

viewinline-0.4.0/context7.json

@@ -0,0 +1,20 @@
+```json
+{
+  "$schema": "https://context7.com/schema/context7.json",
+  "projectTitle": "viewinline",
+  "description": "Terminal inline geospatial preview tool for rasters and vectors over SSH and HPC workflows, with machine-readable --info and --export for AI-agent file inspection.",
+  "excludeFolders": [
+    "tests",
+    "examples/large-data",
+    "build",
+    "dist"
+  ],
+  "rules": [
+    "Prefer SSH and terminal-based workflows in examples.",
+    "Use inline terminal image rendering instead of GUI workflows.",
+    "Highlight support for GeoTIFF, NetCDF, GeoJSON, and GeoParquet.",
+    "Emphasize compatibility limitations for terminal graphics protocols.",
+    "For programmatic or AI-agent use, note --info (JSON metadata) and --export (save rendered image)."
+  ]
+}
+```

viewinline-0.4.0/llms.txt

@@ -0,0 +1,244 @@
+# viewinline
+
+> A tiny, non-interactive command-line viewer that displays rasters/photos, vectors, and tabular data (CSV/Parquet) inline in your terminal — no GUI, no X11, no file downloads. Think of it as `ls` for geospatial files: built for quick visual inspection at the command line, not a replacement for QGIS/ArcGIS or analytical workflows. Especially useful on HPC systems and remote servers over SSH, where images render on your *local* terminal. Also provides agent-facing `--info` (metadata as JSON) and `--export` (save the rendered image) for AI coding-agent workflows.
+
+- Package: `viewinline` (PyPI: https://pypi.org/project/viewinline/)
+- Repo: https://github.com/nkeikon/inlineviewer
+- Command name: `viewinline`
+- Requires: Python 3.9+
+- License: Apache-2.0 © 2026 Keiko Nomura
+- Latest release: v0.4.0 (2026-06-06)
+- Combines the core display logic of `viewtif` and `viewgeom`, but is **non-interactive**: no zoom/pan/colormap-switching on the fly. Everything is controlled via CLI options (e.g. `--display`, `--color-by`, `--colormap`).
+
+## Installation
+
+```
+pip install viewinline
+pip install --upgrade viewinline          # upgrade
+pip install --upgrade "viewinline[netcdf]"  # with hyperspectral/NetCDF extras
+```
+
+Optional extras (install only if needed):
+- `duckdb` — required for `--where`, `--sort`, `--select`, `--limit`, `--sql`. `pip install duckdb`
+- `pyarrow` — required for Parquet/GeoParquet. `pip install pyarrow`
+- `h5py` — fallback for HDF5 if GDAL lacks HDF5 support (usually unnecessary). `pip install h5py`
+- `chafa` — system binary (not a Python package); strongly recommended for terminal coverage beyond the native list. See "Terminals".
+
+## How display works (rendering engines)
+
+- Uses the **iTerm2 inline image protocol (OSC 1337)** natively in supported terminals.
+- Falls back to **`chafa`** elsewhere, which routes through each terminal's best protocol: real high-res images via the kitty graphics protocol or sixel in some terminals, and 24-bit colored block-art (ASCII-art) previews in others.
+- Without `chafa`, terminals outside the native list show an info message instead of an image.
+- Force the chafa path on any terminal with the env var `INLINE_VIEWER_ENGINE=chafa`.
+
+## Terminals
+
+Native (no extra install, via OSC 1337): iTerm2 (macOS), WezTerm, Konsole (KDE), Rio, Contour.
+
+Via `chafa` (recommended for everyone else):
+- Real high-res images (kitty graphics protocol / sixel): kitty, Ghostty, foot.
+- Colored block-art previews (24-bit color): Terminal.app, VS Code, GNOME Terminal, Alacritty, Warp, Hyper, most Linux terminals.
+
+Install chafa once (system binary, works across all conda/virtualenv environments):
+```
+brew install chafa        # macOS
+sudo apt install chafa     # Debian/Ubuntu
+sudo dnf install chafa     # Fedora
+scoop install chafa        # Windows
+```
+
+- **SSH/HPC:** Works over SSH when connecting from a compatible terminal. Images render on the *local* machine, not the remote server. No X11 forwarding or VNC required.
+- **tmux/screen:** Full inline images work inside tmux only when the *outer* terminal is iTerm2 (or WezTerm/Konsole/Rio/Contour). With other outer terminals (kitty, Terminal.app, etc.), viewinline shows ASCII/block-art previews instead.
+- **Windows:** For real images, use Windows Terminal (v1.22+) or WezTerm. Stock PuTTY can show block-art via chafa.
+
+### Terminal detection & image-support logic
+
+viewinline decides how to render by detecting the terminal, then routing native-OSC-1337 terminals one way and everything else through chafa.
+
+Detection checks these environment variables (in order): `TERM_PROGRAM`, `KONSOLE_VERSION`, `KONSOLE_PROFILE_NAME`, `VTE_VERSION`, `TERMINATOR_UUID`, `ALACRITTY_SOCKET`, `WEZTERM_EXECUTABLE`, `ITERM_SESSION_ID`, and `TERM`. If none are set, it falls back to inspecting the parent process name (via `ps`).
+
+Override: setting `INLINE_VIEWER_ENGINE=chafa` forces the chafa path on any terminal, bypassing detection.
+
+Important nuance — terminals NOT on the native OSC-1337 list still get images via chafa; "not native" does **not** mean "no images." chafa auto-detects the terminal and picks the best output:
+- `xterm-kitty` (kitty) → real images via the kitty graphics protocol
+- foot, Ghostty, and similar → may render real images via sixel or the kitty protocol, depending on chafa's detection
+- most others (Terminal.app, VS Code, GNOME Terminal, Alacritty, Warp, etc.) → Unicode block-art preview with 24-bit color
+
+Only terminals **without chafa installed** (and outside the native OSC-1337 set) see no rendering at all — just an info message.
+
+Terminals routed through chafa rather than native OSC 1337 (these are the values matched during detection): `Apple_Terminal` (Terminal.app), `xterm-kitty` (kitty), `screen`/`screen-256color`, `tmux`/`tmux-256color` (the `TMUX` env var also signals tmux), `vscode` (VS Code integrated terminal), `alacritty`, `foot`, `ghostty`/`xterm-ghostty`, `WarpTerminal` (Warp), `Hyper`, `unknown`, `cygwin`, `rxvt`/`rxvt-unicode`/`rxvt-unicode-256color`, `st-256color` (suckless st), `gnome-terminal`, `xfce4-terminal`, `lxterminal`, `terminator`, `tilix`, `sakura`, `terminology`, `guake`, `tilda`, `deepin-terminal`, `eterm`, `putty`, and `Windows Terminal`. (Most Linux desktop terminals are VTE-based and lack OSC 1337.) Terminals using native OSC 1337 — iTerm2, WezTerm, Konsole, Rio, Contour — are deliberately absent from this list.
+
+## Supported formats
+
+Rasters: GeoTIFF (.tif, .tiff); PNG, JPEG (.png, .jpg, .jpeg); NetCDF (.nc); HDF5 (.h5, .hdf5); HDF4 (.hdf, requires GDAL with HDF4 support); single-band or multi-band composites.
+
+Vectors: GeoJSON (.geojson), Shapefile (.shp), GeoPackage (.gpkg), Parquet/GeoParquet (.parquet, .geoparquet).
+
+Tabular: CSV (.csv), Parquet (.parquet, requires pyarrow). All CSV operations work on Parquet.
+
+HDF/NetCDF notes:
+- HDF5 (.h5/.hdf5): via rasterio if GDAL has HDF5 support (most installs).
+- HDF4 (.hdf): requires GDAL compiled with HDF4 support (legacy MODIS / older NASA products).
+- NetCDF (.nc): via rasterio (GDAL's NetCDF driver).
+- viewinline lists only variables displayable as 2D or 3D arrays. 3D variables with time or known spatial dims are auto-handled (sliced along the non-spatial axis). Variables with 4+ dimensions are not supported. For a full variable list, use `ncdump -h file.nc` or `viewtif`.
+
+## Usage examples
+
+Rasters:
+```
+viewinline path/to/file.tif
+viewinline R.tif G.tif B.tif                       # RGB composite (also via --rgbfiles)
+viewinline path/to/multiband.tif --rgb 3 2 1
+viewinline path/to/folder --gallery 4x3            # gallery of all images in a folder
+viewinline path/to/hyperspectral.tif --bands 10-50 # gallery of selected bands (also --bands 11,15,30,45)
+```
+
+NetCDF / HDF:
+```
+viewinline file.nc                                 # list variables
+viewinline file.nc --subset 2                      # display variable 2
+viewinline file.nc --subset 1 --band 10            # variable 1, timestep 10 (--band or --timestep)
+viewinline temp.nc --subset 1 --colormap plasma --vmin 273 --vmax 310
+viewinline hyperspectral.nc --subset 1 --reduce NumberOfScanlines  # override auto-detected axis
+viewinline hyperspectral.nc --subset 22 --band 50
+viewinline hyperspectral.nc --subset 22 --bands 10-54 --gallery 5x11
+```
+
+Vectors:
+```
+viewinline path/to/vector.geojson
+viewinline boundaries.geoparquet --color-by population --colormap viridis
+```
+
+CSV / Parquet:
+```
+viewinline data.csv                                # preview rows and columns
+viewinline data.parquet --describe                 # summary statistics
+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 (DuckDB)
+viewinline data.csv --sort population --desc       # sort rows
+viewinline data.csv --sql "SELECT * FROM data WHERE area > 100 ORDER BY year"  # full SQL; table name is 'data'
+```
+
+Tabular view of vectors (`--table` unlocks CSV-style ops on any vector file):
+```
+viewinline counties.shp --table
+viewinline counties.shp --table --describe
+viewinline counties.shp --table --unique STATE_NAME
+viewinline data.geoparquet --table --where "POP > 100000" --sort POP --desc
+```
+
+## CLI options
+
+General:
+- `--display DISPLAY` — resize only the displayed image (0.5 = smaller, 2 = bigger). Default: auto-fit to terminal.
+- `--info` — print file metadata as JSON, then exit (no image drawn). Works with rasters (GeoTIFF, NetCDF, HDF) and vectors (GeoJSON, Shapefile, GeoPackage, GeoParquet). For NetCDF/HDF, lists variables; combine with `--subset N` to inspect one. Always returns JSON, including a `{"readable": false, "error": ...}` object on unreadable input. Aimed at AI coding agents.
+- `--export PATH` — save the rendered image to PATH (`.png`/`.jpg`, chosen by extension) and open it; prints `{"path": "..."}` as the final line. Works with any display flag (`--rgb`, `--colormap`, `--band`, `--display`), saving exactly what viewinline would render. Useful for saving quick-looks and for AI agents inspecting outputs visually.
+Raster:
+- `--band BAND` — band number for a single raster, or slice number for NetCDF (default: 1).
+- `--bands BANDS` — display multiple bands as a grid. Accepts ranges (`30-40`), lists (`3,4,5`), or mixed (`1,5,10-15`).
+- `--rgb R G B` — three band numbers for RGB display (e.g. `--rgb 4 3 2`); overrides default `1 2 3`. Accepts space- or comma-separated values (`--rgb 4 3 2` or `--rgb 4,3,2`).
+- `--rgbfiles R G B` — three single-band rasters for an RGB composite (can also be given as positional args).
+- `--timestep INTEGER` — alias for `--band` with NetCDF files.
+- `--subset INTEGER` — variable index for NetCDF/HDF files (e.g. `--subset 1`).
+- `--reduce DIM_NAME` — for 3D NetCDF variables, choose which dimension is the band/slider axis. Auto-detected if omitted.
+- `--colormap` — apply colormap to single-band rasters; flag with no value → `terrain`.
+- `--vmin VMIN` / `--vmax VMAX` — pixel value range for display scaling (each works independently).
+- `--nodata NODATA` — override nodata value when dataset metadata is missing/incorrect.
+- `--gallery [GRID]` — display all PNG/JPG/TIF images in a folder as thumbnails (e.g. `5x5`).
+
+Vector:
+- `--color-by COLUMN` — color features by a column.
+- `--colormap` — apply colormap to vector coloring; flag with no value → `terrain`.
+- `--width WIDTH` — line width for vector boundaries (default: 0.7).
+- `--edgecolor COLOR` — edge color for outlines, hex or named (default: white).
+- `--layer LAYER` — layer name for GeoPackage/multi-layer files, or variable name for NetCDF.
+- `--table` — display a vector/parquet file as tabular data instead of rendering geometry.
+
+CSV / Parquet:
+- `--describe [COLUMN]` — summary statistics for all numeric columns or one named column.
+- `--hist [COLUMN]` — histograms for all numeric columns or one named column.
+- `--bins BINS` — number of histogram bins (with `--hist`; default: 20).
+- `--scatter X Y` — scatter plot of two numeric columns.
+- `--unique COLUMN` — unique values for a categorical column.
+- `--where EXPR` — filter rows with a SQL WHERE clause (DuckDB). Example: `--where "year > 2010"`.
+- `--sort COLUMN` — sort by column (ascending by default; use `--desc`).
+- `--desc` — descending sort (with `--sort`).
+- `--limit N` — limit number of rows shown.
+- `--select COLUMNS` — select specific columns, space-separated. Example: `--select Country City`.
+- `--sql QUERY` — full DuckDB SQL query; use `data` as the table name. Example: `--sql "SELECT * FROM data WHERE Poverty > 40"`.
+
+Help text is grouped into sections: General, Raster, Vector, and Tabular.
+
+## AI-agent inspection (`--info`, `--export`)
+
+Two commands for AI coding-agent workflows (Claude Code, Codex, Cursor, and similar): an agent can confirm its code *ran* but not whether the geospatial file it produced is *sensible* (wrong CRS, unexpected dimensions, all-NoData, NaN/Inf values, flipped output). These answer "what did I create?" and "what does it look like?" as machine-readable JSON. Both are deterministic and local — no LLM dependency, no external API calls.
+
+`--info` reports facts, not judgments, choosing fields per format:
+- Rasters (GeoTIFF, NetCDF, HDF): format, dimensions, bands, dtype, CRS, resolution, bounds, nodata, per-band statistics (min/max/mean, valid_fraction, naninf_fraction).
+- Vectors (GeoJSON, Shapefile, GeoPackage, GeoParquet): feature count, geometry type, CRS, bounds, columns.
+
+viewinline result.tif --info # raster metadata + stats as JSON
+viewinline boundaries.geojson --info # vector: features, geometry, CRS, columns
+viewinline data.nc --info # list NetCDF variables
+viewinline data.nc --subset 7 --info # inspect variable 7 (dims, dtype, units, stats)
+viewinline scene.hdf --subset 1 --info # inspect HDF subdataset 1
+
+Output notes:
+- `crs` is an `EPSG:code` when one can be resolved, WKT when the CRS has no EPSG code (e.g. MODIS Sinusoidal), or `null` when absent.
+- Statistics exclude NoData and non-finite pixels; large rasters are sampled (`"method": "sampled"`), small ones read in full (`"method": "full"`).
+- Files with many bands report a capped subset (`bands_reported` < `bands_total`, plus a `note`); missing per-band stats do not imply a problem.
+- Errors return structured JSON (`{"readable": false, "error": ...}`) rather than crashing, so callers can always parse the result.
+
+`--export` saves what viewinline would render to PNG/JPEG and prints `{"path": "..."}`:
+viewinline result.tif --export out.png
+viewinline scene.tif --rgb 4 3 2 --export rgb.png
+viewinline dem.tif --colormap terrain --display 1 --export dem.png # full-res with colormap
+
+Neither command claims the scientific result is *correct* — that judgment stays with the agent.
+
+## Behavior notes (current)
+
+- Multi-band rasters (multispectral, hyperspectral, embeddings) are NOT auto-composited as RGB. Band 1 is shown in grayscale by default (consistent with NetCDF). Use `--rgb` to composite explicitly. `--band N` shows any single band N (including band 1).
+- `--gallery` silently skips incompatible/non-image files instead of failing the whole run.
+- In chafa/ASCII terminals, band labels and gallery filenames are printed as a text grid *after* the image (labels drawn on the canvas are unreadable there), so you can tell tiles/files apart.
+- `--bands` tiles are labeled with their band number; default colormap for `--bands` is viridis (override with `--colormap`). Works with GeoTIFF and NetCDF.
+- For large CSV or filtered results, viewinline prompts `Show first N or all? [first/all]`.
+- `--vmin` and `--vmax` are independent — setting only one no longer falls back to auto-scaling on both ends.
+
+## Hyperspectral / non-standard NetCDF
+
+viewinline can open NetCDF files that organize variables under hierarchical groups (e.g. `/radiometric_data/CalibratedRadianceData`), use non-standard dimension names (`NumberOfChannels`, `NumberOfScanlines`, etc.), or have malformed CF attributes (e.g. per-band `scale_factor` arrays that xarray's default decoding can't handle).
+
+Band-axis detection for 3D variables is tiered: user override (`--reduce`) → standard convention (lat/lon detected) → smallest-dimension fallback. If auto-detection picks the wrong axis, set it explicitly:
+```
+viewinline PICARDL1B.nc --subset 22 --band 50
+viewinline file.nc --subset 1 --reduce DIM_NAME
+```
+Tested on NASA PICARD L1B; the same pattern should apply to AVIRIS, EMIT, and similar instruments.
+
+## Dependencies
+
+Core (installed automatically): `rasterio` (raster reading, includes GDAL), `geopandas` + `pyogrio` (vector reading), `matplotlib` (vector rendering), `Pillow` (image encoding), `numpy`, `pandas`.
+
+Optional: `chafa` (terminal coverage; system binary), `duckdb` (filter/sort/SQL), `pyarrow` (Parquet/GeoParquet), `h5py` (HDF5 fallback).
+
+## Version history (selected)
+
+- **v0.3.2 (2026-06-06):** Band labels and gallery filenames shown as a text grid after the image in chafa/ASCII terminals; `--gallery NxM` now works with `--bands` for NetCDF; `--rgb` works with NetCDF when used with `--subset`; `--vmin`/`--vmax` work independently; `--rgb` accepts comma-separated values; help text grouped into sections; large-CSV prompt changed to `Show first N or all? [first/all]`.
+- **v0.3.1 (2026-06-02):** New `--bands` flag (gallery grid of multiple bands; ranges/lists/mixed; per-tile band-number labels; viridis default); `--gallery` now silently skips incompatible files; multi-band rasters no longer auto-composite as RGB (band 1 grayscale by default — use `--rgb`).
+- **v0.3.0 (2026-05-15):** Hyperspectral NetCDF support (hierarchical groups, non-standard dimension names, malformed CF attributes); new `--reduce` flag; tiered dimension detection; fixed `--band 1` being overridden by RGB auto-composite on multi-band TIFFs; consistent `(downsampled)` label; `[netcdf]` install extra.
+- **v0.2.3 (2026-05-13):** Broad terminal support via chafa (real high-res on kitty/foot; block-art elsewhere); fixed Apple_Terminal / `xterm-kitty` misdetection; reliable block-art inside tmux. chafa fallback contributed by @filipkral.
+- **v0.2.2 (2026-04-22):** Added Zenodo DOI for citation.
+- **v0.2.1 (2026-02-21):** NetCDF/HDF support (`--subset`, `--band`/`--timestep`, auto nodata, HDF4 via GDAL); Parquet/GeoParquet; `--table` for vectors; `--rgb 3 2 1` syntax + `--rgbfiles`; auto edge-color removal when coloring by column.
+- **v0.2.0 (2026-02-17):** Inline-only display (OSC 1337); removed ANSI fallback and /tmp save; DuckDB integration for `--where`/`--sort`/`--select`/`--limit`/`--sql`; license switched MIT → Apache-2.0.
+- **v0.1.5 (2026-02-13):** Fixed duplicate band-display prints; optimized uint8 normalization; minor perf.
+- **v0.4.0 (2026-08-23):** New agent-facing inspection commands: `--info` (file metadata + statistics as JSON, for rasters and vectors; lists variables for NetCDF/HDF with `--subset`; always returns JSON including structured errors) and `--export` (save the rendered image to PNG/JPEG, works with any display flag). Existing viewer behavior unchanged.
+
+## Support & links
+
+- NASA staff can ask usage questions via the documentation-based assistant "viewtif + viewgeom + viewinline Helper" in the ChatGSFC Agent Marketplace.
+- YouTube demo playlist: https://www.youtube.com/playlist?list=PLP9MNCMgJIHj6FvahJ6Tembp1rCyhLtR4
+- Releases: https://github.com/nkeikon/inlineviewer/releases

{viewinline-0.3.2 → viewinline-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "viewinline"
-version = "0.3.2"
+version = "0.4.0"
 description = "Quick look geospatial viewer for the terminal, with inline image previews"
 readme = "README.md"
 license = { text = "Apache-2.0" }

{viewinline-0.3.2 → viewinline-0.4.0}/src/viewinline/viewinline.py

@@ -24,6 +24,7 @@ from PIL import Image, ImageOps, ImageDraw, ImageFont
 from matplotlib import colormaps
 import matplotlib as mpl
 import subprocess
+import json
 
 import warnings
 
@@ -31,7 +32,10 @@ warnings.filterwarnings("ignore", message="More than one layer found", category=
 warnings.filterwarnings("ignore", message="Dataset has no geotransform", category=UserWarning)
 warnings.filterwarnings("ignore", message="invalid scale_factor or add_offset attribute", category=UserWarning)
 
-__version__ = "0.3.2"
+_EXPORT_PATH = None
+_EXPORT_RESULT = None
+
+__version__ = "0.4.0"
 
 AVAILABLE_COLORMAPS = [
     "viridis", "inferno", "magma", "plasma",
@@ -203,25 +207,42 @@ def show_inline_image(image_array: np.ndarray, display_scale = None, is_vector:
     
     sys.stdout.flush()
 
+def _open_in_viewer(path: str) -> None:
+    """Open a file in the OS default viewer. Best-effort; ignores failures."""
+    try:
+        if sys.platform == "darwin":
+            subprocess.run(["open", path], check=False)
+        elif sys.platform.startswith("linux"):
+            subprocess.run(["xdg-open", path], check=False)
+        elif sys.platform.startswith("win"):
+            os.startfile(path)
+    except Exception:
+        pass
+
 def show_image_auto(img: np.ndarray, display_scale=None, is_vector: bool = False) -> None:
-    """Render an image inline, with chafa fallback for non-iTerm2 terminals.
-    
-    Cascade:
-      1. If terminal supports OSC 1337 → emit iTerm2 inline image sequence.
-      2. Else if chafa is installed → pipe through chafa (which auto-detects
-         and emits the terminal's native graphics protocol or block-art).
-      3. Else → print an info message suggesting chafa installation.
-    
-    The branching happens inside show_inline_image(); this wrapper handles
-    status messaging and exception safety.
-    """
+    global _EXPORT_RESULT
+    # Export mode: save the image, open it in the OS viewer, skip inline render.
+    if _EXPORT_PATH:
+        try:
+            out = Image.fromarray(img)
+            ext = os.path.splitext(_EXPORT_PATH)[1].lower()
+            if ext in (".jpg", ".jpeg"):
+                out.convert("RGB").save(_EXPORT_PATH, quality=90)
+            else:
+                out.save(_EXPORT_PATH)
+            saved_path = os.path.abspath(_EXPORT_PATH)
+            _open_in_viewer(saved_path)
+            _EXPORT_RESULT = {"path": saved_path}
+        except Exception as e:
+            _EXPORT_RESULT = {"error": str(e)}
+        return
+
     try:
         show_inline_image(img, display_scale, is_vector)
         if _TERMINAL_SUPPORTS_IMAGES:
             print("[VIEW] Inline render complete")
         elif is_chafa_available():
             print("[VIEW] Inline render complete via chafa")
-        # If neither path applies, show_inline_image already printed the info message
     except Exception as e:
         print(f"[ERROR] Failed to render image: {e}")
         import traceback
@@ -273,7 +294,255 @@ def parse_rgb(values: list[str]) -> list[int]:
     except ValueError:
         print("[WARN] --rgb requires exactly 3 band numbers. e.g. --rgb 4 3 2 or --rgb 4,3,2")
         return None
-    
+
+def print_raster_info(path: str, subset: int = None) -> int:
+    """Agent-facing: print JSON metadata + basic stats for a raster. Returns exit code."""
+    try:
+        import rasterio
+        from rasterio.enums import Resampling
+    except ImportError:
+        print(json.dumps({"error": "rasterio not installed", "readable": False}))
+        return 1
+
+    # Resolve subdataset selection for HDF/NetCDF containers
+    if subset is not None and path.lower().endswith((".nc", ".hdf", ".hdf5", ".h5")):
+        try:
+            with rasterio.open(path) as ds:
+                subs = ds.subdatasets
+            if subs:
+                if subset < 1 or subset > len(subs):
+                    print(json.dumps({"error": f"--subset must be between 1 and {len(subs)}",
+                                      "readable": False, "subdataset_count": len(subs)}))
+                    return 1
+                # path = subs[subset - 1]
+                path = subs[subset - 1]
+                subset_var = path.split(":")[-1]                
+        except Exception as e:
+            print(json.dumps({"error": str(e), "readable": False}))
+            return 1
+
+    try:
+        with rasterio.open(path) as ds:
+            # Container with no directly-readable bands (e.g. HDF/NetCDF without --subset)
+            if ds.count == 0:
+                subs = ds.subdatasets
+                print(json.dumps({
+                    "format": ds.driver,
+                    "filename": os.path.basename(path),
+                    "readable": False,
+                    "error": "no directly-readable bands (file has subdatasets)",
+                    "subdataset_count": len(subs),
+                    "note": "Use --subset N to inspect a specific subdataset.",
+                }))
+                return 1
+
+            if ds.crs:
+                epsg = ds.crs.to_epsg() or ds.crs.to_epsg(confidence_threshold=20)
+                crs_str = f"EPSG:{epsg}" if epsg else ds.crs.to_string()
+            else:
+                crs_str = None
+
+            info = {
+                "format": ds.driver,
+                "filename": os.path.basename(path),
+                "dimensions": [ds.width, ds.height],
+                "bands": ds.count,
+                "dtype": ds.dtypes[0],
+                "crs": crs_str,
+                "resolution": [abs(ds.transform.a), abs(ds.transform.e)],
+                "bounds": [ds.bounds.left, ds.bounds.bottom, ds.bounds.right, ds.bounds.top],
+                "nodata": ds.nodata,
+            }
+
+            H, W = ds.height, ds.width
+            cap = 1024
+            sampled = max(H, W) > cap
+            if sampled:
+                s = cap / max(H, W)
+                out_shape = (max(1, int(H * s)), max(1, int(W * s)))
+
+            MAX_BANDS = 20
+            n_report = min(ds.count, MAX_BANDS)
+            per_band = []
+            for b in range(1, n_report + 1):
+                if sampled:
+                    arr = ds.read(b, out_shape=out_shape,
+                                  resampling=Resampling.nearest).astype("float64")
+                else:
+                    arr = ds.read(b).astype("float64")
+
+                valid = np.isfinite(arr)
+                if ds.nodata is not None:
+                    valid &= (arr != ds.nodata)
+                n_total, n_valid = arr.size, int(valid.sum())
+
+                bs = {"band": b}
+                if n_valid:
+                    v = arr[valid]
+                    bs.update({"min": float(v.min()), "max": float(v.max()), "mean": float(v.mean())})
+                else:
+                    bs.update({"min": None, "max": None, "mean": None})
+                bs["valid_fraction"] = round(n_valid / n_total, 4) if n_total else 0.0
+                bs["naninf_fraction"] = round(int((~np.isfinite(arr)).sum()) / n_total, 4) if n_total else 0.0
+                per_band.append(bs)
+
+            stats_block = {
+                "method": "sampled" if sampled else "full",
+                "bands_total": ds.count,
+                "bands_reported": n_report,
+                "per_band": per_band,
+            }
+            if n_report < ds.count:
+                stats_block["band_sampling"] = "first_n"
+                stats_block["note"] = (f"Showing bands 1-{n_report} of {ds.count}. "
+                                       f"Remaining bands not analyzed; absence of stats does not imply a problem.")
+            info["statistics"] = stats_block
+
+            try:
+                info["storage"] = {
+                    "tiled": bool(ds.profile.get("tiled", False)),
+                    "compression": ds.compression.value if ds.compression else None,
+                    "overviews": ds.overviews(1),
+                }
+            except Exception:
+                pass
+
+            print(json.dumps(info))
+            return 0
+    except Exception as e:
+        print(json.dumps({"error": str(e), "readable": False}))
+        return 1
+
+def print_netcdf_info(path: str, subset: int = None) -> int:
+    """Agent-facing: JSON metadata for a NetCDF file via netCDF4 (matches viewer's variable indexing)."""
+    try:
+        import netCDF4
+    except ImportError:
+        print(json.dumps({"error": "netCDF4 not installed", "readable": False}))
+        return 1
+    try:
+        nc = netCDF4.Dataset(path)
+    except Exception as e:
+        print(json.dumps({"error": str(e), "readable": False}))
+        return 1
+
+    # Same recursive enumeration the renderer uses, so indices match
+    def collect_vars(group, prefix=""):
+        out = []
+        for name, var in group.variables.items():
+            out.append((f"{prefix}{name}", var))
+        for sub_name, sub in group.groups.items():
+            out.extend(collect_vars(sub, f"{prefix}{sub_name}/"))
+        return out
+
+    all_vars = collect_vars(nc)
+    if not all_vars:
+        print(json.dumps({"error": "no variables found", "readable": False}))
+        nc.close()
+        return 1
+
+    # No --subset: list variables (mirrors the viewer's listing)
+    if subset is None:
+        variables = [{
+            "index": i,
+            "name": name,
+            "shape": list(var.shape),
+            "dtype": str(var.dtype),
+            "dimensions": list(var.dimensions),
+        } for i, (name, var) in enumerate(all_vars, 1)]
+        print(json.dumps({
+            "format": "netCDF",
+            "filename": os.path.basename(path),
+            "variable_count": len(all_vars),
+            "variables": variables,
+            "note": "Use --subset N to inspect a specific variable.",
+        }))
+        nc.close()
+        return 0
+
+    # --subset given: inspect that variable
+    if subset < 1 or subset > len(all_vars):
+        print(json.dumps({"error": f"--subset must be between 1 and {len(all_vars)}",
+                          "readable": False, "variable_count": len(all_vars)}))
+        nc.close()
+        return 1
+
+    var_name, var = all_vars[subset - 1]
+    info = {
+        "format": "netCDF",
+        "filename": os.path.basename(path),
+        "subset": subset,
+        "variable": var_name,
+        "shape": list(var.shape),
+        "dtype": str(var.dtype),
+        "dimensions": list(var.dimensions),
+    }
+
+    # Attributes worth surfacing if present
+    for attr in ("units", "long_name", "standard_name"):
+        if hasattr(var, attr):
+            info[attr] = str(getattr(var, attr))
+
+    fill = getattr(var, "_FillValue", None)
+    info["fill_value"] = float(fill) if fill is not None else None
+
+    # Stats on a sample: read one slice if 3D+, or the whole thing if small 2D/1D
+    try:
+        if var.ndim >= 3:
+            # sample first slice along axis 0 to avoid loading the full cube
+            arr = np.asarray(var[0], dtype="float64")
+            stats_scope = f"first slice along '{var.dimensions[0]}' (of {var.shape[0]})"
+        else:
+            arr = np.asarray(var[:], dtype="float64")
+            stats_scope = "full variable"
+
+        valid = np.isfinite(arr)
+        if fill is not None:
+            valid &= (arr != fill)
+        n_total, n_valid = arr.size, int(valid.sum())
+        stats = {"scope": stats_scope}
+        if n_valid:
+            v = arr[valid]
+            stats.update({"min": float(v.min()), "max": float(v.max()), "mean": float(v.mean())})
+        else:
+            stats.update({"min": None, "max": None, "mean": None})
+        stats["valid_fraction"] = round(n_valid / n_total, 4) if n_total else 0.0
+        stats["naninf_fraction"] = round(int((~np.isfinite(arr)).sum()) / n_total, 4) if n_total else 0.0
+        info["statistics"] = stats
+    except Exception as e:
+        info["statistics"] = {"error": str(e)}
+
+    print(json.dumps(info))
+    nc.close()
+    return 0
+
+def print_vector_info(path: str) -> int:
+    try:
+        import geopandas as gpd
+    except ImportError:
+        print(json.dumps({"error": "geopandas not installed", "readable": False}))
+        return 1
+    try:
+        if path.lower().endswith((".parquet", ".geoparquet")):
+            gdf = gpd.read_parquet(path)
+        else:
+            gdf = gpd.read_file(path)
+        b = gdf.total_bounds  # [minx, miny, maxx, maxy]
+        info = {
+            "format": "vector",
+            "filename": os.path.basename(path),
+            "features": len(gdf),
+            "geometry_type": str(gdf.geom_type.iloc[0]) if len(gdf) else None,
+            "crs": (f"EPSG:{gdf.crs.to_epsg()}" if gdf.crs and gdf.crs.to_epsg()
+                    else (gdf.crs.to_string() if gdf.crs else None)),
+            "bounds": [float(x) for x in b],
+            "columns": [c for c in gdf.columns if c != gdf.geometry.name],
+        }
+        print(json.dumps(info))
+        return 0
+    except Exception as e:
+        print(json.dumps({"error": str(e), "readable": False}))
+        return 1
 # ---------------------------------------------------------------------
 # CSV handling
 # ---------------------------------------------------------------------
@@ -1491,7 +1760,8 @@ def render_vector(path, args):
 # ---------------------------------------------------------------------
 import argparse
 
-class SmartDefaults(argparse.ArgumentDefaultsHelpFormatter):
+class SmartDefaults(argparse.ArgumentDefaultsHelpFormatter,
+                    argparse.RawDescriptionHelpFormatter):
     """Show defaults only when meaningful (not None or SUPPRESS)."""
     def _get_help_string(self, action):
         if action.help and "%(default)" in action.help:
@@ -1662,8 +1932,16 @@ def main() -> None:
             "Supports rasters (.tif, .tiff, .png, .jpg, .jpeg), "
             "vectors (.shp, .geojson, .gpkg), and CSV preview.\n"
             "Sends iTerm2 inline image protocol — visible in compatible terminals."
+            ),
+        formatter_class=SmartDefaults,
+        epilog=(
+            "Agent interface (machine-readable JSON):\n"
+            "  viewinline result.tif --info                 # metadata + stats as JSON\n"
+            "  viewinline result.tif --export out.png       # save PNG, print {\"path\": ...}\n"
+            "  viewinline data.nc --info                    # list NetCDF variables\n"
+            "  viewinline data.nc --subset 7 --info         # inspect variable 7\n"
+            "  viewinline scene.hdf --subset 1 --info       # inspect HDF subdataset 1\n"
         ),
-        formatter_class=SmartDefaults
     )
 
 # File input
@@ -1682,6 +1960,11 @@ def main() -> None:
         "--gallery", nargs="?", const="4x4", metavar="GRID",
         help="Display all image files in a folder as thumbnails (e.g., --gallery 5x4). Incompatible files are skipped."
     )
+    general.add_argument("--info", action="store_true",
+    help="Print JSON metadata (format, CRS, dims, stats) and exit. Agent-facing.")
+    
+    general.add_argument("--export", metavar="PATH", default=None,
+    help="Also save the displayed image to PATH (.png/.jpg). Prints {\"path\": ...}.")
 
     # Raster options
     raster = parser.add_argument_group("Raster")
@@ -1827,6 +2110,28 @@ def main() -> None:
 
     paths = args.paths
 
+    if args.info:
+        if len(paths) != 1:
+            print(json.dumps({"error": "--info requires exactly one file"}))
+            sys.exit(1)
+        p = paths[0].lower()
+        vector_exts = (".shp", ".geojson", ".json", ".gpkg", ".parquet", ".geoparquet")
+        if p.endswith(".nc"):
+            sys.exit(print_netcdf_info(paths[0], subset=args.subset))
+        if p.endswith(vector_exts):
+            sys.exit(print_vector_info(paths[0]))
+        sys.exit(print_raster_info(paths[0], subset=args.subset))
+        
+    if args.export:
+        globals()["_EXPORT_PATH"] = args.export
+        import atexit
+        _real_stdout = sys.stdout
+        sys.stdout = sys.stderr  # send [DATA]/[INFO] logs to stderr, keep stdout clean
+        def _emit_export_json(_out=_real_stdout):
+            sys.stdout = _out
+            print(json.dumps(_EXPORT_RESULT or {"error": "no image rendered"}))
+        atexit.register(_emit_export_json)
+
     # File routing
     raster_exts = (".png", ".jpg", ".jpeg", ".tif", ".tiff", ".nc", ".hdf", ".hdf5", ".h5")
     vector_exts = (".shp", ".geojson", ".json", ".gpkg", ".parquet", "geoparquet")
@@ -1910,4 +2215,4 @@ def main() -> None:
 
 
 if __name__ == "__main__":
-    main()
+    main()