| # Contributing | |
| ## Setup | |
| ```bash | |
| git clone <repo> | |
| cd terrology | |
| uv sync --extra web | |
| ``` | |
| ## Running the tool | |
| ```bash | |
| uv run main.py "Snowdon" --radius 500 # in the repo | |
| terrology "Snowdon" --radius 500 # when installed | |
| ``` | |
| ## Running the web UI | |
| ```bash | |
| uv run uvicorn web.app:app --reload | |
| ``` | |
| ## Tests and linting | |
| Run these before every commit: | |
| ```bash | |
| uv run pytest | |
| uv run ruff check . | |
| uv run ruff format . | |
| ``` | |
| Write tests alongside new code, not after. | |
| ## Key files | |
| | File | Purpose | | |
| |---|---| | |
| | `main.py` | CLI entry point — argument parsing, orchestration | | |
| | `terrology/builder.py` | `MapBuilder` — terrain mesh, buildings, colouring, clipping | | |
| | `terrology/fetcher.py` | OSM + elevation downloads, caching | | |
| | `terrology/decorations.py` | Border frame mesh | | |
| | `terrology/exporter.py` | STL, OBJ+MTL, 3MF output | | |
| | `terrology/cache.py` | Disk cache under `~/.cache/3dmap/` | | |
| | `web/` | FastAPI web interface | | |
| ## Notes | |
| - Always use `uv`. Don't use pip directly. | |
| - The cache stores failed fetches as empty results — use `--no-cache` when debugging missing features. | |
| - Stale cache is the most common cause of unexpected empty output. | |