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:

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

# 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:

python test_all.py [base_url] [data_path]

Example:

# 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:

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:

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.