umbra-py

Search, preview, load, and convert Umbra open SAR data.

Umbra publishes 16–25 cm SAR as CC BY 4.0 open data, but no search API — only a 17+ TB S3 bucket and a static STAC tree. umbra-py is that layer: search, preview, download, and analysis-ready arrays without the usual 500 lines of glue. A community STAC API (umbra serve) and MCP server sit on the same host, so pystac-client and Claude can query the archive with nothing installed.

📖 Docs: umbra-py.space · Showcase: browse the archive in the browser (no install) · Already listing the bucket? Replace your crawler (HTTP, pystac-client, or DuckDB over the weekly Parquet)

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

Hosted API (api.umbra-py.space): best-effort 99% monthly uptime, no SLA, 120 requests/minute, page size 10,000. Limits, CORS, and the parquet fallback.

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 amplitude COG (sicd_to_geocoded_cog, umbra convert) — phase is discarded. Needs [convert]. Open products generally have no radiometric metadata, so --calibrate / --noise-model measured refuse rather than invent numbers. See limitations and the complex-product handoff.

Chip scenes into georeferenced ML tiles for SR / ATR-style benchmarks from open Umbra GEC/SICD: umbra chips --area Centerfield --out chips/. See the ISR training-set cookbook and Used in research.

Drive it from an agent. Copy-paste recipes for Claude Desktop and Claude Code: Connect Claude (MCP).

Zero-install remote MCP (no uvx):

# Claude Code
claude mcp add --transport http umbra https://api.umbra-py.space/mcp --scope user

{
  "mcpServers": {
    "umbra": {
      "url": "https://api.umbra-py.space/mcp"
    }
  }
}

Paste that JSON into Claude Desktop (claude_desktop_config.json). Claude Code needs "type": "http" on the same URL — see the MCP page.

Local stdio (server on your machine):

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. STAC for pystac-client / QGIS is https://api.umbra-py.space/ (not /mcp). docker compose -f deploy/docker-compose.yml up is the one-command self-host.

What the data looks like

umbra-py downloads SICD/CPHD. umbra convert geocodes a SICD to amplitude and discards phase. It does not form interferograms or compute coherence. For a processor that needs the complex pixels, see Complex products (SICD/CPHD).

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. The copyright notice Umbra's terms require is quoted under Citing umbra-py. umbra-py also stamps this shorter line on its own outputs:

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

10.5281/zenodo.TBD is a placeholder. After the first Zenodo-archived release, replace it with the concept DOI (Zenodo's Cite all versions? value). Machine-readable metadata lives in CITATION.cff (GitHub's Cite this repository button) and .zenodo.json (what Zenodo archives).

@software{hammerstrom2026umbrapy,
  author  = {Hammerstrom, Reese},
  title   = {umbra-py},
  year    = {2026},
  version = {0.1.3},
  doi     = {10.5281/zenodo.TBD},
  url     = {https://github.com/reesehammer/umbra-py},
  license = {Apache-2.0}
}

Imagery is © Umbra Space, licensed CC BY 4.0. Umbra's terms require this copyright notice on or adjacent to adapted materials, with [YEAR] the year the image was first created:

SAR-derived data © [YEAR] Umbra Lab, Inc.

Also credit Umbra, link the license, and say if you changed the data. The open-data program is umbra.space/open-data.

Repo layout

Self-host: docker compose -f deploy/docker-compose.yml up (build context stays the repo root). More in docs/README.md and the deploy guide.

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.