tessera

Tessera Embeddings Skill

geotessera CLI、Python ライブラリ、または R ライブラリを使って、TESSERA の衛星エンベディングを扱います。

このスキルの用途

以下の作業が必要な場合に、このスキルを使用します。

• TESSERA のエンベディングが存在する場所を確認する
• bbox または地域ファイルのエンベディングをダウンロードする
• ポイント位置のエンベディングをサンプリングする（Python/R ライブラリ）
• 高密度のラスタ解析用にモザイクを作成する（Python ライブラリ）
• GeoTIFF、NPY、Zarr の出力形式を選択する
• レジストリとキャッシュの動作を設定する
• ダウンロードした出力をローカルでプレビューまたは配信する

インストール

pip install geotessera                              # Python library + CLI

remotes::install_github("lassa-sentinel/GeoTessera") # R library

主な概念

• エンベディングは、ピクセルあたり解像度 10m の 128 チャネルの高密度ベクトルです
• タイルは 0.1° × 0.1°（約 11km × 11km）で、量子化された int8 と float32 のスケール値として保存されます
• Parquet レジストリ（数 MB 程度）はローカルにキャッシュされ、タイルは必要に応じて取得されます
• 高レベル API のすべてのメソッドは、逆量子化された float32 配列を返します
• ハッシュ検証はデフォルトで有効です

ポイントとモザイク — 適切な方法を選ぶ

ほとんどのタスクでは sample_embeddings_at_points() を優先してください。 必要なタイルのみをダウンロードし、コンパクトな (N, 128) 配列を返します。ラベル付きサイトの抽出、検証、スパースな分類、および特定の座標があるワークフローに使用します。

ピクセル単位で高密度なカバレッジが必要な場合に限り、fetch_mosaic_for_region() を使用してください（例：領域全体の土地被覆分類や、連続したエリアの空間クラスタリング）。モザイクは bbox 内のすべてのタイルを結合して再投影し、1 つの大きな配列にするため、広い地域ではメモリを大量に消費します。

Have specific point locations?
  YES → sample_embeddings_at_points()
  NO  → Need wall-to-wall raster output?
          YES → fetch_mosaic_for_region()
          NO  → CLI download + export

Python ライブラリ

from geotessera import GeoTessera

gt = GeoTessera()  # uses default registry and current directory

# --- Point sampling (preferred for most tasks) ---
points = [(0.15, 52.05), (0.25, 52.15), (-1.3, 51.75)]
embeddings = gt.sample_embeddings_at_points(points, year=2024)
# Returns: (N, 128) float32 array, NaN for missing points

# With metadata (tile info, pixel coordinates, CRS)
embeddings, metadata = gt.sample_embeddings_at_points(
    points, year=2024, include_metadata=True
)

# --- Mosaic (dense raster analysis only) ---
bbox = (-0.2, 51.4, 0.1, 51.6)
mosaic, transform, crs = gt.fetch_mosaic_for_region(bbox, year=2024)
# Returns: (H, W, 128) float32 array

# --- Single tile ---
embedding, crs, transform = gt.fetch_embedding(lon=0.15, lat=52.05, year=2024)
# Returns: (H, W, 128) float32, CRS, Affine transform

# --- Export ---
gt.export_embedding_geotiff(lon=0.15, lat=52.05, output_path="tile.tif", year=2024)
gt.export_embedding_zarr(lon=0.15, lat=52.05, output_path="tile.zarr", year=2024)

# --- Registry queries ---
gt.registry.get_available_years()           # [2017, 2018, ..., 2025]
gt.registry.get_tile_counts_by_year()       # {2024: 1234567, ...}
tiles = gt.registry.load_blocks_for_region(bounds=bbox, year=2024)

ポイント入力には、(lon, lat) タプルのリスト、GeoJSON FeatureCollection、または GeoPandas GeoDataFrame を指定できます。

R ライブラリ

Simon Frost（Microsoft Research）による R 移植版です。R6 クラス、sf、terra、arrow を使用します。

remotes::install_github("lassa-sentinel/GeoTessera")
library(GeoTessera)

gt <- geotessera()
tiles <- gt$get_tiles(bbox = c(-0.2, 51.4, 0.1, 51.6), year = 2024)
gt$export_embedding_geotiffs(tiles = tiles, output_dir = "london_tiles")

R のドキュメント全文：https://lassa-sentinel.github.io/GeoTessera

CLI ワークフロー

1. 最初にカバレッジを確認する

geotessera coverage --output coverage_map.png
geotessera coverage --year 2024 --country uk

2. 地域のデータをダウンロードする

geotessera download --bbox "-0.2,51.4,0.1,51.6" --year 2024 --output ./tiffs
geotessera download --region-file cambridge.geojson --year 2024 --output ./tiffs

3. 出力形式を選ぶ

geotessera download --bbox "..." --format tiff --year 2024 --output ./tiffs  # GIS-ready
geotessera download --bbox "..." --format npy  --year 2024 --output ./arrays # ML-friendly
geotessera download --bbox "..." --format zarr --year 2024 --output ./zarr   # cloud-native

4. 必要に応じてバンドを選択する

geotessera download --bbox "..." --bands "0,1,2" --year 2024 --output ./subset

5. 可視化または配信する

geotessera visualize ./tiffs --type web --output ./web
geotessera serve ./web --open

ヒント

• 位置がまばらな場合は、モザイクより sample_embeddings_at_points() を優先してください
• CLI で大量にダウンロードする前に、coverage を実行してください
• GIS ですぐに使える出力には --format tiff を、配列を中心とする ML には --format npy を使用してください
• 必要なチャネルが少数のみの場合は、--bands を使用して出力サイズを削減してください
• --year は明示的に指定してください。データは 2017 年から 2025 年まで利用できます
• 再現性を確保するため、固定のレジストリパスまたは URL を使用してください

よくある間違い

間違い	修正方法
少数のポイントを抽出するだけなのにモザイクを作成する	代わりに sample_embeddings_at_points() を使用します
必要なバンドが少数のみなのに 128 バンドすべてをダウンロードする	--bands（CLI）または bands パラメーターを使用します
大規模なダウンロードの前にカバレッジを確認しない	最初に geotessera coverage を実行します
--year を指定せず、デフォルトの年が適用される	必ず --year を明示的に指定します

参考資料

• references/geotessera-cli.md — CLI フラグの詳細なリファレンス
• references/geotessera-library.md — Python ライブラリ API のリファレンス