mars-titiler/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Mars Titiler is a FastAPI-based tile server for Mars MGS MOLA Color-Shaded Relief global basemap data. It uses the Titiler framework to serve Cloud Optimized GeoTIFFs (COG) with a custom Mars coordinate system.

## Environment Setup

The project uses a conda environment named `gdal_env`:

```bash
source /home/la/miniconda3/bin/activate gdal_env
```

This environment includes:
- FastAPI + Uvicorn (web server)
- rio-tiler (COG reading)
- morecantile (tile matrix sets)
- pyproj (coordinate reference systems)
- GDAL dependencies

## Running the Server

```bash
# Direct uvicorn
uvicorn app:app --reload --host 0.0.0.0 --port 8000

# Or use the provided script
./start_server.sh
```

The server will be available at `http://localhost:8000` with API docs at `/docs`.

## Testing

Run the comprehensive test suite:

```bash
python test_all.py [base_url] [data_path]
```

Example:
```bash
# Default (localhost:8000, default data path)
python test_all.py

# Custom server and data
python test_all.py http://localhost:8000 /path/to/data.tif
```

The test script validates:
- Data info endpoint
- TileJSON metadata
- Tile generation
- Preview images

## Architecture

### Custom Mars Coordinate System

The core of this project is the Mars Simple Cylindrical projection defined in `app.py`:

- **Projection**: Equidistant Cylindrical (Simple Cylindrical)
- **Sphere Radius**: 3,396,190 meters
- **Extent**:
  - X: ±10,669,442 m (±180° longitude)
  - Y: ±5,334,721 m (±90° latitude)
- **TMS Configuration**: `matrix_scale=[2, 1]` creates a 2×1 tile layout at zoom 0

The `matrix_scale=[2, 1]` is critical for compatibility with Cesium's `GeographicTilingScheme`, ensuring zoom 0 has exactly 2 tiles horizontally and 1 tile vertically.

### Titiler Factory Pattern

The application uses Titiler's `TilerFactory` to automatically generate endpoints:

```python
cog = TilerFactory(
    reader=Reader,
    supported_tms=tms,
)
```

This factory pattern eliminates the need to manually implement endpoints. All Titiler endpoints are automatically available under the `/cog` path prefix.

### Custom TMS Registration

The custom Mars TMS is registered with morecantile before being passed to the factory:

```python
MARS_TMS = TileMatrixSet.custom(
    crs=MARS_CRS,
    extent=(-_MAX_X, -_MAX_Y, _MAX_X, _MAX_Y),
    identifier="MarsCylindrical",
    matrix_scale=[2, 1],
)
tms = tms.register({"MarsCylindrical": MARS_TMS})
```

## API Endpoints

All endpoints require a `url` query parameter specifying the COG file path:

- **Tiles**: `/cog/tiles/MarsCylindrical/{z}/{x}/{y}?url=<path>`
- **TileJSON**: `/cog/MarsCylindrical/tilejson.json?url=<path>`
- **Info**: `/cog/info?url=<path>` (bands, bounds, CRS metadata)
- **Preview**: `/cog/preview.png?url=<path>&max_size=512`
- **Statistics**: `/cog/statistics?url=<path>`
- **Map Viewer**: `/cog/MarsCylindrical/map.html?url=<path>`

## Data Source

The default data file is expected at:
```
/home/la/studio/cesium/rio-tiler-tms/data/Mars_MGS_MOLA_ClrShade_merge_global_463m.tif
```

This is a Cloud Optimized GeoTIFF containing Mars MGS MOLA Color-Shaded Relief data.

## Design Principles

1. **Dynamic URLs**: Data paths are passed as query parameters, not hardcoded. This allows the same server to serve different datasets.

2. **Standards Compliance**: The TMS follows OGC standards and is compatible with Cesium's GeographicTilingScheme.

3. **Minimal Code**: Titiler's factory pattern auto-generates endpoints, resulting in ~70% less code compared to manual implementations.