128 lines
3.6 KiB
Markdown
128 lines
3.6 KiB
Markdown
# 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.
|