Skip to content

Limitations

Honest bounds on what v0.1.0 will and will not do. Silent errors are easy in SAR; this page is the list of things the library refuses, approximates, or has not yet checked on real products.

Not an InSAR toolbox

SICD and CPHD are classified and downloadable. That is the whole phase-preserving path in umbra-py: search, size-check, download, stop.

CPHD is compensated phase history for formation elsewhere (a GPU backprojector, a custom former, sarpy). umbra-py does not form an image from it and does not run backprojection. umbra convert does not read CPHD. A former that writes a SICD can be geocoded afterwards; that step still detects amplitude and drops phase. FastSAR 0.2.0 process_cphd is one such former — see Complex products (SICD/CPHD).

umbra convert detects amplitude from SICD and writes a geocoded GeoTIFF — the phase is discarded. There is no interferogram, no coherence, no perpendicular-baseline filter, and no PFA → range-Doppler rewrite.

Open Umbra SICDs are spotlight / RGAZIM / Polar Format (PFA), not Capella-style RGZERO stripmap. A processor that only ingests RGZERO should reject them. If you need the complex pixels, download the SICD (or CPHD) and hand it to sarpy or another downstream tool — see Complex products (SICD/CPHD).

Radiometry on the open archive

Umbra's open SICDs generally ship without a Radiometric block.

  • --calibrate sigma0|beta0|gamma0|rcs refuses when the product cannot support it. It does not invent a scale factor.
  • --noise-model measured refuses when there is no ABSOLUTE NoisePoly.
  • --noise-model estimated / estimated-range infer a floor from the scene's dark tail. The arithmetic is tested on synthetic data. They have not been compared to a real product that carries a measured floor (that needs a Canopy scene or equivalent).

A published GEC is already a geocoded GeoTIFF. Its pixels are relative amplitude, not a calibrated backscatter coefficient. Open GEC is 8-bit display-scaled data with nodata 0 and a floor at DN 1. Mask nodata 0 before a threshold or a statistic, and use SICD or CSI when dynamic range matters.

Search is a crawl unless you fetch the index

There is no STAC API on the open bucket. UmbraCatalog.search paginates S3 listings and is slow on an unconstrained query — that is why umbra index fetch / CatalogIndex.from_release() exist, and why the community umbra serve --public host exists (see Deploy). Prefer --local for anything you will run more than once.

area= on the library and the CLI is a task-directory name, not a geocoded place. --place geocodes via Nominatim to a rectangle, so it can include nearby ground outside the named place. GET/POST /search and /sites (and the MCP tools search_catalog and find_repeat_sites) fall back to that geocoder when area= matches no task name and no bbox or polygon was given. The response then says matched_by: geocode. A name Nominatim does not know is an empty result with hint no task named X; try place= or bbox=. When the geocoder is busy or unreachable, that same empty result (HTTP 200 on /search and /sites) carries hint no task named X; geocoding was unavailable. A task-name hit is unchanged. The resolved box is cached in-process, including on a local umbra serve, so the next page does not call Nominatim again.

The index is what Umbra has published, rebuilt weekly. umbra index info (and index_stats) report built_at and end, the newest plausible acquisition. As of 2026-10-14 the published snapshot was built 2026-10-08 and its newest plausible acquisition is 2026-09-13 (Nepal disaster coverage). Umbra open data arrives in irregular batches. A gap of weeks between that acquisition and today is normal, and it is not an umbra-py lag.

A few upstream items carry impossible future dates (a task-data collect dated 2036-07-24, and others in 2035). umbra index build quarantines a datetime before 2018-01-01 or more than a day after the build and reports how many in quarantined_future_count — those rows are not in the index. A datetime that is after the item's own properties.created, or after built_at when created is missing, but still inside that window is kept, flagged datetime_suspect, and left out of end, rank_by=recency, and other latest-pass selections. The datetime is not rewritten.

Open-data timestamps are not delivery latency

The catalog index (schema version 6) stores two times beside datetime, the acquisition time:

  • created is STAC properties.created when the sidecar has it. Legacy _METADATA.json collects do not. created minus datetime is the lag until Umbra generated the STAC record, not tasking delivery latency.
  • published is the S3 LastModified of the sidecar object. The crawl already sees it in ListObjectsV2, so filling it costs no extra request. It is when that object appeared in the public bucket.

Open data is a curated, batch-published subset. A task's collects can land in the bucket together, weeks after they were acquired. Neither field is a commercial delivery-latency measurement. umbra serve passes created through as properties.created and published as properties["umbra-py:published"].

Canopy is the same interface, not a live-verified client

UmbraCatalog(token=...) / umbra search --token posts to Canopy's STAC API. The client is built to the STAC API standard and tested against a mock. Request/response shapes have not been confirmed against the live API; product_types and area are still applied client-side.

Convert is a toolkit, not MultiRTC

Terrain orthorectification, four RTC models (including a plane-wave image-space "facet" approximation of Small 2011), speckle filters, and clipping all ship. They are exercised offline with fakes and synthetic arrays. They have not been cross-checked against MultiRTC. Over extreme relief, or when you need a survey-grade RTC product, compare before you publish numbers.

Community STAC API, not an Umbra product

Umbra's open catalog is still a static tree with no official search API. umbra serve --public (https://api.umbra-py.space/) is an unofficial community instance: STAC search + MCP on one URL, on-demand artifact routes off so this host does not proxy rasters, a per-client rate limit, and CC-BY license headers. Product hrefs point at Umbra's public bucket — stream them yourself. Baked thumbnails are the exception: GET /artifacts/thumbnail/{item_id}.png serves a PNG already on the host, and an item with a bake advertises it as assets.thumbnail. An item with no bake has no thumbnail; show a placeholder. See Hosted API limits. A browser fetch() of GET /search is From a browser; open data is published in batches, so a last-7-days or last-30-days query is usually empty. Do not set a Canopy token or a model key on that instance. See Deploy.

AI is opt-in and never implicit

umbra ask, describe, embed, and change --narrate call a model only when you invoke them and have configured a key. Model output is re-validated or provenance-stamped; it never becomes a coordinate, URL, or filter on its own. The core search / download / render path never calls a model.