tessera

Tessera 嵌入向量技能

通过 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 中的所有瓦片，形成一个大型数组，因此处理大型区域时会占用大量内存。

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 FeatureCollections 或 GeoPandas GeoDataFrames。

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 参考