umbra-py

# umbra-py

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![CI](https://github.com/reesehammer/umbra-py/actions/workflows/ci.yml/badge.svg)](https://github.com/reesehammer/umbra-py/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/reesehammer/umbra-py/branch/main/graph/badge.svg)](https://codecov.io/gh/reesehammer/umbra-py)
[![Docs](https://img.shields.io/badge/docs-umbra--py.space-informational.svg)](https://umbra-py.space/)

**Search, preview, load, and convert [Umbra](https://umbra.space/open-data/) 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](https://umbra-py.space/)
· **Showcase:** [browse the archive in the browser](https://umbra-py.space/showcase/)
(no install)
· **Already listing the bucket?** [Replace your crawler](https://umbra-py.space/replace-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](https://api.umbra-py.space/)): best-effort
99% monthly uptime, no SLA, 120 requests/minute, page size 10,000.
[Limits, CORS, and the parquet fallback](https://umbra-py.space/hosted-limits/).

## Install

```bash
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](https://umbra-py.space/install/).

## 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.

```bash
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
```

```python
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](https://umbra-py.space/).

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

```python
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](https://umbra-py.space/guides/limitations/) and the
[complex-product handoff](https://umbra-py.space/guides/complex-downstream/).

**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](https://github.com/reesehammer/umbra-py/blob/main/examples/09_isr_training_set.ipynb)
and [Used in research](https://umbra-py.space/guides/research/).

**Drive it from an agent.** Copy-paste recipes for Claude Desktop and Claude
Code: [Connect Claude (MCP)](https://umbra-py.space/mcp/).

Zero-install remote MCP (no `uvx`):

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

```json
{
  "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):

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

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

That command is published to the [MCP registry](https://registry.modelcontextprotocol.io/)
as `io.github.reesehammer/umbra-mcp`. STAC for `pystac-client` / QGIS is
[https://api.umbra-py.space/](https://api.umbra-py.space/) (not `/mcp`).
`docker compose -f deploy/docker-compose.yml up` is the one-command self-host.

<!-- mcp-name: io.github.reesehammer/umbra-mcp -->

## 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 slant-plane image (NITF). Open archive: RGAZIM/PFA. | Phase-preserving downstream. Download; do not convert. |
| `CPHD` | Compensated phase history | Custom formation *outside* umbra-py (download; do not convert). Not an image. |

`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)](https://umbra-py.space/guides/complex-downstream/).

## 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](#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](LICENSE)). The two licenses
are independent and compatible.

## Citing umbra-py

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.TBD.svg)](https://doi.org/10.5281/zenodo.TBD)

`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](CITATION.cff)
(GitHub's **Cite this repository** button) and
[.zenodo.json](.zenodo.json) (what Zenodo archives).

```bibtex
@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](https://creativecommons.org/licenses/by/4.0/).
Umbra's
[terms](https://umbra.space/umbra-satellite-tasking-services-terms-and-conditions/)
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](https://umbra.space/open-data/).

## Repo layout

| Path | Role |
|------|------|
| `src/umbra_py/` | Package source |
| `docs/` | Published user manual (mkdocs → [umbra-py.space](https://umbra-py.space/)) |
| `docs/schemas/` | Public JSON contracts (also in the wheel) |
| `.github/TODO.md` | Maintainer ledger of scoped-out follow-ups |
| `deploy/` | Dockerfiles, `docker-compose.yml`, entrypoint |
| `railway.toml` | Railway Config-as-Code (`dockerfilePath` → `deploy/Dockerfile.mcp`) |

Self-host: `docker compose -f deploy/docker-compose.yml up` (build context stays the repo root). More in [`docs/README.md`](docs/README.md) and the [deploy guide](https://umbra-py.space/deploy/).

## Community

- [Contributing](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md) · [Security](SECURITY.md)
- [Example notebooks](examples/) · [Limitations](https://umbra-py.space/guides/limitations/)

## Acknowledgements

Built on the SAR open-source community, including
[`sarpy`](https://github.com/ngageoint/sarpy) and Umbra's open data program.
**Not affiliated with or endorsed by Umbra Lab, Inc.**