ucam-eo/geotessera

GeoTessera – Python library for Earth‑satellite embeddings

What it does

• Provides programmatic access to Tessera embeddings, a pixel‑wise Earth‑foundation model that turns a year of Sentinel‑1/2 imagery into a 128‑channel vector for every 10 m pixel.
• The library can stream embeddings directly from a cloud‑hosted Zarr store or download them as GeoTIFF/NumPy tiles for offline work.
• Includes a CLI (geotessera) for common tasks: download a region, visualise with PCA, generate web‑map tiles, and inspect data coverage.

How you use it

1. Install with pip install geotessera (Python 3.12+).
2. Create a client, e.g. gt = GeoTesseraZarr().
3. Query points (gt.probe(lon, lat, year)) or whole regions (gt.read_region(bbox, year)).
4. Export the results as GeoTIFFs (gt.export_geotiffs(...)) or NumPy arrays.
5. Optionally run the CLI:

   geotessera download --bbox '-3,53.4,-2.9,53.5' --year 2024 --output region/
   geotessera webmap --bbox '-3,53.4,-2.9,53.5' --year 2024 --output map/ --serve
   

Key technical bits

• Zarr backend: reads only the needed byte‑ranges, de‑quantises int8 values with per‑pixel scale factors, and returns float‑32 vectors on the native UTM grid.
• Tile system: 0.1° × 0.1° tiles (~11 km) stored as quantised .npy plus scale files; land‑mask tiles give correct georeferencing.
• Registry: a Parquet manifest per dataset version (v1.1, v2) lists available tiles, enabling fast spatial/temporal look‑ups.
• Metadata safety: each export writes tessera_metadata.json and tags GeoTIFFs with dataset version; mixing versions is prevented.
• Agent Skill: an optional skill for Claude‑Code agents to learn the Zarr API.

When to pick GeoTessera

• You need dense, multi‑spectral embeddings for large‑scale Earth‑observation analysis (e.g., land‑cover change, climate modelling, agricultural monitoring).
• You prefer not to download the whole global dataset; the streaming Zarr API pulls only the region you need.
• You work in Python/GIS environments and want ready‑made GeoTIFFs or web‑map tiles.

Limitations / current state

• v2 embeddings are still being generated on demand; turnaround may be slow.
• Tile‑based downloads (--source tiles) are deprecated and will be removed.
• Some artefacts from Sentinel acquisition geometry remain; they are documented but not fully removable.

Where to learn more

• Full docs: https://geotessera.readthedocs.io
• Model paper: TESSERA v2: Scaling Pixel‑wise Earth Foundation Models (arXiv:2607.03949)
• Example notebooks: https://github.com/ucam-eo/geotessera-examples

---

All information above is taken directly from the repository’s README.