first commit

CLAUDE.md

@@ -0,0 +1,127 @@
+# 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.