Items & collections¶
UmbraItem is the normalized view of one STAC item — its geometry, datetime,
polarizations, product types, and downloadable assets. ItemCollection is the
iterable of items a search returns.
dataclass
¶
UmbraItem(id, properties=dict(), assets=dict(), geometry=None, bbox=None, href=None, raw=dict(), place=None)
A single Umbra SAR acquisition, parsed from a STAC item.
property
¶
Free-text description of the acquisition, when the STAC item has one.
Checks the item's top-level description (STAC convention) and
properties.description, then falls back to the description on
the primary image asset (GEC) so popups can surface whatever
human-readable blurb the catalog provides.
property
¶
The Umbra task (AOI campaign) this acquisition belongs to.
Umbra files every pass of a site under one sar-data/tasks/<task>/
directory, so the task is the natural grouping for "the same place
over time". We read the task component straight from the item's
sidecar href (URL-decoded, e.g. "Centerfield, Utah"), since
that carries the human-friendly label; when no usable href is present
we fall back to the umbra:task_id property. Returns None when
neither is available.
property
¶
Map canonical product type -> actual STAC asset key.
When several assets share a product type (e.g. a primary SIDD and a Color Sub-aperture SIDD), the non-CSI "primary" asset is preferred.
property
¶
Canonical product types present on this item (e.g. GEC, SICD).
Return the download URL for a product type ("GEC") or asset key.
Umbra's published *.stac.v2.json sidecars reference assets either
with href="" or with an s3:// URL into a private processing
bucket -- neither is anonymously fetchable. In both cases the public
copy sits next to the sidecar in the open-data bucket, so we
reconstruct a public HTTPS URL: first relative to the item's own
sidecar href (which correctly handles named-task layouts like
tasks/<name>/<task_id>/<acq>/), then falling back to deriving from
umbra:task_id. Hrefs already pointing at http(s) are returned
unchanged.
Whether this item's footprint overlaps the given bounding box.
Whether this item's footprint intersects the given polygon geometry.
geometry is the exterior-ring form returned by
:func:umbra_py._geometry.parse_geometry (a list of rings). This uses
the item's actual footprint polygon when it has one -- a tighter test
than the bbox rectangle :meth:intersects_bbox uses -- and falls back
to the footprint bbox when the geometry is missing or not a polygon (and
matches nothing when neither is available).
Whether this item satisfies the SAR acquisition-property filters.
These are the first-class radar-discovery filters an analyst reaches for
beyond geography and date -- polarization, incidence angle and spatial
resolution -- read from the STAC sar:/view: properties the item
already parses (:attr:polarizations, :attr:incidence_angle,
:attr:resolution). Every argument is optional; a None/empty one is
no constraint, so a call with no arguments always returns True.
polarizations: keep the item if it exposes at least one of the requested polarizations (case-insensitive), e.g.["VV"]. This is the filter that keeps a change composite comparing like with like -- HH and VV image different scattering physics (see :data:~umbra_py.constants.POLARIZATION_CAVEAT).min_incidence/max_incidence: inclusive bounds on the view incidence angle in degrees.max_resolution: keep the item only if it is at least this fine -- both the range and azimuth resolution must be<= max_resolutionmetres.
Each filter is a hard predicate: when it is set, an item that lacks
the corresponding metadata is excluded (an absent value can't be
confirmed to match), matching the STAC Query-extension convention that a
property predicate does not select items missing that property. This is
deliberately unlike the geometric :meth:intersects_bbox /
:meth:intersects_polygon filters, which fall back to a coarser datum
when a footprint is missing: those have a fallback, these categorical /
numeric properties do not, so "present and satisfies" is the honest test.
No model is called and no new dependency is used -- pure metadata
comparison, so it is fully deterministic and offline-testable.
A compact, explanation-rich context card for prompting a model.
Like :meth:metadata_summary but tuned for a language model rather
than a human: every present product type carries a one-line
explanation, the polarizations carry the change-detection caveat, and
the mandatory CC-BY attribution line travels with the data. The
differences from metadata_summary are exactly the things a model
needs spelled out and a human already knows — so an agent can reason
about the scene, and cite the right product, with no external SAR
literacy. Deterministic and offline (no network, no model call).
Published as docs/schemas/item-context.schema.json -- the same card
umbra info --json prints, the agent tools return, and a watch delta
carries one of per new acquisition.
Return a GeoJSON Feature representing this item.
Convenience wrapper around :func:umbra_py.viz.item_to_feature so
users can call item.to_geojson() directly. The third coordinate
of 3D footprints is stripped so the feature renders cleanly in
standard 2D GIS tools.
Bases: list
A list of :class:UmbraItem that renders as a gallery in notebooks.
Behaves exactly like a list (it is one), so existing code that
iterates search results is unaffected. The extra is a Jupyter
_repr_html_ that lays the items out as a grid of metadata cards::
from umbra_py import UmbraCatalog, ItemCollection
results = ItemCollection(UmbraCatalog().search(area="rome", limit=8))
results # -> gallery of cards (offline, no extras needed)
Pass thumbnails=True to stream a small SAR quicklook for each item
(needs the viz extra). Thumbnails are fetched lazily when the
collection is displayed; any item that can't be previewed falls back to
its footprint card, so displaying the collection never raises.
GeoJSON helpers¶
Convert one UmbraItem to a GeoJSON Feature dict.
Properties include the compact metadata summary plus the item's STAC
URL (stac_href) so downstream tools can link back to the source.
Convert items to a single GeoJSON FeatureCollection dict.
Write items as a GeoJSON FeatureCollection to dest.