Skip to main content

TerrainLoader

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

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

Usageโ€‹

import {ImageLoader} from '@loaders.gl/images';
import {TerrainLoader} from '@loaders.gl/terrain';
import {load, registerLoaders} from '@loaders.gl/core';

registerLoaders(ImageLoader);

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

Optionsโ€‹

OptionTypeDefaultDescription
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

elevationDecoderโ€‹

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
}

tesselatorโ€‹

The choices for tesselator are as follows:

auto:

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

martini:

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

delatin:

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