GeoTessera

https://geotessera.readthedocs.io/
Admin
GeoTessera provides access to open geospatial embeddings from satellite imagery (Sentinel-1 and...
Tokens:2,278
Snippets:23
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install GeoTessera

Source: https://geotessera.readthedocs.io

Standard installation via pip or editable installation for development.

```bash
pip install geotessera
```

```bash
git clone https://github.com/ucam-eo/geotessera
cd geotessera
pip install -e .
```

--------------------------------

### Visualize and Serve Data via CLI

Source: https://geotessera.readthedocs.io

Create PCA mosaics from GeoTIFFs and serve them as interactive web maps.

```bash
# Create PCA mosaic from GeoTIFFs
geotessera visualize ./london_tiffs pca_mosaic.tif

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

--------------------------------

### Check Data Coverage via CLI

Source: https://geotessera.readthedocs.io

Verify data availability using global, year-specific, or country-specific filters.

```bash
# Generate coverage visualizations (creates PNG map, JSON data, and interactive HTML globe)
geotessera coverage --output coverage_map.png
# Creates: coverage_map.png, coverage.json, globe.html

# View coverage for a specific year
geotessera coverage --year 2024

# Check coverage for a single country with precise boundary outline
geotessera coverage --country "United Kingdom"
geotessera coverage --country uk  # Also accepts country codes
```

--------------------------------

### Initialize GeoTessera with Default Cache

Source: https://geotessera.readthedocs.io

Instantiate the GeoTessera class to use the default cache location. This is the recommended approach for most users.

```python
gt = GeoTessera()
```

--------------------------------

### Download Data with Custom Cache Directory (CLI)

Source: https://geotessera.readthedocs.io

Use the `geotessera download` command with the `--cache-dir` option to specify a custom directory for downloaded data.

```bash
geotessera download --cache-dir /path/to/cache ...
```

--------------------------------

### Download Data with Default Cache Location (CLI)

Source: https://geotessera.readthedocs.io

Execute the `geotessera download` command without specifying a cache directory to use the library's default cache location.

```bash
geotessera download ...
```

--------------------------------

### Download Embeddings via CLI

Source: https://geotessera.readthedocs.io

Download data in GeoTIFF or NPY format using bounding boxes, country names, or region files.

```bash
# Download as GeoTIFF (default, georeferenced, ready for GIS)
geotessera download --bbox "-0.2,51.4,0.1,51.6" --year 2024 --output ./london_tiffs --bands 1,2,3

# Download as quantized numpy arrays (for analysis, includes scales and landmask TIFFs)
geotessera download --bbox "-0.2,51.4,0.1,51.6" --format npy --year 2024 --output ./london_arrays
# NPY format includes: quantized .npy, _scales.npy, and landmask .tiff files

# Download by country name with precise boundary filtering
geotessera download --country "United Kingdom" --year 2024 --output ./uk_tiles

# Download tiles from a region file (supports GeoJSON, Shapefile, or URLs)
geotessera download --region-file example/CB.geojson --year 2024 --output ./cambridge
geotessera download --region-file https://example.com/region.geojson --year 2024 --output ./remote_region
```

--------------------------------

### Configure GeoTessera Cache Directory

Source: https://geotessera.readthedocs.io

Initialize the GeoTessera client with a custom cache directory for the Parquet registry.

```python
from geotessera import GeoTessera

# Use custom cache directory for registry
gt = GeoTessera(cache_dir="/path/to/cache")
```

--------------------------------

### Visualize GeoTessera Data Flow

Source: https://geotessera.readthedocs.io

A diagram illustrating the request process from registry lookup to final output.

```text
User Request (lat/lon bbox)
    ↓
Parquet Registry Lookup (find available tiles from registry.parquet)
    ↓
Direct HTTP Downloads to Temp Files
    ├── embedding.npy (quantized) → temp file
    └── embedding_scales.npy → temp file
    ↓
Dequantization (multiply arrays)
    ↓
Automatic Cleanup (delete temp files)
    ↓
Output Format
    ├── NumPy arrays → Direct analysis
    └── GeoTIFF → GIS integration
```

--------------------------------

### View Local Cache Structure

Source: https://geotessera.readthedocs.io

The directory layout of the local cache, noting that tiles are not stored persistently.

```text
~/.cache/geotessera/                 # Default cache location
└── registry.parquet                 # Cached Parquet registry (~few MB)

# Note: Embedding and landmask tiles are NOT cached persistently.
# They are downloaded to temporary files and immediately cleaned up after use.
```

--------------------------------

### View Remote Server Structure

Source: https://geotessera.readthedocs.io

The directory layout of the remote GeoTessera data server.

```text
https://dl2.geotessera.org/
├── v1/                              # Dataset version
│   ├── registry.parquet             # Parquet registry with all metadata
│   ├── 2024/                        # Year
│   │   ├── grid_0.15_52.05/         # Tile (named by center coords)
│   │   │   ├── grid_0.15_52.05.npy              # Quantized embeddings
│   │   │   └── grid_0.15_52.05_scales.npy       # Scale factors
│   │   └── ...
│   └── landmasks/
│       ├── grid_0.15_52.05.tiff     # Landmask with projection info
│       └── ...
```

--------------------------------

### Access Embeddings via Python API

Source: https://geotessera.readthedocs.io

Programmatic access to fetch single tiles, bounding box regions, or point samples, and export to GeoTIFF.

```python
from geotessera import GeoTessera

# Initialize client
gt = GeoTessera()

# Method 1: Fetch a single tile with CRS information
embedding, crs, transform = gt.fetch_embedding(lon=0.15, lat=52.05, year=2024)
print(f"Shape: {embedding.shape}")  # e.g., (1200, 1200, 128)
print(f"CRS: {crs}")  # UTM projection

# Method 2: Fetch all tiles in a bounding box
bbox = (-0.2, 51.4, 0.1, 51.6)  # (min_lon, min_lat, max_lon, max_lat)
tiles_to_fetch = gt.registry.load_blocks_for_region(bounds=bbox, year=2024)
tiles = gt.fetch_embeddings(tiles_to_fetch)

for year, tile_lon, tile_lat, embedding, crs, transform in tiles:
    print(f"Tile ({tile_lon}, {tile_lat}): {embedding.shape}")

# Method 3: Sample embeddings at specific point locations
points = [(0.15, 52.05), (0.25, 52.15), (-0.05, 51.55)]  # (lon, lat) tuples
embeddings = gt.sample_embeddings_at_points(points, year=2024)
print(f"Sampled embeddings shape: {embeddings.shape}")  # (3, 128)

# Export as GeoTIFF files with preserved UTM projections
tiles_to_fetch = gt.registry.load_blocks_for_region(bounds=bbox, year=2024)
files = gt.export_embedding_geotiffs(
    tiles_to_fetch,
    output_dir="./output",
    bands=[0, 1, 2]  # Export first 3 bands only
)
```
Tokens:
Raw