Skip to content
Spec00
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

Real-world 3D terrain for three.js from any map tiles — with buildings, roads and bridges, water and vegetation, and a frame for your own layers.
The live example: the Bernese Alps from Lake Brienz to the Aletsch Glacier as 3D terrain with satellite imagery; the panel shows the geolocation of a click on the terrain
Fig. 01The live example · Bernese Alps

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-terrain
  • 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.

  • Buildings

    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 bridges

    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.

  • Your own layers

    FeatureLayer loads the tiles of any source and keeps your geometry in step with the terrain; TileContext drapes 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.

  • Any look

    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 process for its imagery’s pixels. The built-in look — a color, lights, wireframe — is a starting point the layers share.

  • Any source

    Every source takes a preset, a {z}/{x}/{y} URL template, a TileJSON or your own load; 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.

  • Diorama base and export

    TerrainBase closes 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.

  • Large areas, your way

    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.

  • Fast, and tunable

    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 WebGLRenderer and WebGPURenderer, with lights and fog.

  • Well-behaved

    Retries for flaky tile servers, AbortController for pending requests, clean() frees every GPU resource.

  • Small

    TypeScript, ESM + CommonJS, no runtime dependencies (its own vector tile decoder); three is a peer dependency.

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.

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