CONTRIBUTING.md

Contributing

Setup

git clone <repo>
cd terrology
uv sync --extra web

Running the tool

uv run main.py "Snowdon" --radius 500   # in the repo
terrology "Snowdon" --radius 500        # when installed

Running the web UI

uv run uvicorn web.app:app --reload

Tests and linting

Run these before every commit:

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.