terrology

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 16 Open GitHub ↗

Generate 3D-printable terrain maps from OpenStreetMap + elevation data

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

---
title: Terrology
emoji: 🗺️
colorFrom: green
colorTo: blue
sdk: docker
app_port: 8000
pinned: false
---

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

---

## Examples

<table>
<tr>
<td align="center"><img src="examples/urban/urban.png" width="360"/> Urban — Canary Wharf, London</td>
<td align="center"><img src="examples/mountain/mountain.png" width="360"/> Mountain — Snowdon with 50 m contours</td>
</tr>
<tr>
<td align="center"><img src="examples/two-point/twopoint.png" width="360"/> Two-point — Edinburgh Castle to Arthur's Seat</td>
<td align="center"><img src="examples/route/route.png" width="360"/> Route — Beacon Fell Country Park GPX</td>
</tr>
<tr>
<td align="center" colspan="2"><img src="examples/coastal/coastal.png" width="360"/> Coastal — St Ives, Cornwall</td>
</tr>
</table>

---

## Installation

Install [uv](https://docs.astral.sh/uv/), then:

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

Or clone and run directly:

```bash
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](https://portal.opentopography.org/requestApiKey):

```bash
export OPENTOPOGRAPHY_API_KEY=your_key
```

Or save it once:
```bash
terrology --save-api-key <your_key>
```

---

## Usage

```bash
terrology <location> [options]
```

### Modes

**Single location** — square map centred on a point:
```bash
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):
```bash
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:
```bash
terrology --area central_park.geojson
terrology --area manhattan.geojson --dem srtm
```
Draw or export a polygon from [geojson.io](https://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:
```bash
terrology --route my_ride.gpx
terrology --route trail.gpx --route-width 2.0 --terrain-exag 3
```

---

## Web interface

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):**
```bash
uv tool install "git+https://github.com/twigley/terrology[web]"
terrology-web
```

**Run locally (cloned repo):**
```bash
uv run uvicorn web.app:app --host 0.0.0.0 --port 8000
```

Then open `http://localhost:8000`.

**Run with Docker:**
```bash
docker build -t terrology .
docker run -p 8000:8000 -e OPENTOPOGRAPHY_API_KEY=your_key terrology
```

### Hosting

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**.

#### Free options

| Platform | RAM | Sleep policy | Credit card | Notes |
|---|---|---|---|---|
| [Oracle Cloud Always Free](https://www.oracle.com/cloud/free/) | 24 GB (ARM VM) | Never | Required (verification only, never charged) | Best free option; full VM with Docker. ARM instances are often at capacity in popular regions — may take retries to provision |
| [Hugging Face Spaces](https://huggingface.co/spaces) | 16 GB | After 48 h inactivity | Not required | Run as a Docker Space. Terrology's poll-based job API avoids the platform's HTTP timeout limits |

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.

#### Paid options

| Platform | Plan | RAM | Cost |
|---|---|---|---|
| [Hetzner Cloud](https://www.hetzner.com/cloud/) | CX22 | 4 GB | ~€4/mo |
| [Railway](https://railway.app) | Hobby | up to 8 GB | ~$5/mo |
| [Fly.io](https://fly.io) | shared-cpu-1x | 1 GB | ~$5/mo |
| Self-hosted VPS | — | 1 GB+ | varies |

**Fly.io quickstart:**
```bash
fly launch          # detects the Dockerfile, creates fly.toml
fly secrets set OPENTOPOGRAPHY_API_KEY=your_key
fly deploy
```

**Environment variables:**

| Variable | Default | Description |
|---|---|---|
| `OPENTOPOGRAPHY_API_KEY` | — | Required for `srtm` and `aw3d30` DEM sources |
| `TERROLOGY_NO_RATE_LIMIT` | unset | Set to `1` to disable the 5 jobs/hour/IP rate limit |
| `MAX_CONCURRENT_JOBS` | `1` | Max simultaneous jobs — increase on larger instances (allow ~600 MB RAM per job) |
| `TERROLOGY_JOB_DIR` | `/tmp/terrology` | Directory for job output files |

---

## Output files

| File | Description |
|---|---|
| `terrain.stl` | Full terrain solid — use for mono-colour printing |
| `buildings.stl` | Building extrusions only |
| `water.stl` | Water surface patch (lakes, rivers, sea) |
| `parks.stl` | Parks/woodland surface patch |
| `roads.stl` | Roads/paths surface patch |
| `model.obj` + `model.mtl` | Combined coloured model for multi-colour slicers |
| `model.3mf` | Bambu Studio 3MF with per-face colour metadata |

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.

### Materials

| Material | Used for |
|---|---|
| `terrain` | Terrain surface and buildings |
| `water` | Lakes, rivers, sea |
| `parks` | Parks, woodland, grassland |
| `roads` | Roads, paths |
| `route` | GPX route line (route mode only) |

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

---

## Options

### Location / extent

| Flag | Default | Description |
|---|---|---|
| `location` | — | Place name or `"lat,lon"` — omit when using `--area` or `--route` |
| `--to` | — | Second location for a two-point map |
| `--area` | — | GeoJSON file whose first polygon defines the map boundary |
| `--route` | — | GPX file (route mode) |
| `--radius` | `500` | Radius in metres (single-point mode) |
| `--buffer` | `0.05` | Edge buffer as a fraction of span (two-point / area / route mode) |

### Model size & scale

| Flag | Default | Description |
|---|---|---|
| `--size` | `190` | Longest model dimension in mm |
| `--scale` | auto | Scale denominator — overrides `--size` (e.g. `3000` → 1:3000) |
| `--terrain-exag` | `2.0` | Vertical exaggeration of terrain height |

### Quality

| Flag | Default | Description |
|---|---|---|
| `--grid-size` | `200` | Terrain base mesh resolution N×N |
| `--color-grid-size` | `800` | Colour surface mesh resolution N×N — higher gives finer roads/paths |
| `--color-depth` | `1.5` | Depth (mm) colour features project into terrain — limits filament changes to surface layers |
| `--nozzle` | `0.4` | Nozzle diameter in mm. Both grid sizes are capped at `model_size ÷ (2 × nozzle)` so no cell is finer than the minimum printable feature. |
| `--dem` | `glo30` | Elevation dataset — see table below |

#### DEM sources

| Value | Resolution | Coverage | Notes |
|---|---|---|---|
| `glo30` *(default)* | 30 m | Global | Copernicus GLO-30 via public S3 — no API key needed |
| `srtm` | 30 m | Global (±60°) | SRTM GL1 via OpenTopography — smoother in dense urban areas |
| `aw3d30` | 30 m | Global | ALOS AW3D30 via OpenTopography — often sharper in mountains; better bridge deck elevation |

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.

### Colour

| Flag | Default | Description |
|---|---|---|
| `--colors` | `4` | Number of materials — priority order: terrain+buildings, water, parks, roads. Route mode always uses 2 (terrain + route). |
| `--route-width` | `1.5` | Route line width on the printed model in mm |
| `--contour-interval` | — | Draw elevation contour lines every N real-world metres (e.g. `--contour-interval 50`). Uses a contrasting colour from the existing palette — no extra filament needed. |

### Misc

| Flag | Default | Description |
|---|---|---|
| `--output` | `./output` | Output directory |
| `--save-api-key` | — | Save an OpenTopography API key to `~/.config/terrology/config` and exit |
| `--no-terrain` | — | Skip terrain — buildings and features only |
| `--no-buildings` | — | Skip building extrusion — terrain and features only |
| `--no-cache` | — | Ignore cached downloads |
| `--smooth-boundary` | `0` | Smooth the `--area` polygon outline with N iterations of Chaikin corner-cutting (e.g. `3`–`5`). Rounds sharp corners between GeoJSON vertices. |

---

## Tips

**API key** — set once as an environment variable so you don't have to pass it every run:
```bash
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](https://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.
```bash
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.
```bash
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.

---

## Data sources

Map data © [OpenStreetMap contributors](https://www.openstreetmap.org/copyright), licensed under the [Open Database Licence](https://opendatacommons.org/licenses/odbl/).

Elevation data provided by [OpenTopography](https://opentopography.org/). 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

terrology

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README