Skip to main content


The TerrainLoader reconstructs mesh surfaces from height map images, e.g. Mapzen Terrain Tiles, which encodes elevation into R,G,B values.

File Extension.png, .pngraw
File TypeBinary
File FormatEncoded height map
Data FormatMesh
Supported APIsload, parse
Decoder TypeAsynchronous
Worker Thread SupportYes
Streaming SupportNo


import {ImageLoader} from '';
import {TerrainLoader} from '';
import {load, registerLoaders} from '';


const data = await load(url, TerrainLoader, options);


terrain.meshMaxErrornumber10Mesh error in meters. The output mesh is in higher resolution (more vertices) if the error is smaller.
terrain.boundsarray<number>nullBounds of the image to fit x,y coordinates into. In [minX, minY, maxX, maxY]. If not supplied, x and y are in pixels relative to the image.
terrain.elevationDecoderobjectSee belowSee below
terrain.tesselatorstringautoSee below
terrain.skirtHeightnumbernullIf set, create the skirt for the tile with particular height in meters


Parameters used to convert a pixel to elevation in meters. An object containing the following fields:

  • rScale: Multiplier of the red channel.
  • gScale: Multiplier of the green channel.
  • bScale: Multiplier of the blue channel.
  • offset: Translation of the sum.

Each color channel (r, g, and b) is a number between [0, 255].

For example, the Mapbox terrain service's elevation is encoded as follows:

height = -10000 + ((R * 256 * 256 + G * 256 + B) * 0.1)

The corresponding elevationDecoder is:

"rScale": 6553.6,
"gScale": 25.6,
"bScale": 0.1,
"offset": -10000

The default value of elevationDecoder decodes a grayscale image:

"rScale": 1,
"gScale": 0,
"gScale": 0,
"offset": 0


The choices for tesselator are as follows:


  • Chooses Martini if possible (if the image is a square where both height and width are powers of 2), otherwise uses Delatin instead, which has no input image limitations.


  • Uses the Martini algorithm for constructing a mesh.
  • Only works on square 2^n+1 x 2^n+1 grids.
  • Generates a hierarchy of meshes (pick arbitrary detail after a single run)
  • Optimized for meshing speed rather than quality.


  • Uses the Delatin algorithm for constructing a mesh.
  • Works on arbitrary raster grids.
  • Generates a single mesh for a particular detail.
  • Optimized for quality (as little triangles as possible for a given error).