Generate 3D-printable terrain and building models from OpenStreetMap and elevation data.

Urban — Canary Wharf, London	Mountain — Snowdon with 50 m contours
Two-point — Edinburgh Castle to Arthur's Seat	Route — Beacon Fell Country Park GPX
Coastal — St Ives, Cornwall

Install uv, then:

uv tool install git+https://github.com/twigley/terrology
terrology "Snowdon" --radius 500

Or clone and run directly:

git clone https://github.com/twigley/terrology
cd terrology
terrology "Snowdon" --radius 500

The default elevation source (glo30) requires no API key. The srtm and aw3d30 sources require a free OpenTopography API key:

export OPENTOPOGRAPHY_API_KEY=your_key

Or save it once:

terrology --save-api-key <your_key>

terrology <location> [options]

Single location — square map centred on a point:

terrology "Canary Wharf, London" --radius 500
terrology 51.5074,-0.1278 --radius 600 --scale 4000

Two locations — rectangular map spanning both points (each near an edge):

terrology "51.5074,-0.1278" --to "51.5155,-0.0753"
terrology "Edinburgh Castle" --to "Arthur's Seat, Edinburgh" --buffer 0.08

Area (GeoJSON) — map clipped to a polygon boundary; everything outside is void:

terrology --area central_park.geojson
terrology --area manhattan.geojson --dem srtm

Draw or export a polygon from geojson.io, QGIS, or any GIS tool. The first polygon in the file is used. No location argument is needed — the polygon provides the extent.

Route (GPX) — terrain-only map with the GPX track painted as a coloured line:

terrology --route my_ride.gpx
terrology --route trail.gpx --route-width 2.0 --terrain-exag 3

A browser-based UI is included. It provides a map for drawing or searching a location, all the key options, a 3D preview of the result, and a ZIP download.

Try it live: https://huggingface.co/spaces/twigley/terrology

Run locally (installed):

uv tool install "git+https://github.com/twigley/terrology[web]"
terrology-web

Run locally (cloned repo):

uv run uvicorn web.app:app --host 0.0.0.0 --port 8000

Then open http://localhost:8000.

Run with Docker:

docker build -t terrology .
docker run -p 8000:8000 -e OPENTOPOGRAPHY_API_KEY=your_key terrology

Each job runs in its own process so memory is fully released when it finishes — the server returns to ~50 MB idle between jobs. The minimum spec for a public instance is 1 GB RAM.

Render, Koyeb, and Northflank free tiers top out at 256–512 MB RAM — not enough for a map generation job. Fly.io removed its free tier for new users in late 2024.

Fly.io quickstart:

fly launch          # detects the Dockerfile, creates fly.toml
fly secrets set OPENTOPOGRAPHY_API_KEY=your_key
fly deploy

Environment variables:

Import model.obj into Bambu Studio — it reads the MTL colours and lets you assign each material to a filament in the Filament panel.

The per-colour STLs (water.stl, parks.stl, roads.stl) are surface patches of the top layer only. Import them alongside terrain.stl into any slicer that handles multi-material via separate objects. Only files for colours present in the map are written.

Use --colors to limit the number of materials (e.g. --colors 2 for a two-colour printer).

All three are Digital Surface Models (DSM) — they measure the top of the surface including buildings and trees, which adds height to dense urban areas. srtm tends to be slightly smoother than glo30 in cities. Both srtm and aw3d30 require a free OpenTopography API key.

API key — set once as an environment variable so you don't have to pass it every run:

export OPENTOPOGRAPHY_API_KEY=your_key

Caching — OSM and elevation data are cached in ~/.cache/3dmap/. Re-runs with the same area are fast. Use --no-cache to force a fresh download. If features look unexpectedly missing, try --no-cache — a failed fetch is cached as empty.

Area / polygon maps — draw your boundary at geojson.io and save as a .geojson file. Useful for irregular shapes (a river valley, a city district, a national park) where a rectangular bbox would include unwanted terrain. Everything outside the polygon is removed entirely.

terrology --area my_area.geojson --smooth-boundary 4

Smooth polygon outlines — if your GeoJSON polygon has few vertices, the map outline will have angular corners. Use --smooth-boundary 3 to 5 to round them. More iterations pull the outline inward, so don't exceed ~6.

Multi-colour printing — import model.obj into Bambu Studio and assign each material name to a filament in the Filament panel. Buildings and terrain share the same material, so a 4-colour printer covers terrain, water, parks, and roads.

Nozzle & triangle count — the --nozzle default (0.4 mm) automatically caps grid resolutions so you never generate triangles the printer can't resolve. With a 0.6 mm nozzle the cap is tighter and files are smaller with no visible quality loss.

Vertical exaggeration — flat areas benefit from a higher --terrain-exag (try 3–5). Mountainous areas may look better at 1.5.

Route maps — the GPX bounding box is used automatically. Adjust --buffer to add more space around the track edges (default 5%). The route line width (--route-width) is in printed mm, not real-world metres, so it stays the same visual size regardless of map scale.

Coastal maps — coastlines and sea are detected automatically from OSM coastline data. Use --dem srtm for dense coastal cities to reduce building spikes in the terrain.

Contour lines — --contour-interval paints elevation contours using a colour already in your palette — no extra filament required. Choose an interval that matches the relief: 10–25 m for gentle hills, 50–100 m for mountains. Contours are invisible in 1–2 colour mode.

terrology "Zermatt, Switzerland" --radius 1500 --contour-interval 50
terrology "Peak District" --radius 3000 --contour-interval 25 --terrain-exag 3

Bridges — road and railway segments tagged bridge=yes in OSM sit at the correct elevated position rather than being depressed into the hillside.

Slicers without OBJ support — import terrain.stl, water.stl, parks.stl, and roads.stl together and assign each a filament. Only files for features present in the map are written.

Map data © OpenStreetMap contributors, licensed under the Open Database Licence.

Elevation data provided by OpenTopography. Datasets used:

• GLO-30 (glo30) — © DLR/ESA, distributed under CC BY 4.0
• SRTM GL1 (srtm) — NASA/USGS, public domain
• AW3D30 (aw3d30) — © JAXA, distributed under CC BY 4.0