geotessera copilot-instructions.md

GitHub Copilot Instructions for GeoTessera

Project Overview

GeoTessera is a Python library for accessing and working with Tessera geospatial foundation model embeddings. The library provides tools to download, process, and visualize satellite imagery embeddings from Sentinel-1 and Sentinel-2 data at 10m resolution.

Core Architecture

• Two-step workflow: Retrieve embeddings (numpy arrays) → Export to desired format (GeoTIFF/NPY)
• Registry system: Parquet-based metadata registry for efficient tile lookup
• 0.1-degree grid: Tiles cover ~11km × 11km, named by center coordinates
• Direct HTTP downloads: On-demand tile fetching with automatic cleanup
• Hash verification: SHA256 checksums ensure data integrity by default

Technology Stack

Core Dependencies

• Python: 3.12 or 3.13 required (requires-python = ">=3.12")
• CLI Framework: typer with rich for interactive output
• Geospatial: rasterio, geopandas, rioxarray for GIS operations
• Data Processing: numpy, pandas, pyarrow (for Parquet registry)
• Visualization: matplotlib, scikit-learn (PCA), scikit-image
• Storage: zarr, xarray, dask for chunked data handling

Build System

• Package Manager: Uses uv for dependency management (preferred) or pip
• Configuration: pyproject.toml with setuptools backend
• Lock File: uv.lock for reproducible builds
• Test Framework: cram (shell-based functional testing)
• Linting: ruff for code quality

Coding Standards

Python Style

• Follow PEP 8 conventions
• Use type hints for function signatures (e.g., Optional[str], Path, etc.)
• Use typing_extensions.Annotated for CLI argument annotations with typer
• Prefer pathlib Path over string paths
• Use f-strings for string formatting

Code Organization

geotessera/
├── __init__.py          # Package exports and version
├── core.py              # Main GeoTessera class
├── registry.py          # Parquet registry management
├── cli.py               # Main CLI commands
├── registry_cli.py      # Registry-specific CLI
├── store.py             # Zarr v3 store access (GeoTesseraZarr)
├── tiles.py             # Tile abstraction (GeoTIFF + NPY)
├── visualization.py     # Visualization functions
├── web.py              # Web map generation
├── country.py          # Country bounding box utilities
└── progress.py         # Progress tracking utilities