umbra-py

umbra-py

A Python toolkit to discover, preview, load, and analyze Umbra open SAR data.

Umbra publishes 16–25 cm synthetic aperture radar as CC BY 4.0 open data, but there is no search API — only a 17+ TB S3 bucket and a static STAC tree. umbra-py is the missing layer: search, preview, download, and analysis-ready arrays without writing the same 500 lines of glue first.

📖 Docs: umbra-py.space · Showcase: browse the archive in the browser (no install)

Status: v0.1.1. Discovery, download, xarray loading, SICD → geocoded COG, change/timescan composites, chips, a local STAC API, and an MCP server all ship. This is not an InSAR toolbox (phase is not preserved through convert). Not affiliated with Umbra Lab, Inc.

Install

pip install umbra-py              # core: search + download + metadata
pip install "umbra-py[load]"      # + xarray / rasterio
pip install "umbra-py[viz]"       # + quicklooks, maps, galleries
pip install "umbra-py[convert]"   # + SICD → geocoded COG
pip install "umbra-py[all]"       # convert + load + viz + export

Python 3.10+. Other extras (dask, serve, mcp, ai, langchain, llamaindex) are listed in the install guide.

Five minutes to a scene

Fetch the weekly catalog snapshot, then search and preview offline. A live walk of the bucket (umbra search without --local) works but is slow.

pip install "umbra-py[viz,load]"
umbra index fetch
umbra search --local --area Centerfield --product GEC --limit 3
umbra gallery --local --area Centerfield --limit 6 --out gallery.html --db

from umbra_py import CatalogIndex, to_xarray

with CatalogIndex.from_release() as index:
    item = next(iter(index.search(area="Centerfield", product_types=["GEC"], limit=1)))

# Stream a downsampled window over HTTP — no multi-GB download. Needs [load].
da = to_xarray(item, max_size=1024, db=True)
print(item.summary())

If the snapshot is missing, the same search against the live bucket is UmbraCatalog().search(...) / umbra search --area Centerfield.

What you can do

More detail, options, and caveats live in the docs.

Search by bbox, place name, polygon, or Umbra task (area=). --local reads the snapshot; omit it to walk S3.

from umbra_py import UmbraCatalog

for item in UmbraCatalog().search(area="Centerfield", product_types=["GEC"], limit=5):
    print(item.summary())

Preview without downloading the scene: umbra gallery, umbra quicklook <stac-url> --out scene.png --db, umbra view <stac-url> (full-res tiles), or umbra change --area Centerfield --out change.png.

Load a geocoded GEC into xarray or a GeoTIFF (to_xarray, to_geotiff, to_stack). Needs [load].

Convert a SICD to a north-up COG (sicd_to_geocoded_cog, umbra convert). Needs [convert]. Open products generally have no radiometric metadata, so --calibrate / --noise-model measured refuse rather than invent numbers. See limitations.

Chip scenes into georeferenced ML tiles: umbra chips --area Centerfield --out chips/.

Drive it from an agent. Zero-install MCP server:

uvx --from 'umbra-py[mcp]' umbra-mcp

{
  "mcpServers": {
    "umbra": {
      "command": "uvx",
      "args": ["--from", "umbra-py[mcp]", "umbra-mcp"]
    }
  }
}

That command is published to the MCP registry as io.github.reesehammer/umbra-mcp. A local STAC API is umbra serve (needs [serve]); docker compose up is the one-command form. There is no public hosted instance yet.

What the data looks like

Asset	What it is	Use it for
GEC	Geocoded cloud-optimized GeoTIFF	Map-ready imagery. Start here.
CSI	Color sub-aperture GeoTIFF	Quick-look RGB, not a measurement
SIDD	Geocoded detected image (NITF)	Detected imagery in a standard format
SICD	Complex data in the radar slant plane (NITF)	Phase-preserving work, InSAR inputs
CPHD	Compensated phase history	Custom image formation

umbra-py downloads SICD/CPHD and can geocode a SICD to amplitude. It does not form interferograms or compute coherence.

Data license & attribution

Umbra's imagery is CC BY 4.0. If you use or redistribute the data or derived products you must attribute Umbra, e.g.:

Contains Umbra open data, licensed under CC BY 4.0.

umbra-py itself is Apache 2.0 (LICENSE). The two licenses are independent and compatible.

Citing umbra-py

Machine-readable metadata lives in CITATION.cff. GitHub renders it as a "Cite this repository" button. Please also honor the CC BY 4.0 line above for any Umbra data you use.

Community

• Contributing · Code of Conduct · Security
• Example notebooks · Limitations

Acknowledgements

Built on the SAR open-source community, including sarpy and Umbra's open data program. Not affiliated with or endorsed by Umbra Lab, Inc.