Umbra open SAR archive

umbra-py

搜索、预览、加载并转换 Umbra 开放 SAR 数据。

Umbra 将 16–25 cm SAR 作为 CC BY 4.0 开放数据发布，但没有搜索 API——只有一个超过 17 TB 的 S3 存储桶和一棵静态 STAC 树。umbra-py 正是为此提供的工具层：无需编写常见的 500 行胶水代码，即可搜索、预览、下载并获取可用于分析的数组。社区 STAC API（umbra serve）和 MCP 服务托管在同一主机上，因此无需安装任何内容，pystac-client 和 Claude 就能查询档案。

📖 文档： umbra-py.space · 示例： 在浏览器中浏览档案 （无需安装） · 已经在列出存储桶内容？ 替换你的爬虫 （通过 HTTP、pystac-client 或查询每周 Parquet 文件的 DuckDB）

状态： v0.1.4。已提供发现、下载、xarray 加载、 SICD → 地理编码 COG、变化／时间序列复合图、芯片、STAC API （umbra serve，带有社区托管服务）和 MCP 服务。它 不是 InSAR 工具箱（转换过程中不会保留相位）。与 Umbra Lab, Inc. 无关。

托管 API（api.umbra-py.space）：尽力保证 每月 99% 可用性，无 SLA，每分钟 120 个请求，页面大小为 10,000。 限制、CORS 和 Parquet 备用方案。

安装

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+。其他可选依赖（dask、serve、mcp、ai、langchain、 llamaindex）请参阅安装指南。

五分钟获取一个场景

获取每周目录快照，然后离线搜索和预览。实时遍历存储桶 （运行不带 --local 的 umbra search）也可行，但速度较慢。

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())

如果缺少快照，可使用 UmbraCatalog().search(...) / umbra search --area Centerfield 对实时存储桶执行同样的搜索。

可以做什么

更多详情、选项和注意事项请参阅 文档。

按边界框、地点名称、多边形或 Umbra 任务进行搜索（area=）。 --local 会读取快照；省略此参数则会遍历 S3。

from umbra_py import UmbraCatalog

for item in UmbraCatalog().search(area="Centerfield", product_types=["GEC"], limit=5):
    print(item.summary())

无需下载场景即可预览：umbra gallery、umbra quicklook <stac-url> --out scene.png --db、umbra view <stac-url>（全分辨率瓦片）， 或 umbra change --area Centerfield --out change.png。

将地理编码 GEC 载入 xarray 或 GeoTIFF（to_xarray、to_geotiff、 to_stack）。需要 [load]。

将 SICD 转换为北向朝上的振幅 COG（sicd_to_geocoded_cog、 umbra convert）——相位会被丢弃。需要 [convert]。开放产品通常没有辐射元数据，因此 --calibrate / --noise-model measured 会拒绝处理，而不会编造数值。请参阅 限制和 复数产品交接指南。

将场景切片为地理参考 ML 瓦片，用于基于开放 Umbra GEC/SICD 的 SR / ATR 类基准测试： umbra chips --area Centerfield --out chips/。请参阅 ISR 训练集指南 和研究应用。

通过 Agent 驱动。 Claude Desktop 和 Claude Code 的复制粘贴配置示例：连接 Claude（MCP）。

零安装远程 MCP（无需 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"
    }
  }
}

将该 JSON 粘贴到 Claude Desktop（claude_desktop_config.json）。Claude Code 需要在同一 URL 上设置 "type": "http"——请参阅 MCP 页面。

本地 stdio（服务运行在你的计算机上）：

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

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

该命令已作为 io.github.reesehammer/umbra-mcp 发布到 MCP 注册表。 供 pystac-client / QGIS 使用的 STAC 地址为 https://api.umbra-py.space/（不是 /mcp）。 docker compose -f deploy/docker-compose.yml up 是一键自托管命令。

数据的样子

资产	内容	用途
GEC	地理编码的云优化 GeoTIFF	可直接用于地图的影像。从这里开始。
CSI	彩色子孔径 GeoTIFF	快速查看 RGB，并非测量数据
SIDD	地理编码的检测图像（NITF）	标准格式的检测影像
SICD	复数斜距平面图像（NITF）。开放存档格式：RGAZIM/PFA。	保留相位的下游处理。下载；不要转换。
CPHD	补偿相位历史数据	在 umbra-py 之外 自行形成图像（下载；不要转换）。不是图像。

umbra-py 会下载 SICD/CPHD。umbra convert 会将 SICD 地理编码为 振幅并丢弃相位。它不会形成干涉图或 计算相干性。如需处理复数像素的处理器，请参阅 复数产品（SICD/CPHD）。

数据许可与署名

Umbra 的影像采用 CC BY 4.0 许可。如果你使用或再分发数据或 衍生产品，必须注明 Umbra。Umbra 条款要求的版权声明摘录见引用 umbra-py。 umbra-py 也会在其自身输出中附上以下简短声明：

包含 Umbra 开放数据，采用 CC BY 4.0 许可。

umbra-py 本身采用 Apache 2.0 许可（LICENSE）。这两种许可证 彼此独立且兼容。

引用 umbra-py

引用所有版本时，请使用概念 DOI 10.5281/zenodo.23676715 （Zenodo 的 引用所有版本？ 值）。该 DOI 会指向最新归档版本。v0.1.4 版本的 DOI 是 10.5281/zenodo.23676716。 机器可读的元数据位于 CITATION.cff （GitHub 的 引用此仓库 按钮）和 .zenodo.json（Zenodo 归档的内容）中。

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

影像版权归 Umbra Space 所有，依据 CC BY 4.0 许可。 Umbra 的 条款 要求在改编材料上或其附近注明此版权声明，其中 [YEAR] 为图像首次创建的年份：

SAR 派生数据 © [YEAR] Umbra Lab, Inc.

还需注明 Umbra、链接至许可证，并说明是否修改了数据。开放数据计划详见 umbra.space/open-data。

仓库结构

路径	用途
src/umbra_py/	软件包源代码
docs/	已发布的用户手册（mkdocs → umbra-py.space）
docs/schemas/	公开的 JSON 契约（也包含在 wheel 中）
.github/TODO.md	维护者记录的范围外后续事项
deploy/	Dockerfile、docker-compose.yml、入口点
railway.toml	Railway 配置即代码（dockerfilePath → deploy/Dockerfile.mcp）

自托管：运行 docker compose -f deploy/docker-compose.yml up（构建上下文仍为仓库根目录）。更多信息请参阅 docs/README.md 和部署指南。

社区

• 贡献指南 · 行为准则 · 安全
• 示例笔记本 · 限制

致谢

本项目基于 SAR 开源社区的成果构建，包括 sarpy 和 Umbra 的开放数据计划。 本项目与 Umbra Lab, Inc. 无关联，也未获其认可。