CLI Reference

GeoTessera provides a comprehensive command-line interface for downloading, visualizing, and serving Tessera embeddings.

Global Options

Data-fetching commands (download, coverage, info) share the dataset-selection options:

--dataset-version TEXT    Tessera dataset version (default: v1).
                          Accepts v1, 1.0, v1.0, v1.1, 1.1 etc.
--dataset-variant TEXT    Tessera dataset variant (default: vultr).
                          Known variants: vultr (1.0 default), cambridge (1.1).
--verbose, -v             Enable verbose output
--help                    Show help message

The download and coverage commands additionally accept manifest location overrides (info does not):

--cache-dir PATH          Custom cache directory for the manifest
--registry-dir PATH       Directory containing manifest.parquet + landmasks.parquet

To point at a single local manifest file from Python, use the GeoTessera(registry_path=...) parameter (there is no equivalent CLI flag).

Note

Dataset versions and variants: there are now two Tessera versions on S3 (1.0 and 1.1). Prefer 1.1 / cambridge for new work — the legacy 1.0 line is frozen. Never mix versions or variants within the same downstream task — they are independently learned feature spaces and not interchangeable. See Dataset Versions and Variants in the main index for the full picture.

Cache Configuration

Control where the Parquet manifest is cached:

# Use custom cache directory for the per-version manifest
geotessera download --cache-dir /path/to/cache ...

# Use a locally-supplied manifest (e.g. a checked-in offline copy)
geotessera download --registry-path /path/to/manifest.parquet ...

# Default cache locations (if not specified):
# - Linux/macOS: ~/.cache/geotessera/{v1,v1.1}/manifest.parquet
# - Windows:     %LOCALAPPDATA%/geotessera/{v1,v1.1}/manifest.parquet

Note: Embedding tiles land in the user-supplied --output directory and persist there for reuse. Only the per-version manifest + landmasks parquet (~hundreds of MB combined) is kept in the cache directory.

Commands

download

Download embeddings for a region in numpy or GeoTIFF format.

Usage:

geotessera download [OPTIONS]

Required Options:

  • -o, --output PATH - Output directory [required]

Region Definition (one required):

  • --bbox TEXT - Bounding box: ‘min_lon,min_lat,max_lon,max_lat’

  • --region-file PATH - GeoJSON/Shapefile to define region (supports local files or URLs)

  • --country TEXT - Country name (e.g., ‘United Kingdom’, ‘UK’, ‘GB’)

Format Options:

  • -f, --format TEXT - Output format: ‘tiff’ or ‘npy’ (default: tiff)

  • --bands TEXT - Comma-separated band indices (default: all 128)

  • --compress TEXT - Compression for TIFF format (default: lzw)

Data Selection:

  • --year INT - Year of embeddings (default: 2024)

  • --dataset-version TEXT - Tessera dataset version (v1 / 1.0 / v1.1 / 1.1; default v1). Pick once per project.

  • --dataset-variant TEXT - Tessera dataset variant (default: vultr). Pass cambridge for v1.1 test embeddings.

Other Options:

  • --list-files - List all created files with details

  • -v, --verbose - Verbose output

Warning

Re-running download into a directory that already contains a different (version, variant) will silently mix tiles — the local layout is the same regardless of variant. Always use a fresh --output dir per (version, variant) and check the tessera_metadata.json sidecar if you’re unsure which run produced the contents.

Resume Behaviour:

Both TIFF and NPY downloads automatically skip files that already exist on disk, so interrupted downloads can be resumed by re-running the same command. The progress bar reflects only remaining work.

Examples:

# Download as GeoTIFF (georeferenced, for GIS)
geotessera download \
    --bbox "-0.2,51.4,0.1,51.6" \
    --year 2024 \
    --output ./london_tiffs
# Next step: geotessera visualize ./london_tiffs pca_mosaic.tif

# Download as numpy arrays (for analysis)
geotessera download \
    --bbox "-0.2,51.4,0.1,51.6" \
    --format npy \
    --year 2024 \
    --output ./london_arrays

# Download specific bands only
geotessera download \
    --bbox "-0.2,51.4,0.1,51.6" \
    --bands "0,1,2,10,20,30" \
    --year 2024 \
    --output ./london_subset
# Next step: geotessera visualize ./london_subset pca_mosaic.tif

# Download by country name
geotessera download \
    --country "United Kingdom" \
    --year 2024 \
    --output ./uk_tiles
# Next step: geotessera visualize ./uk_tiles pca_mosaic.tif

# Download using a region file
geotessera download \
    --region-file cambridge.geojson \
    --format tiff \
    --year 2024 \
    --output ./cambridge_tiles
# Next step: geotessera visualize ./cambridge_tiles pca_mosaic.tif

# Download v1.1 / cambridge embeddings (recommended for new work)
geotessera download \
    --dataset-version v1.1 \
    --dataset-variant cambridge \
    --region-file cambridge.geojson \
    --year 2024 \
    --output ./cambridge_v11
# Note the tessera_metadata.json sidecar dropped alongside the tiles —
# it records the (version, variant) provenance for this output dir.

Output Formats:

TIFF Format (--format tiff):

  • Creates georeferenced GeoTIFF files with native UTM projections

  • Each tile preserves its native UTM projection from landmask tiles

  • Includes accurate CRS and transform metadata

  • Suitable for GIS software (QGIS, ArcGIS, etc.)

  • Supports compression (lzw, deflate, none)

  • Registry directory structure: global_0.1_degree_representation/{year}/grid_{lon}_{lat}/grid_{lon}_{lat}_{year}.tiff

  • Supports resume: interrupted downloads skip existing files

NPY Format (--format npy):

  • Downloads quantized numpy arrays (.npy) with separate scale files and landmask TIFFs

  • Registry directory structure: global_0.1_degree_representation/{year}/grid_{lon}_{lat}/

  • Embedding files: grid_{lon}_{lat}.npy (int8 quantized)

  • Scale files: grid_{lon}_{lat}_scales.npy (float32)

  • Landmask TIFFs: global_0.1_degree_tiff_all/grid_{lon}_{lat}.tiff (CRS and transform)

  • Dequantize with: embedding = quantized.astype(np.float32) * scales

  • Supports resume: interrupted downloads skip existing files

visualize

Create PCA visualization from multiband GeoTIFF files.

Usage:

geotessera visualize INPUT_PATH OUTPUT_FILE [OPTIONS]

Required Arguments:

  • INPUT_PATH - Path to GeoTIFF file or directory containing GeoTIFFs

  • OUTPUT_FILE - Output PCA mosaic file (.tif)

PCA Options:

  • --n-components INT - Number of PCA components (default: 3). Only first 3 used for RGB visualization - increase for analysis/research.

  • --crs TEXT - Target CRS for reprojection (default: EPSG:3857)

RGB Balance Options:

  • --balance TEXT - RGB balance method: histogram (default), percentile, or adaptive

  • --percentile-low FLOAT - Lower percentile for percentile balance method (default: 2.0)

  • --percentile-high FLOAT - Upper percentile for percentile balance method (default: 98.0)

Examples:

# Create PCA visualization (3 components optimal for RGB)
geotessera visualize tiles/ pca_mosaic.tif

# Use histogram equalization for maximum contrast
geotessera visualize tiles/ pca_balanced.tif --balance histogram

# Use adaptive scaling based on variance
geotessera visualize tiles/ pca_adaptive.tif --balance adaptive

# Custom percentile range for outlier-robust scaling
geotessera visualize tiles/ pca_custom.tif --percentile-low 5 --percentile-high 95

# Use custom projection
geotessera visualize tiles/ pca_mosaic.tif --crs EPSG:4326

# PCA for research - compute more components for analysis
# (still only uses first 3 for RGB, but saves variance info)
geotessera visualize tiles/ pca_research.tif --n-components 10

PCA Visualization Process:

  1. Data Combination: Combines all embedding data across tiles

  2. PCA Transformation: Applies a single PCA transformation to the combined dataset

  3. RGB Mosaic: Creates a unified RGB mosaic from the first 3 principal components

  4. Consistent Components: Ensures consistent principal components across the entire region, eliminating tiling artifacts

Balance Methods:

  • histogram - Histogram equalization for maximum contrast

  • percentile - Uses percentile range for outlier-robust scaling

  • adaptive - Adaptive scaling based on variance

Next Steps: After creating PCA visualization, use geotessera webmap to create interactive web tiles

webmap

Create web tiles and viewer from a 3-band RGB mosaic.

Usage:

geotessera webmap RGB_MOSAIC [OPTIONS]

Required Arguments:

  • RGB_MOSAIC - 3-band RGB mosaic GeoTIFF file

Options:

  • -o, --output PATH - Output directory

  • --min-zoom INT - Min zoom for web tiles (default: 8)

  • --max-zoom INT - Max zoom for web tiles (default: 15)

  • --initial-zoom INT - Initial zoom level (default: 10)

  • --force/--no-force - Force regeneration of tiles even if they exist

  • --serve/--no-serve - Start web server immediately

  • -p, --port INT - Port for web server (default: 8000)

  • --region-file PATH - GeoJSON/Shapefile boundary to overlay (supports local files or URLs)

  • --use-gdal-raster/--use-gdal2tiles - Use newer gdal raster tile vs gdal2tiles (default: gdal2tiles)

Examples:

# Create web tiles from PCA mosaic and serve immediately
geotessera webmap pca_mosaic.tif --serve

# Create web tiles with custom zoom levels
geotessera webmap pca_mosaic.tif --min-zoom 6 --max-zoom 18 --output webmap/

# Add region boundary overlay
geotessera webmap pca_mosaic.tif --region-file study_area.geojson --serve

# Force regeneration of existing tiles
geotessera webmap pca_mosaic.tif --force --serve

Process: 1. Reprojects mosaic to EPSG:3857 for web viewing if needed 2. Generates web tiles at specified zoom levels 3. Creates HTML viewer with Leaflet map 4. Optionally starts web server for immediate viewing

serve

Start a web server to serve visualization files.

Usage:

geotessera serve DIRECTORY [OPTIONS]

Required Arguments:

  • DIRECTORY - Directory containing web visualization files

Options:

  • -p, --port INT - Port number for web server (default: 8000)

  • --open/--no-open - Auto-open browser (default: open)

  • --html TEXT - Specific HTML file to serve

Examples:

# Serve web visualization and open browser
geotessera serve ./london_web --open

# Serve on specific port
geotessera serve ./london_web --port 8080

# Serve specific HTML file
geotessera serve ./visualizations --html coverage.html

# Serve without auto-opening browser
geotessera serve ./london_web --no-open
Notes:

  • The server automatically finds HTML files (index.html, viewer.html, etc.)

  • Use Ctrl+C to stop the server

  • The server serves all files in the directory

  • Required for viewing Leaflet-based web maps

coverage

Generate a world map showing Tessera embedding coverage.

Usage:

geotessera coverage [OPTIONS]

Output Options:

  • -o, --output PATH - Output PNG file path (default: tessera_coverage.png)

Data Selection:

  • --year INT - Specific year to visualize (default: all years)

  • --region-file PATH - GeoJSON/Shapefile to focus coverage map on specific region (supports local files or URLs)

  • --country TEXT - Country name to focus coverage map on with precise boundary outline (e.g., ‘United Kingdom’, ‘UK’, ‘GB’)

  • --dataset-version TEXT - Tessera dataset version. Pass all with --by-source to render every known version.

  • --dataset-variant TEXT - Tessera dataset variant. Pass all with --by-source to render every variant.

Multi-source rendering:

  • --by-source - Render each (version, variant) in a distinct hue with per-dataset checkboxes in the generated globe.html. Each tile’s shade encodes how many years of coverage it has (pale = 1 year, saturated = all years for that dataset). Without --dataset-version / --dataset-variant overrides, defaults to all on both axes — downloads every known version’s manifest and renders them side-by-side.

Visualization Options:

  • --tile-color TEXT - Color for tile rectangles (default: red)

  • --tile-alpha FLOAT - Transparency of tiles 0.0-1.0 (default: 0.6)

  • --tile-size FLOAT - Size multiplier for tiles (default: 1.0)

  • --no-multi-year-colors - Disable multi-year color coding

Map Options:

  • --width INT - Output image width in pixels (default: 2000)

  • --no-countries - Don’t show country boundaries

Examples:

# STEP 1: Check coverage for your region (recommended first step)
geotessera coverage --region-file study_area.geojson
geotessera coverage --region-file colombia_aoi.gpkg
geotessera coverage --country "United Kingdom"
geotessera coverage --country "Colombia"

# Check coverage for specific year only
geotessera coverage --region-file study_area.shp --year 2024
geotessera coverage --country "UK" --year 2024

# Global coverage overview (all regions)
geotessera coverage

# Global coverage for specific year
geotessera coverage --year 2024

# Customize visualization
geotessera coverage --region-file area.geojson --tile-alpha 0.3
geotessera coverage --country "Germany" --tile-alpha 0.3

# Show every dataset version on one map, with a layer-toggle UI in
# globe.html. Each (version, variant) gets a distinct hue family;
# within each hue, shade indicates how many years are covered.
geotessera coverage --by-source --output ./multi
# Output: multi/{tessera_coverage.png, coverage.json,
#              coverage_texture_v1_vultr.png, coverage_v1_vultr_*.json,
#              coverage_texture_v1.1_cambridge.png, coverage_v1.1_cambridge_*.json,
#              globe.html}

# Focus on a single (version, variant) but still get the per-dataset
# legend / by-source coverage.json schema:
geotessera coverage --by-source --dataset-version v1.1 \
    --dataset-variant cambridge --output ./v11_only
Multi-Year Color Coding (default when no specific year requested):

  • Green: All available years present for this tile

  • Blue: Only the latest year available for this tile

  • Orange: Partial years coverage (some combination of years)

Output:

  • High-resolution PNG world map with available tile coverage

  • Colored rectangles show available tile locations (one per 0.1° × 0.1° tile)

  • Boundary Visualization: Country/region boundaries are precisely outlined when using --country or --region-file

  • Global country boundaries are hidden when focusing on specific regions for cleaner visualization

  • Statistics and next-step hints shown after generation

Next Steps: After checking coverage, proceed to download data using the same region file or bounding box

info

Display information about GeoTIFF files or the library.

Usage:

geotessera info [OPTIONS]

Options:

  • --tiles PATH - Analyze tile files/directory (GeoTIFF or NPY format)

  • --geotiffs PATH - Alias for –tiles (deprecated)

  • --dataset-version TEXT - Tessera dataset version (default: v1)

  • --dataset-variant TEXT - Tessera dataset variant (default: vultr)

  • -v, --verbose - Verbose output

Examples:

# Show library information for the legacy 1.0/vultr line (frozen)
geotessera info

# Inspect v1.1/cambridge — same 2017–2025 year range, newer model
geotessera info --dataset-version v1.1 --dataset-variant cambridge

# Analyze downloaded tiles (GeoTIFF or NPY)
geotessera info --tiles ./london_tiffs

# Analyze single GeoTIFF file
geotessera info --tiles ./london_tiffs/grid_51.45_-0.05.tif

# Verbose library info
geotessera info --verbose
Output for Library Info:

  • GeoTessera version

  • Available years in dataset

  • Registry information

  • Loaded blocks count

Output for GeoTIFF Analysis:

  • Total files analyzed

  • Years covered

  • Coordinate reference systems used

  • Bounding box of all files

  • Band count statistics

  • Individual tile information (with --verbose)

Common Workflows

Basic Download and View

Complete workflow from coverage check to web visualization:

# 1. Check data availability (RECOMMENDED FIRST STEP)
geotessera coverage --year 2024 --output coverage.png

# 2. Download data
geotessera download \
    --bbox "-0.2,51.4,0.1,51.6" \
    --year 2024 \
    --output ./london_data

# 3. Create PCA visualization
geotessera visualize ./london_data pca_mosaic.tif

# 4. Create web tiles and serve
geotessera webmap pca_mosaic.tif --serve

Analysis Workflow

Download for analysis purposes:

# 1. Check coverage for your analysis region
geotessera coverage --bbox "-0.1,52.0,0.1,52.2" --year 2024

# 2. Download as numpy arrays
geotessera download \
    --bbox "-0.1,52.0,0.1,52.2" \
    --format npy \
    --year 2024 \
    --output ./cambridge_analysis

# 3. Process in Python
python your_analysis_script.py

# 4. Export results as GeoTIFF for visualization
geotessera download \
    --bbox "-0.1,52.0,0.1,52.2" \
    --format tiff \
    --year 2024 \
    --output ./cambridge_viz

# 5. Create PCA visualization and web map
geotessera visualize ./cambridge_viz pca_analysis.tif
geotessera webmap pca_analysis.tif --serve

GIS Workflow

Prepare data for GIS software:

# 1. Check coverage for your region first
geotessera coverage --region-file study_area.geojson

# 2. Download with specific bands for analysis
geotessera download \
    --region-file study_area.geojson \
    --bands "10,20,30,40,50" \
    --format tiff \
    --compress lzw \
    --year 2024 \
    --output ./gis_data

# 3. Create PCA visualization for overview
geotessera visualize ./gis_data pca_overview.tif

# 4. Analyze files before importing to GIS
geotessera info --tiles ./gis_data --verbose

# Files are now ready for QGIS, ArcGIS, etc.
# Use pca_overview.tif for quick visual reference

Troubleshooting

Common Issues and Solutions

“No tiles found in region”:

  • Check coverage map first: geotessera coverage --year 2024

  • Verify bounding box format: min_lon,min_lat,max_lon,max_lat

  • Try a different year or larger region

Slow downloads:

  • Files are cached after first download

  • Use --verbose to see download progress

  • Check network connection

Web visualization not working:

  • Use geotessera serve instead of opening HTML directly

  • Check that tiles directory was created

  • Try --force to regenerate tiles

Memory issues with large regions:

  • Download smaller regions at a time

  • Use --bands to download only needed channels

  • Use npy format for smaller file sizes

Permission errors:

  • Check write permissions for output directory

  • Try using a different output directory

  • Set custom cache directory: --cache-dir /tmp/geotessera

GeoTIFF projection issues:

  • Files use native UTM projections (varies by location from landmask tiles)

  • Each tile preserves its original projection for accuracy

  • Most GIS software handles reprojection automatically

  • Use geotessera info --tiles to check CRS for each tile

  • Different tiles may have different UTM zones

Getting Help

For additional help:

# Command-specific help
geotessera download --help
geotessera visualize --help

# Version information
geotessera version

# Library information
geotessera info --verbose
Resources: