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）はインストールガイドに記載されています。

5 分でシーンを取得

週次カタログのスナップショットを取得し、オフラインで検索してプレビューします。バケットをリアルタイムに走査する方法（--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 で実行できます。

できること

詳細、オプション、注意事項については ドキュメントをご覧ください。

bbox、地名、ポリゴン、または 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 は数値をでっち上げず、エラーになります。制限事項および 複素プロダクトの引き渡しをご覧ください。

オープンな Umbra GEC/SICD から、SR / ATR 形式のベンチマーク用にシーンをジオリファレンス済み ML タイルへ分割します： umbra chips --area Centerfield --out chips/。ISR トレーニングセットのクックブック および研究での利用例をご覧ください。

エージェントから操作する。 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"]
    }
  }
}

このコマンドは MCP レジストリに io.github.reesehammer/umbra-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 は独自の出力にも、次の短い表記を追加します：

CC BY 4.0 ライセンスの Umbra オープンデータを含みます。

umbra-py 自体は Apache 2.0 ライセンスです（LICENSE）。2 つのライセンスは 互いに独立しており、併用できます。

umbra-py の引用

すべてのバージョンを引用する場合は、コンセプト DOI 10.5281/zenodo.23676715 （Zenodo の すべてのバージョンを引用？ の値）を使用してください。これは最新のアーカイブ済みリリースを示します。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-derived data © [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 Config-as-Code（dockerfilePath → deploy/Dockerfile.mcp）

セルフホストするには、docker compose -f deploy/docker-compose.yml up を実行します（ビルドコンテキストはリポジトリのルートのままです）。詳細は docs/README.md とデプロイガイドをご覧ください。

コミュニティ

• コントリビューション · 行動規範 · セキュリティ
• ノートブックの例 · 制限事項

謝辞

sarpy や Umbra のオープンデータプログラムを含む、SAR オープンソースコミュニティの成果を基盤としています。 Umbra Lab, Inc. とは提携しておらず、同社からの推奨も受けていません。