### Web Server Examples

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/cli_reference.md

Examples for serving web visualizations with custom ports, specific HTML files, and browser control.

```default
# 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
```

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

### Web Map Generation Examples

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/cli_reference.md

Examples for generating web tiles with custom zoom levels, region overlays, and server options.

```default
# 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
```

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

### Install GeoTessera

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/index.md

Standard installation via pip or development installation from source.

```bash
pip install geotessera
```

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

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

### Start Web Server for Visualizations

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/geotessera.md

Starts a web server to serve visualization files, which is necessary for leaflet-based web visualizations to load tiles and resources via HTTP. Specify the directory containing the files to serve and the port.

```python
geotessera serve ./output --port 8000
```

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

### Serve web visualizations locally

Source: https://github.com/ucam-eo/geotessera/blob/main/README.md

Starts a local web server to visualize GeoTessera data.

```bash
geotessera serve DIRECTORY [OPTIONS]

Options:
  -p, --port INT           Port number (default: 8000)
  --open/--no-open         Auto-open browser (default: open)
  --html TEXT              Specific HTML file to serve
```

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

### Install GeoTessera for development

Source: https://github.com/ucam-eo/geotessera/blob/main/README.md

Commands to clone the repository and install it in editable mode for development purposes.

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

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

### Serve Visualization Files via CLI

Source: https://context7.com/ucam-eo/geotessera/llms.txt

Start a local web server to host and view generated visualization files.

```bash
geotessera serve ./london_web --open

geotessera serve ./london_web --port 8080

geotessera serve ./visualizations --html coverage.html

geotessera serve ./london_web --no-open
```

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

### Verify GeoTessera Installation

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/quickstart.md

Verify that the GeoTessera installation was successful by running the help command.

```bash
geotessera --help
```

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

### Install GeoTessera and Import Libraries

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/tutorials.md

Install the GeoTessera library and necessary dependencies using pip. Then, import the required Python modules for data analysis and visualization.

```bash
pip install geotessera matplotlib jupyter
```

```python
import numpy as np
import matplotlib.pyplot as plt
from geotessera import GeoTessera
import json
```

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

### PCA Visualization Examples

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/cli_reference.md

Various configurations for PCA visualization, including balance methods, projection, and component count.

```default
# 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
```

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

### Install GeoTessera

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/quickstart.md

Install the GeoTessera library using pip. Requires Python 3.12 or later.

```bash
pip install geotessera
```

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

### Create Web Map Tiles using CLI

Source: https://github.com/ucam-eo/geotessera/blob/main/README.md

Generates web tiles and an interactive viewer from a PCA mosaic. Supports specifying output directory, zoom levels, and starting a web server.

```bash
geotessera webmap RGB_MOSAIC [OPTIONS]
```

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

### Generate coverage visualizations via CLI

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/geotessera.md

Examples of using the coverage command to generate maps, JSON metadata, and interactive globe visualizations.

```bash
geotessera coverage –region-file study_area.geojson
```

```bash
geotessera coverage –country “Colombia” -o maps/colombia.png
```

```bash
geotessera coverage –region-file area.geojson –tile-alpha 0.3 –width 3000
```

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

### Create Web Map Tiles and Viewer

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/geotessera.md

Generates web tiles and an HTML viewer from an RGB GeoTIFF mosaic. Optionally starts a web server to serve the tiles immediately. Requires an input RGB mosaic file.

```python
geotessera webmap mosaics/rgb_mosaic.tif --output webmap/ --serve
```

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

### GIS Workflow

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/cli_reference.md

This workflow focuses on preparing data for use in GIS software, starting with checking coverage for a specified region.

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

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

### Generate Interactive Web Maps

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/quickstart.md

Generates web tiles and an HTML viewer from a PCA mosaic. Automatically reprojects, creates tiles at multiple zoom levels, and starts a local web server.

```bash
geotessera webmap pca_mosaic.tif --serve
```

```bash
# Custom zoom levels and output directory
geotessera webmap pca_mosaic.tif --min-zoom 6 --max-zoom 18 --output webmap/
```

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

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

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

### Get Geotessera Version Information

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/cli_reference.md

Display the installed Geotessera version. This is helpful for checking compatibility or reporting issues.

```bash
geotessera --version
```

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

### Get Library Information Verbose

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/cli_reference.md

Retrieve detailed information about the Geotessera library, including its configuration and installed components. Use the --verbose flag for more comprehensive output.

```bash
geotessera info --verbose
```

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

### Basic Download and View Workflow

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/cli_reference.md

This workflow demonstrates a basic process of checking data availability, downloading data for a specific bounding box and year, creating a PCA visualization, and serving a web map.

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

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

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

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

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

### Serve Web Visualization

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/cli_reference.md

Basic command structure for serving web visualization files.

```default
geotessera serve DIRECTORY [OPTIONS]
```

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

### Create Web Maps via CLI

Source: https://context7.com/ucam-eo/geotessera/llms.txt

Generate interactive web tiles from PCA mosaics with configurable zoom levels and server options.

```bash
geotessera webmap pca_mosaic.tif --serve

geotessera webmap pca_mosaic.tif \
    --min-zoom 6 \
    --max-zoom 18 \
    --output webmap/

geotessera webmap pca_mosaic.tif \
    --region-file study_area.geojson \
    --serve

geotessera webmap pca_mosaic.tif --force --serve

geotessera webmap pca_mosaic.tif --serve --port 8080
```

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

### Sample Embeddings with Manual Download

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/geotessera.md

Demonstrates a manual download workflow for sampling embeddings. First, tiles are downloaded for the specified points, then embeddings are sampled in offline mode.

```python
gt.download_tiles_for_points(points, year=2024)
embeddings = gt.sample_embeddings_at_points(
    points, year=2024, auto_download=False
)
```

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

### Create Visualizations via CLI

Source: https://github.com/ucam-eo/geotessera/blob/main/README.md

Generate PCA mosaics or serve web maps from downloaded GeoTIFF files.

```bash
# Create a PCA mosaic from downloaded tiles
geotessera visualize ./london_tiffs pca_mosaic.tif

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

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

# Serve existing web visualizations locally
geotessera serve ./london_web --open
```

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

### Get GeoTessera Version

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/geotessera.md

Retrieve the current version of the GeoTessera library.

```python
from geotessera import GeoTessera
tessera = GeoTessera()
print(tessera.version)
```

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

### Registry Initialization and Tile Iteration

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/geotessera.md

Demonstrates how to initialize the Registry and iterate through tiles within a specified geographic region and year.

```APIDOC
## Registry Initialization and Tile Iteration

### Description
Initializes the Geotessera Registry and provides an example of iterating through geospatial tiles within a defined region and year. This method is memory-efficient for streaming large datasets.

### Method
N/A (Illustrative Example)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```py
from geotessera import Registry

registry = Registry('v1')
bounds = (-0.2, 51.4, 0.1, 51.6)  # London
for year, lon, lat in registry.iter_tiles_in_region(bounds, 2024):
    # Process each tile
    pass
```

### Response
N/A
```

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

### Print Geotessera Version

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/geotessera.md

Prints the currently installed version of the geotessera library.

```python
geotessera version()
```

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

### Visualize and Serve Data

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/index.md

Create PCA mosaics and interactive web maps from downloaded GeoTIFFs.

```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
```

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

### GET /landmask/file-size

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/geotessera.md

Retrieves the file size of a specific landmask tile from the registry based on geographic coordinates.

```APIDOC
## GET /landmask/file-size

### Description
Get the file size of a landmask tile from the registry.

### Method
GET

### Parameters
#### Query Parameters
- **lon** (float) - Required - Longitude of the tile center
- **lat** (float) - Required - Latitude of the tile center

### Response
#### Success Response (200)
- **size** (int) - File size in bytes
```

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

### Define Valid and Invalid Grid Centers

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/architecture.md

Examples of coordinate pairs that align with the 0.1-degree grid system versus those that do not.

```default
# Valid tile centers (examples)
valid_centers = [
    (0.05, 52.05),   # Northwest Europe
    (0.15, 52.05),   # Adjacent tile
    (-0.05, 51.95),  # Southwest tile
]

# Invalid centers (not on grid)
invalid_centers = [
    (0.07, 52.03),   # Off-grid
    (0.1, 52.1),     # Off by 0.05°
]
```

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

### Check Available Data via CLI

Source: https://github.com/ucam-eo/geotessera/blob/main/README.md

Use these commands to visualize available data coverage by country, year, or custom parameters.

```bash
# Generate a coverage map showing all available tiles
geotessera coverage --output coverage_map.png

# Generate a coverage map for the UK
geotessera coverage --country uk

# View coverage for a specific year
geotessera coverage --year 2024 --output coverage_2024.png

# Customize the visualization
geotessera coverage --year 2024 --tile-color blue --tile-alpha 0.3
```

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

### Getting Scales File Size

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/geotessera.md

Details the `get_scales_file_size` function, which returns the size in bytes of a specific scales file.

```APIDOC
## get_scales_file_size(year: int, lon: float, lat: float)

### Description
Gets the file size in bytes of a specific scales file from the registry, identified by its year, longitude, and latitude.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
* **year** (int) - Required - The year of the tile.
* **lon** (float) - Required - The longitude of the tile center.
* **lat** (float) - Required - The latitude of the tile center.

### Returns
* **int** - The file size of the scales file in bytes.

### Raises
* **ValueError** - If the tile is not found in the registry or the `scales_size` column is missing.

### Request Example
```py
from geotessera import Registry

registry = Registry('v1')
try:
    scales_size = registry.get_scales_file_size(year=2024, lon=0.0, lat=51.5)
    print(f"Scales file size: {scales_size} bytes")
except ValueError as e:
    print(f"Error: {e}")
```

### Response
#### Success Response (200)
```json
5120
```

#### Response Example
N/A
```

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

### Getting Manifest Information

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/geotessera.md

Details the `get_manifest_info` function, which retrieves manifest information such as the git hash and repository URL.

```APIDOC
## get_manifest_info()

### Description
Retrieves manifest information, specifically the git hash and repository URL, associated with the Geotessera installation. For Parquet registries, this information is not stored and empty values are returned for API compatibility.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
N/A

### Returns
* **Tuple[str | None, str | None]** - A tuple containing (git_hash, repo_url). Both values will be None for Parquet registries.

### Request Example
```py
from geotessera import Registry

registry = Registry('v1')
git_hash, repo_url = registry.get_manifest_info()
print(f"Git Hash: {git_hash}")
print(f"Repo URL: {repo_url}")
```

### Response
#### Success Response (200)
```json
[
  "abcdef1234567890",
  "https://github.com/user/geotessera.git"
]
```

#### Response Example
N/A
```

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

### Generate Web Tiles and Viewer

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/tutorials.md

Create an interactive web map with Leaflet from a PCA mosaic using the CLI.

```bash
# Using CLI:
# geotessera webmap pca_rgb_mosaic.tif --serve

# This command automatically:
# 1. Reprojects mosaic for web viewing if needed
# 2. Generates web tiles at multiple zoom levels
# 3. Creates HTML viewer with Leaflet map
# 4. Starts web server and opens in browser

# For custom options:
# geotessera webmap pca_rgb_mosaic.tif --min-zoom 6 --max-zoom 18 --output webmap/ --serve

print("Web tiles and viewer created")
print("Interactive map should open in your browser")
```

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

### Getting Landmask Tile Count

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/geotessera.md

Details the `get_landmask_count` function, which returns the total count of unique landmask tiles.

```APIDOC
## get_landmask_count()

### Description
Gets the count of unique landmask tiles using efficient pandas operations. This is useful for quickly determining the total number of available landmasks.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
N/A

### Returns
* **int** - The total count of unique landmask tiles.

### Request Example
```py
from geotessera import Registry

registry = Registry('v1')
landmask_count = registry.get_landmask_count()
print(f"Total landmask tiles: {landmask_count}")
```

### Response
#### Success Response (200)
```json
10000
```

#### Response Example
N/A
```

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

### Getting Tile Counts by Year

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/geotessera.md

Explains the `get_tile_counts_by_year` function, which efficiently provides the number of tiles available for each year.

```APIDOC
## get_tile_counts_by_year()

### Description
Gets the count of available embedding tiles for each year using efficient pandas operations. This provides a summary of data volume per year.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
N/A

### Returns
* **Dict[int, int]** - A dictionary where keys are years and values are the corresponding tile counts.

### Request Example
```py
from geotessera import Registry

registry = Registry('v1')
tile_counts = registry.get_tile_counts_by_year()
print(tile_counts)
```

### Response
#### Success Response (200)
```json
{
  "2023": 1500,
  "2024": 1650
}
```

#### Response Example
N/A
```

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

### Execute Full Geospatial Workflow in Python

Source: https://context7.com/ucam-eo/geotessera/llms.txt

A complete pipeline demonstrating initialization, region-based embedding fetching, analysis, and GeoTIFF export.

```python
from geotessera import GeoTessera
from geotessera.visualization import visualize_global_coverage
import numpy as np

# Initialize client
gt = GeoTessera(embeddings_dir="./embeddings")

# Step 1: Check coverage for region
bbox = (-0.15, 52.15, 0.0, 52.25)  # Cambridge area
visualize_global_coverage(gt, "coverage.png", region_bbox=bbox)

# Step 2: Fetch and analyze embeddings
tiles_to_fetch = gt.registry.load_blocks_for_region(bounds=bbox, year=2024)
embeddings = gt.fetch_embeddings(tiles_to_fetch)

results = []
for year, tile_lon, tile_lat, embedding, crs, transform in embeddings:
    mean_per_band = np.mean(embedding, axis=(0, 1))
    results.append({
        'lat': tile_lat,
        'lon': tile_lon,
        'mean_band_50': mean_per_band[50],
        'total_variance': np.var(embedding),
        'crs': str(crs)
    })
    print(f"Tile ({tile_lat:.2f}, {tile_lon:.2f}): variance={np.var(embedding):.3f}")

# Step 3: Export selected tiles as GeoTIFF
threshold = np.median([r['mean_band_50'] for r in results])
selected = [(2024, r['lon'], r['lat']) for r in results if r['mean_band_50'] > threshold]

files = gt.export_embedding_geotiffs(
    tiles_to_fetch=selected,
    output_dir="./selected_tiles",
    bands=[40, 50, 60]
)
print(f"Exported {len(files)} tiles")

# Step 4: Create visualization (via CLI)
# geotessera visualize ./selected_tiles pca_mosaic.tif
# geotessera webmap pca_mosaic.tif --serve
```

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

### Analysis Workflow

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/cli_reference.md

This workflow outlines steps for downloading data for analysis, including checking coverage, downloading as numpy arrays, processing with Python, exporting as GeoTIFF, and creating visualizations.

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

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

```bash
# 3. Process in Python
python your_analysis_script.py
```

```bash
# 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
```

```bash
# 5. Create PCA visualization and web map
geotessera visualize ./cambridge_viz pca_analysis.tif
```

```bash
geotessera webmap pca_analysis.tif --serve
```

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

### Getting Embedding Tile File Size

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/geotessera.md

Explains the `get_tile_file_size` function, which returns the size in bytes of a specific embedding tile.

```APIDOC
## get_tile_file_size(year: int, lon: float, lat: float)

### Description
Gets the file size in bytes of a specific embedding tile from the registry, identified by its year, longitude, and latitude.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
* **year** (int) - Required - The year of the tile.
* **lon** (float) - Required - The longitude of the tile center.
* **lat** (float) - Required - The latitude of the tile center.

### Returns
* **int** - The file size of the embedding tile in bytes.

### Raises
* **ValueError** - If the tile is not found in the registry or the `file_size` column is missing.

### Request Example
```py
from geotessera import Registry

registry = Registry('v1')
try:
    file_size = registry.get_tile_file_size(year=2024, lon=0.0, lat=51.5)
    print(f"File size: {file_size} bytes")
except ValueError as e:
    print(f"Error: {e}")
```

### Response
#### Success Response (200)
```json
10240
```

#### Response Example
N/A
```

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

### GET /embeddings_count

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/geotessera.md

Retrieves the total number of embedding tiles available within a specified bounding box for a given year.

```APIDOC
## GET /embeddings_count

### Description
Get total number of embedding tiles within a bounding box.

### Parameters
#### Query Parameters
- **bbox** (Tuple[float, float, float, float]) - Required - Bounding box as (min_lon, min_lat, max_lon, max_lat)
- **year** (int) - Optional - Year of embeddings to consider (default: 2024)

### Response
#### Success Response (200)
- **count** (int) - Total number of tiles in the bounding box
```

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

### GeoTessera Initialization and Usage

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/geotessera.md

Demonstrates how to initialize the GeoTessera class and perform common operations like fetching embeddings within a bounding box and exporting them as GeoTIFF files.

```APIDOC
## GeoTessera Class Initialization and Core Functionality

### Description
Initializes the GeoTessera library for accessing Tessera geospatial embeddings. This class handles downloading tiles, sampling embeddings, and exporting them as GeoTIFF files.

### Method
`__init__`

### Parameters
- **dataset_version** (str) - Optional - Tessera dataset version (e.g., ‘v1’, ‘v2’). Defaults to 'v1'.
- **cache_dir** (str | Path | None) - Optional - Directory for caching registry files only.
- **embeddings_dir** (str | Path | None) - Optional - Directory containing pre-downloaded embedding tiles. Defaults to the current working directory.
- **registry_url** (str | None) - Optional - URL to download Parquet registry from. Defaults to remote.
- **registry_path** (str | Path | None) - Optional - Local path to an existing Parquet registry file.
- **registry_dir** (str | Path | None) - Optional - Directory containing registry.parquet and landmasks.parquet files.
- **verify_hashes** (bool) - Optional - If True (default), verify SHA256 hashes of downloaded files. Can be disabled via environment variable.

### Request Example
```pycon
from geotessera import GeoTessera
gt = GeoTessera()

# Fetch embedding tiles in a bounding box
bbox = (-0.2, 51.4, 0.1, 51.6)  # London area
tiles_to_fetch = gt.registry.load_blocks_for_region(bounds=bbox, year=2024)
tiles = gt.fetch_embeddings(tiles_to_fetch)

# Export as individual GeoTIFF files
files = gt.export_embedding_geotiffs(
    tiles_to_fetch,
    output_dir="tiles/",
    bands=[0, 1, 2]  # Select specific bands
)

# Or export a single tile
file = gt.export_embedding_geotiff(
    lat=51.55, lon=-0.05,
    output_path="single_tile.tif"
)
```

### Response
#### Success Response (200)
- **GeoTessera instance**: An initialized GeoTessera object.
- **List of file paths**: For export methods, a list of paths to the created GeoTIFF files.

#### Response Example
```json
{
  "message": "Embeddings fetched and exported successfully.",
  "exported_files": ["tiles/tile1.tif", "tiles/tile2.tif"]
}
```
```

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

### Display Information about GeoTIFF Files or Library

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/cli_reference.md

Use the 'info' command to display library information or analyze tile files (GeoTIFF or NPY). Options include specifying tile paths, dataset versions, and enabling verbose output for detailed analysis.

```bash
geotessera info [OPTIONS]
```

```bash
# Show library information
geotessera info
```

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

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

```bash
# Verbose library info
geotessera info --verbose
```

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

### GeoTessera Cache Configuration

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/cli_reference.md

Instructions on how to configure the cache directory for the GeoTessera registry, including default locations and examples for specifying custom paths.

```APIDOC
## Cache Configuration

Control where the Parquet registry is cached:

```bash
# Use custom cache directory for registry
geotessera download --cache-dir /path/to/cache ...

# Use local registry file
geotessera download --registry-path /path/to/registry.parquet ...

# Default cache locations (if not specified):
# - Linux/macOS: ~/.cache/geotessera/
# - Windows: %LOCALAPPDATA%/geotessera/
```

Note: Embedding tiles are downloaded to temporary files and immediately cleaned up. Only the registry file (~few MB) is cached.
```

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

### Download Embeddings as NumPy Arrays

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/cli_reference.md

Download embeddings in numpy (.npy) format for data analysis. This example specifies the format and output directory.

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

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

### Create PCA Visualization

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/tutorials.md

Generate a PCA-based RGB mosaic from tiles using the CLI to reduce dimensionality and eliminate tiling artifacts.

```bash
# Using CLI:
# geotessera visualize ./london_rgb pca_rgb_mosaic.tif
# geotessera visualize ./london_full pca_full_mosaic.tif --n-components 5

# This creates a PCA-based RGB mosaic that:
# 1. Combines all embedding data across tiles
# 2. Applies PCA transformation for dimensionality reduction
# 3. Maps first 3 principal components to RGB channels
# 4. Eliminates tiling artifacts through consistent PCA across region

print("PCA mosaic created")
print("Next step: geotessera webmap pca_rgb_mosaic.tif --serve")
```

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

### Download Embeddings as GeoTIFF

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/cli_reference.md

Download embeddings in GeoTIFF format for GIS software. This example downloads data for a specific bounding box and year.

```bash
# Download as GeoTIFF (georeferenced, for GIS)
geotessera download \
    --bbox "-0.2,51.4,0.1,51.6" \
    --year 2024 \
    --output ./london_tiffs
```

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

### Create Global Coverage Visualization

Source: https://github.com/ucam-eo/geotessera/blob/main/README.md

Generates a visualization of global data coverage. Requires a Tessera client, output path, and optional parameters for year, dimensions, and tile styling.

```python
visualize_global_coverage(
    tessera_client=gt,
    output_path="global_coverage.png",
    year=2024,  # Or None for all years
    width_pixels=2000,
    tile_color="red",
    tile_alpha=0.6
)
```

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

### Get Command-Specific Help

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/cli_reference.md

Access detailed help information for specific Geotessera commands. This is useful for understanding all available options and parameters for a given command.

```bash
geotessera download --help
```

```bash
geotessera visualize --help
```

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

### Query the Parquet registry

Source: https://github.com/ucam-eo/geotessera/blob/main/README.md

Demonstrates how to load and inspect the registry file using pandas.

```python
# Example registry query
import pandas as pd
registry = pd.read_parquet("registry.parquet")
print(registry.head())
#    lon    lat  year                                hash  ...
# 0.15  52.05  2024  abc123...
```

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

### Download Embeddings Using a Region File

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/cli_reference.md

Define the download region using a GeoJSON or Shapefile. This example uses a local GeoJSON file to specify the area.

```bash
# Download using a region file
geotessera download \
    --region-file cambridge.geojson \
    --format tiff \
    --year 2024 \
    --output ./cambridge_tiles
```

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

### Generate Coverage Maps via CLI

Source: https://context7.com/ucam-eo/geotessera/llms.txt

Create visual representations of Tessera embedding coverage for specific regions, years, or countries.

```bash
geotessera coverage

geotessera coverage --year 2024 --output coverage_2024.png

geotessera coverage --region-file study_area.geojson

geotessera coverage --country "United Kingdom"
geotessera coverage --country "Greece"  # Shows islands and coastlines

geotessera coverage \
    --region-file area.geojson \
    --tile-alpha 0.3 \
    --tile-color blue \
    --width 3000
```

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

### Display GeoTIFF and Library Info via CLI

Source: https://context7.com/ucam-eo/geotessera/llms.txt

Retrieve metadata about the library or analyze specific GeoTIFF/NPY tile files.

```bash
geotessera info

geotessera info --tiles ./london_tiffs

geotessera info --tiles ./london_tiffs/grid_51.45_-0.05.tif

geotessera info --verbose
```

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

### Efficient Point Sampling with GeoTessera

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/architecture.md

Sample embeddings at specific geographic coordinates. This method automatically handles tile downloads. Use `include_metadata=True` to get information about the source tile for each point.

```python
# Efficient point sampling with automatic tile download
points = [(0.15, 52.05), (0.25, 52.15), (-0.05, 51.55)]
embeddings = gt.sample_embeddings_at_points(points, year=2024)
```

```python
# With metadata about which tile each point came from
embeddings, metadata = gt.sample_embeddings_at_points(
    points, year=2024, include_metadata=True
)
```

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

### Create Web Map Visualization with Geotessera CLI

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/geotessera.md

Serve a web map visualization of a PCA mosaic. This command is used after creating a PCA visualization to make it accessible via a web server.

```bash
geotessera webmap pca_mosaic.tif --serve
```

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

### Get Size of a Landmask Tile

Source: https://github.com/ucam-eo/geotessera/blob/main/CHANGES.md

Retrieve the size in bytes of a specific landmask tile from the registry. This is part of the public API for querying registry file sizes and aids in estimating download sizes.

```python
gt.registry.get_landmask_file_size(lon, lat)
```

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

### CLI Commands

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/geotessera.md

Commands for inspecting tile information and generating coverage visualizations.

```APIDOC
## geotessera.cli.info

### Description
Show information about tile files or library. Supports both GeoTIFF and NPY format tiles.

### Parameters
- **tiles_dir** (Path) - Optional - Directory containing tiles
- **geotiffs** (Path) - Optional - Path to GeoTIFF files
- **dataset_version** (str) - Optional - Dataset version (default: 'v1')
- **verbose** (bool) - Optional - Enable verbose output

## geotessera.cli.coverage

### Description
Generate coverage visualizations showing Tessera embedding availability, including PNG maps, JSON data, and interactive HTML globes.

### Parameters
- **output** (Path) - Required - Output path for the PNG map
- **year** (int) - Optional - Filter by specific year
- **region_file** (str) - Optional - Path to region GeoJSON
- **country** (str) - Optional - Country name for filtering
- **bbox** (str) - Optional - Bounding box coordinates
- **tile_color** (str) - Optional - Color for tiles (default: 'red')
- **tile_alpha** (float) - Optional - Alpha transparency (default: 0.6)
- **dataset_version** (str) - Optional - Dataset version (default: 'v1')
```

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

### Export Single Embedding Tile as GeoTIFF

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/geotessera.md

Exports a single embedding tile to a GeoTIFF file with a native UTM projection. You can specify which bands to export and the compression method. Requires the `rasterio` library to be installed.

```python
gt.export_embedding_geotiff(lon=0.15, lat=52.05, output_path="./output.tif", year=2024)
```

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

### Initialize Cloud-Native Zarr Store

Source: https://github.com/ucam-eo/geotessera/blob/main/README.md

Initializes the GeoTessera Zarr store for cloud-based data access. This allows streaming data without downloading files.

```python
from geotessera.store import GeoTesseraZarr

gt = GeoTesseraZarr()
print(gt.years)  # [2017, 2018, ..., 2025]
```

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

### Count Embedding Tiles in a Bounding Box

Source: https://github.com/ucam-eo/geotessera/blob/main/CHANGES.md

Get the total number of embedding tiles that fall within a specified bounding box for a given year. Useful for estimating download volumes and processing loads.

```python
count = gt.embeddings_count((min_lon, min_lat, max_lon, max_lat), 2024)
```

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

### Iterate over tiles in a region

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/geotessera.md

Demonstrates how to initialize a registry and iterate through embedding tiles within specific geographic bounds for a given year.

```pycon
>>> registry = Registry('v1')
>>> bounds = (-0.2, 51.4, 0.1, 51.6)  # London
>>> for year, lon, lat in registry.iter_tiles_in_region(bounds, 2024):
...     embedding = fetch_embedding(lon, lat, year)
...     process(embedding)  # Start processing immediately
```

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

### Get Size of an Embedding Tile

Source: https://github.com/ucam-eo/geotessera/blob/main/CHANGES.md

Query the size in bytes of a specific embedding tile from the registry. This method provides a programmatic way to check file sizes and is used internally for download requirement calculations.

```python
size = gt.registry.get_tile_file_size(2024, 0.15, 52.05)
```

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

### Export Parquet Registry to Pooch Manifests

Source: https://github.com/ucam-eo/geotessera/blob/main/CHANGES.md

Utilize the `export-manifests` command to convert Parquet registry files (`registry.parquet`, `landmasks.parquet`) into Pooch-format text manifests. This is beneficial for maintaining backwards compatibility and the `tessera-manifests` repository.

```bash
geotessera-registry export-manifests /path/to/v1 --output-dir ~/src/git/ucam-eo/tessera-manifests
```

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

### CLI Command: visualize

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/geotessera.md

Creates a PCA visualization from GeoTIFF or NPY format embeddings, producing a unified RGB mosaic.

```APIDOC
## CLI Command: visualize

### Description
Create PCA visualization from GeoTIFF or NPY format embeddings. Combines data across tiles to ensure consistent principal components.

### Parameters
#### Arguments
- **input_path** (Path) - Required - Directory containing input files.
- **output_file** (Path) - Required - Path for the output mosaic file.

#### Options
- **target_crs** (str) - Optional - Target CRS (default: 'EPSG:3857').
- **n_components** (int) - Optional - Number of PCA components (default: 3).
- **balance_method** (str) - Optional - Balancing method: 'histogram' or 'adaptive' (default: 'histogram').
- **percentile_low** (float) - Optional - Lower percentile for scaling (default: 2.0).
- **percentile_high** (float) - Optional - Upper percentile for scaling (default: 98.0).
```

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

### Sample Embeddings at Points using GeoTesseraZarr

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/geotessera.md

Use `sample_points` to get embeddings at specified coordinates. The function routes each point to its correct zone and returns `(N, B)` float32 embeddings. Points outside coverage will result in NaN rows.

```python
X = gt.sample_points([(-2.97, 53.44)], year=2025)
```

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

### Generate Global Coverage Visualization

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/quickstart.md

Generate a global coverage map in PNG format, along with JSON data and an interactive HTML globe, to visualize available embedding tiles.

```bash
geotessera coverage --output global_coverage.png
```

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

### Visualize Embeddings via CLI

Source: https://context7.com/ucam-eo/geotessera/llms.txt

Generate PCA mosaics from tile directories with options for adaptive scaling, custom projections, and component selection.

```bash
geotessera visualize ./london_tiles pca_adaptive.tif --balance adaptive

geotessera visualize ./london_tiles pca_custom.tif \
    --percentile-low 5 --percentile-high 95

geotessera visualize ./london_tiles pca_mosaic.tif --crs EPSG:4326

geotessera visualize ./london_tiles pca_research.tif --n-components 10
```

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

### Create PCA Visualization

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/cli_reference.md

Generate a PCA (Principal Component Analysis) visualization from downloaded data for a quick overview. The output is saved as a GeoTIFF file.

```bash
geotessera visualize ./gis_data pca_overview.tif
```

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

### Update Initialization for Cache Directory

Source: https://github.com/ucam-eo/geotessera/blob/main/CHANGES.md

Migration note: Update initialization code to use the `cache_dir` parameter instead of environment variables like `TESSERA_DATA_DIR` or `TESSERA_REGISTRY_DIR`.

```python
# Update initialization code to use new cache_dir parameter
# geo_tessera = GeoTessera(cache_dir="path/to/cache")
```

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

### Fetch and Export Embedding Tiles

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/geotessera.md

Demonstrates fetching embedding tiles within a bounding box and exporting them as individual GeoTIFF files. Specify bands to select specific data channels.

```python
>>> from geotessera import GeoTessera
>>> gt = GeoTessera()
>>> 
>>> # Fetch embedding tiles in a bounding box
>>> bbox = (-0.2, 51.4, 0.1, 51.6)  # London area
>>> tiles_to_fetch = gt.registry.load_blocks_for_region(bounds=bbox, year=2024)
>>> tiles = gt.fetch_embeddings(tiles_to_fetch)
>>> 
>>> # Export as individual GeoTIFF files
>>> files = gt.export_embedding_geotiffs(
...     tiles_to_fetch,
...     output_dir="tiles/",
...     bands=[0, 1, 2]  # Select specific bands
... )
>>> 
>>> # Or export a single tile
>>> file = gt.export_embedding_geotiff(
...     lat=51.55, lon=-0.05,
...     output_path="single_tile.tif"
... )
```

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

### CLI: Visualize Command

Source: https://context7.com/ucam-eo/geotessera/llms.txt

Creates PCA visualizations from embedding files using the command line.

```bash
# Create PCA visualization (3 components for RGB)
geotessera visualize ./london_tiles pca_mosaic.tif

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

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

### Create PCA Visualization using CLI

Source: https://github.com/ucam-eo/geotessera/blob/main/README.md

Creates a PCA visualization from multiband GeoTIFF or NPY embeddings. Allows customization of PCA components, CRS, and RGB balance.

```bash
geotessera visualize INPUT_PATH OUTPUT_FILE [OPTIONS]
```

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

### Create PCA visualization mosaic

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/quickstart.md

Generates a unified RGB mosaic from embedding tiles using PCA transformation.

```bash
geotessera visualize ./london_tiles pca_mosaic.tif
# Next step: geotessera webmap pca_mosaic.tif --serve
```

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

### POST /download/requirements

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/geotessera.md

Calculates the total download size and file count for a specified set of tiles, useful for estimating storage and bandwidth needs.

```APIDOC
## POST /download/requirements

### Description
Calculate download requirements for a set of tiles.

### Method
POST

### Request Body
- **tiles** (List[Tuple[int, float, float]]) - Required - List of (year, lon, lat) tuples
- **output_dir** (Path) - Required - Output directory where files would be downloaded
- **format_type** (str) - Required - Either ‘npy’ or ‘tiff’
- **check_existing** (bool) - Optional - If True, skip files that already exist (for resume). If False, calculate as if downloading all files (for dry-run estimates).

### Response
#### Success Response (200)
- **total_bytes** (int) - Total download size in bytes
- **total_files** (int) - Number of files to download
- **file_sizes_dict** (Dict[str, int]) - Dictionary mapping file keys to sizes
```

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

### Perform Sequential Processing

Source: https://github.com/ucam-eo/geotessera/blob/main/docs/architecture.md

Demonstrates the standard sequential fetch pattern for region-based tile retrieval.

```python
# Sequential processing (recommended for most cases)
gt = GeoTessera()
tiles_to_fetch = gt.registry.load_blocks_for_region(bounds=bbox, year=2024)
```