- Renderer
- WebGL · WebGPU
- Elevation
- AWS · Mapterhorn · yours
- Imagery
- any {z}/{x}/{y}
- Layers
- buildings · roads · water · trees
- Picking
- lat · lon · alt · feature
- Export
- GLB · STL · OBJ · USDZ
- Dependencies
- 0 · three ≥ 0.152
- License
- MIT
three-map-terrain
Elevation and imagery from any source, OpenStreetMap buildings standing on the terrain and roads lying exactly on it, the geolocation math to put your data there, and model files — GLB, STL, USDZ — to take it anywhere. Every stage is yours to replace: the data, how it is read, the geometry, the materials.
npm install three three-map-terrainFeatures
Section titled “Features”-
Terrain from real elevation
AWS Terrain Tiles, Mapterhorn, Mapbox, MapTiler or your own, at any zoom, as a grid of tiles around a location or any rectangle of tiles.
-
OpenStreetMap buildings from OpenFreeMap, VersaTiles, MapTiler, Mapbox, Protomaps or the Overpass API, or any data you load (Overture Maps in an example), standing on the rendered terrain.
-
Roads and railways lying exactly on the terrain, cut along its triangles; bridges as decks on piers spanning valleys, joined across tiles; tunnels left out.
-
Water and vegetation
Lakes, the sea and rivers lying on the terrain, islands left land; woods filled with trees and scrub with bushes (instanced), single trees and bushes where they stand — or what you plant.
-
FeatureLayerloads the tiles of any source and keeps your geometry in step with the terrain;TileContextdrapes polygons and lines on it, extrudes them or places your models. The built-in layers are made of it, and you can replace or extend their geometry. -
Every part of a layer takes your material, with UVs in meters so that textures repeat at true size; the terrain takes a material factory (PBR, shaders, node materials) and a
processfor its imagery’s pixels. The built-in look — a color, lights, wireframe — is a starting point the layers share. -
Every source takes a preset, a
{z}/{x}/{y}URL template, a TileJSON or your ownload; a basemap tile is loaded once for all the layers reading it; tiles missing or beyond a source’s zoom are cut out of their ancestors. -
Picking
The geolocation under the pointer, the building or road there (never one the terrain hides), highlighted over any material.
-
TerrainBasecloses the terrain into a solid block; GLB, glTF, OBJ, STL (3D printing) or USDZ (AR) of everything, in meters. -
Seamless while streaming
Tiles are stitched to their neighbours the moment they load, and what lies on them follows: no cracks, no walls, no roads floating or sinking.
-
Tiles loaded ahead of the camera and removed behind it, a detailed middle in coarser rings with skirts closing the steps between them, in a few lines — the policy yours.
-
Layers draw a few tiles at a time between frames, picking tests only the triangles under the ray, and the costs are yours to set: imagery detail, layers hidden beyond a distance, and more.
-
Plain three.js
Built-in materials, no custom shaders: works with
WebGLRendererandWebGPURenderer, with lights and fog. -
Well-behaved
Retries for flaky tile servers,
AbortControllerfor pending requests,clean()frees every GPU resource. -
Small
TypeScript, ESM + CommonJS, no runtime dependencies (its own vector tile decoder);
threeis a peer dependency.
One map, four looks
Section titled “One map, four looks”
Plain a color per part

Textured canvas textures, in meters

Aerial a process of the pixels

Wireframe over a light fill
The live example — a small tool in React Three Fiber: any area of the world, picked on an OpenStreetMap map, its layers switched on and off, one map in four looks, exported as GLB, STL, OBJ or USDZ. Every view is a link.
For AI assistants
Section titled “For AI assistants”Every page is also Markdown: add .md to its URL, or use Copy page above its title. llms.txt lists them, llms-full.txt is all of them in one file — LLMs. For agents that load skills, Claude Code, Codex, Cursor and more, the agent skill has the essentials:
npx skills add whidrubeld/three-map-terrain