Skip to content

Download

Resume-safe HTTPS downloads with integrity verification: a short read or a mid-stream break keeps the .part for resume, a changed object restarts cleanly, and the finished file is hashed against the object's ETag.

By filename or acquisition stem

umbra info and umbra download take a sidecar URL (*.stac.v2.json, or a legacy *_METADATA.json for 2023 to 2024 collects). They also take a GEC/SICD filename or the acquisition stem once a local catalog index is present (umbra index fetch):

umbra index fetch
umbra info 2025-05-17-17-43-46_UMBRA-08_GEC.tif
umbra info 2025-05-17-17-43-46_UMBRA-08
umbra download 2025-05-17-17-43-46_UMBRA-08 --asset GEC --dest ./downloads

The stem is YYYY-MM-DD-HH-MM-SS_UMBRA-NN. A product file is that stem plus a suffix such as _GEC.tif or _SICD.nitf. The same string is published under sar-data/tasks/, sar-data/task-data/, or open-data/, and the filename does not say which, so the lookup matches the stem against asset hrefs in the index. Nothing matched is an error. More than one match lists the candidate STAC URLs; pass one of those to either command.

The MCP get_item and download_asset tools accept the same filename or stem in their url argument. umbra quicklook, umbra view, and umbra load still take a sidecar URL, not a filename.

Which file

--asset (repeatable) accepts three names for the same bytes:

  • a product type, any case (GEC, gec, SICD) — the primary file of that type
  • a schema v2 key, including a suffix (gec, gec_2, csi_sidd, metadata, di_gif, file_tif)
  • the original filename (umbra-py:filename), such as ..._GEC.tif

gec_2 is a second GEC, not an alias of gec. Omit --asset to download every product type present (one primary file each). A name that is not on the item lists the v2 keys that are (gec, gec_2, sicd), not the uppercase product types.

The MCP download_asset tool uses the same asset names. Its url is a STAC JSON URL, or the filename or stem above.

item.asset_href("gec")
item.asset_href("gec_2")
item.asset_href("2025-05-17-17-43-46_UMBRA-08_GEC.tif")

download_item 

download_item(item, dest_dir='.', assets=None, **kwargs)

Download several assets of an item.

Each name is resolved like :meth:UmbraItem.asset_href: a product type in any case, a schema v2 key (gec, gec_2, file_tif), or the original filename. Defaults to every product type present (one primary file each).

download_asset 

download_asset(item, asset, dest_dir='.', **kwargs)

Download one asset of an item.

asset is a product type in any case ("GEC"), a schema v2 key ("gec", "gec_2", "csi_sidd", "file_tif"), or the original filename (umbra-py:filename).

download_url 

download_url(url, dest, *, overwrite=False, resume=True, verify=True, session=None, progress=None, max_bytes=None)

Stream url to dest.

dest may be a directory (the filename is the URL's basename; see :func:_filename_from_url) or a full file path. A trailing path separator means a directory even when it does not exist yet. The file is refused when that basename is unsafe or the resolved path leaves the directory. Partial downloads are written to a .part sidecar and resumed via an HTTP Range request when resume is true.

When verify is true (the default) and the server exposes a single-part S3 ETag (the object's hex MD5), the finished file is hashed and compared against it, so on-the-wire corruption a correct byte count can't catch fails loudly. Multipart ETags ("<hash>-<n>") are not a plain MD5 and are skipped.

max_bytes, when set, refuses a transfer larger than that many bytes (Content-Length when the server sends one, and the bytes actually read either way). An existing finished file is still returned when overwrite is false; the cap applies to a transfer.