Terrain Viewer

Tile service (Scalar)

What the app draws, served as XYZ tiles and as pictures of a viewport over HTTP, from a Docker image; its addresses and parameters browsed with Scalar

The app runs in the browser and has no server. The tile service is a small server that hands out what the app draws, so a map library, QGIS or a script can use a Terrain Viewer view without running the app. Two engines draw:

EngineDrawsTime per tile
DirectEvery 2D terrain mode and overlay (contours with labels, iso-line, mound detector, plane slicer, graticule, dark theme), computed in the server by the app's own code from any source the app reads, read with the app's own readers0.05 to 2.5 s
BrowserEverything: the app itself in a headless browser, so every source, every mode, imagery, 3D, split views and combined layouts3 to 10 s for a new block, then milliseconds

Tiles and viewports take the direct engine whenever they can. 3D, tilted, rotated and split views always take the browser, and so do imagery and the few layers listed in What goes to the browser.

docker run -p 3400:3400 --shm-size=1g -v tv-tiles:/data/tiles ghcr.io/iconem/terrain-viewer-tiles

Then http://localhost:3400/docs is the reference below with a working Test request button, and http://localhost:3400/openapi.json its OpenAPI document.

The two answers

AddressAnswersLike
/tiles/{z}/{x}/{y}.png or .jpgOne Web Mercator tile by its index. 256 px; {y}@2x or tilesize=512 for 512 pxAn XYZ tile layer, titiler's /tiles
/render.png or .jpgA picture of a viewport: lat, lng, zoom, or bbox=west,south,east,north, with width and height. Can be tilted (viewMode=3d, pitch, bearing) or splitA WMS GetMap

A tile is the map alone. A viewport keeps the scale bar and the credits.

Both take the view as query parameters, the same words the MCP server uses:

ParameterMeaning
terrainSourceAn id from /sources (the built-in sources and the library), the address of Terrarium tiles, of a COG (.tif) or of a VRT (.vrt), or a configuration as JSON with the fields of a library entry: {"url": "…/{z}/{x}/{y}.png", "type": "terrainrgb", "maxzoom": 15} (types terrarium, terrainrgb, cog, vrt, wms-raw, lerc, quantized-mesh, tilejson)
modesComma-separated: hillshade, colorRelief, contours, slope, aspect, curvature, tpi, roughness, lrm, svf, openness, localDominance, phong, matcap, shadows, moundDetector, isoline, graticules, planeSlicer, basemap (also tri, shapeIndex, blobness, eigenRatio, orientation)
imageryUrl, imagerySource, imageryDateImagery under the terrain, drawn with the mode basemap
engineauto (the default: direct when it can), direct (an error when it cannot), browser
mapboxKey, maptilerKey, cesiumIonKeyYour own API key, for the Mapbox, MapTiler and Cesium ion sources. The direct engine's readers use it, and the browser engine gives it to the app as a setting, never in the app's address. A tile made with a key is cached apart from one made without
anything elsePassed to the app as a URL parameter: ramps, opacities, light direction, contour interval

Every answer says which engine drew it in its x-tv-engine header, and x-tv-engine-why says why not the direct one.

Names, not addresses

Like titiler's list of tile matrix sets, three lists give the ids the parameters take:

AddressLists
/sources, /sources/{id}The 141 terrain sources: built-in and library, with type, tile address, zoom range, extent, and the engine that can draw each
/colorramps, /colorramps/{id}The app's 268 colour ramps, to name as colorRamp (colour relief) or slopeColorRamp (slope); one ramp gives its stops
/algorithmsThe modes with the engine that draws each

A source that is not listed can still be given whole, as its address or as a JSON configuration.

Vector tiles

/vector/{z}/{x}/{y}.pbf answers the line, area and point overlays as a Mapbox Vector Tile, the features the app's own layers draw, one layer each. modes picks them, the app's parameters set them as for the raster tiles, and /vector/tilejson.json?modes=… gives a TileJSON for a MapLibre vector source. Tiles are 512 px, as the map loads them; past a layer's last zoom (15 for the mound detector, the source's for the others) a tile is cut from its deepest one, scaled up.

ModeLayerFeatures
contourscontoursLines, ele (metres) and level (1 for a major line), the app's own contour tiles; on the local relief model with contourReferenceMode=lrm
isolineisoband, isoline, isoline-cliffAt a value: the band above it as polygons, its edge as lines, and on slope the simplified cliff edge the teeth hang from. Every interval: isoline lines with ele
moundDetectortellsA point per candidate with its measures (a, blobness, plan, detHessian, pit, scaleM, ...)
graticulesgraticuleMeridians and parallels at the app's spacing for the zoom, kind and deg

/contours/{z}/{x}/{y}.pbf is the same tile with the contours alone.

Every mode, raster or vector:

ModeRaster tile (/tiles)Vector tile (/vector)
Hillshade, colour relief, the 14 computed modes, matcap, Phong, cast shadowsYesNo: they are images
Plane slicerYesNo: the app draws it as a colour layer. The same edge as polygons: isoline on elevation at the slice's height
Contours, iso-line, mound detector, graticuleYes, drawn from the same vector tilesYes

The raster tile of these four is made from the vector tiles: their features are read, then drawn with the app's widths, colours and opacities, the contour labels and the cliff teeth placed as MapLibre places line symbols.

map.addSource("tv-overlays", { type: "vector", url: "http://localhost:3400/vector/tilejson.json?modes=contours,moundDetector" })
map.addLayer({ id: "contour-lines", type: "line", source: "tv-overlays", "source-layer": "contours", paint: { "line-width": ["match", ["get", "level"], 1, 1, 0.5] } })
map.addLayer({ id: "contour-labels", type: "symbol", source: "tv-overlays", "source-layer": "contours", filter: ["==", ["get", "level"], 1], layout: { "symbol-placement": "line", "text-field": ["concat", ["get", "ele"], " m"], "text-size": 10 } })
map.addLayer({ id: "mounds", type: "circle", source: "tv-overlays", "source-layer": "tells", paint: { "circle-radius": 8, "circle-color": "rgba(0,0,0,0)", "circle-stroke-color": "#ef4444", "circle-stroke-width": 2 } })

Raster tiles in a map

/tiles/{z}/{x}/{y}.png?modes=slope&terrainSource=custom-nl-ahn-dtm
/render.jpg?bbox=6.7,45.75,7.0,45.95&width=800&height=600&modes=hillshade,contours
map.addSource("tv-slope", { type: "raster", tileSize: 256, tiles: ["http://localhost:3400/tiles/{z}/{x}/{y}.png?modes=slope"] })

titiler's addresses

A client written for titiler needs few changes: the service answers at the same addresses, for Web Mercator only.

titilerHere
/tiles/WebMercatorQuad/{z}/{x}/{y}@2x.pngThe same tile as /tiles/{z}/{x}/{y}@2x.png
/WebMercatorQuad/tilejson.jsonA TileJSON whose tile address keeps the parameters given; tile_format, tile_scale
/bbox/{w},{s},{e},{n}/{width}x{height}.png/render with bbox, width, height
urlRead as terrainSource
algorithmRead as one name of modes
tilesize256 or 512
rescale, colormap_name, bidx, expression, nodata, other tile matrix setsNot read. The app's own parameters set the ramps

What the direct engine draws

The direct engine computes the tile in the server, with no browser. It opens nothing: it rebuilds the map's layer stack from the same URL parameters the app would read, and computes every layer with the app's own code, bundled for Node.

LayersHow
Colour relief, and the 14 computed modes: slope, aspect, TRI, curvature, TPI, LRM, roughness, shape index, blobness, eigen ratio, orientation, sky-view factor, openness, local dominanceThe app's tile protocols (lib/*-protocol.ts), coloured with the paint the map computes (lib/layer-paints.ts, lib/mode-relief.ts) and interpolated between the ramp's stops as MapLibre does
HillshadeMapLibre's two shader passes, rewritten in JavaScript line by line, fed with the paint the map computes: the five methods and the app's three multi-light presets
Matcap, PhongThe app's live GL layers, its default renderer: their fragment shaders rewritten in JavaScript (the normal of each pixel from the bilinear elevation, Phong's multiply and add passes over the layers below, the camera-relative matcap lookup). With matcapRenderer=raster or phongRenderer=raster, the app's tile protocols, as the app then draws them
Cast shadowsThe app's tile protocol
Contoursmaplibre-contour, the app's contour library, with its intervals, widths and colours; on the terrain, or on its local relief model with contourReferenceMode=lrm. The labels are drawn on the picture (elevation and "m" on major lines, Noto Sans bold 10 px with a halo, upright), where MapLibre puts line symbols: per vector tile, every 250 px from where the line enters it, not where it turns more than 45°, and not over an earlier label. Straight, where MapLibre bends the letters along the line. The vector tiles carry ele for a client that places its own
Iso-lineAt a value: the app's isoband:// vector tiles over the chosen measure (elevation, slope, any computed mode or lighting), the fill and the line, and on slope the cliff teeth, every 28 px from where MapLibre starts them on each tile. Every interval: the contour engine over the measure's tiles
Mound detectorThe app's tells:// vector tiles, a circle per candidate with the map's radius (fixed, or the measured diameter times tellsScaleMultiplier) and colours (outline, or coloured by blobness, plan curvature, Hessian or LRM)
Plane slicerThe colour relief the map draws for it, on the elevation or on the local relief model
GraticuleThe lines at the app's spacing for the zoom, or graticuleDensity. Its labels sit on the edges of the screen in the app, so a tile has none
Dark themeThe black background, and the contour, label and graticule colours that follow the theme

The layers stack in the map's order (the relief and lighting layers, then iso-line and graticule, mound markers, plane slicer, and the contours on top) over its white or black background, each composited with the app's opacity for it, so any combination of modes is drawn as the map draws it. A colour ramp is read as MapLibre reads it: the stops rounded to the elevation encoding's step and the colours taken from an 8-bit texture. Every URL parameter the app reads for these layers applies: ramps, ranges, inversion, custom ramp stops, radii, light direction, exaggeration, opacities.

Sources

The direct engine reads every source type the app reads, with the app's own readers. What a source's elevation tiles are (template, RGB packing, tile size, zoom range) comes from the function the map uses for its own decoders, terrainTileSpec in lib/terrain-tile-spec.ts, with the app's default settings (the in-browser COG reader on, Terrarium tiles, titiler at titiler.xyz). The readers are the app's protocols, registered in Node through the app's registry (lib/protocol-registry.ts) by mcp/app-sources.ts:

TypeRead by
Terrarium, Terrain-RGB, custom RGB packingThe tiles fetched and decoded in the server
PMTilespmtiles://, Range reads of the archive
COGcog:// (geotiff.js), with the elevation colour function the map registers. A COG the in-browser reader refuses, or one pinned to titiler (cogViaTitiler, most of the library's), is read through titiler as in the app
VRTvrt://: the VRT's own index, its files Range-read by geotiff.js and warped by proj4. Also GEM-15, Open Buildings and Meta's canopy height, whose indexes come from the deployed app. A VRT pinned to titiler goes through titiler
WMS, WCS, ArcGIS exportImage (wms-raw)float32dem://, one Float32 GeoTIFF request per tile
LERC (ArcGIS tiled elevation, Esri World Elevation)lerc://, Esri's wasm decoder
Quantized meshquantized-mesh://, the meshes rasterised
Difference (nDSM, change)demdiff:// over its two operands, each read as above
TileJSONThe manifest's tile template

Mapbox, MapTiler and Cesium ion are read with your API key (mapboxKey, maptilerKey, cesiumIonKey); without one neither engine can draw them, and a key the provider refuses gives an error that says so. Not read in the server, so drawn by the browser: a local file, a source whose address is not https (one demo entry of the library), STAC and MosaicJSON entries (none among the terrain sources), and a COG or VRT that does not answer. /sources gives each source its engine, and the reason when it is the browser.

What goes to the browser

3D, tilted, rotated and split views (the camera is the app's); imagery and basemaps; building shadows (OpenStreetMap buildings); the sky and fog background; the historical mode; a source the server does not read (see Sources). The answer's x-tv-engine-why header names the reason.

Compared with the app

Run on 2026-11-21, the rows with contours, the iso-line teeth and the mound detector again on 2026-11-22: every case below drawn by both engines at the same index, at Matterhorn (z12, 4,000 m of relief) and in Paris (z14, almost flat), as 256 px tiles and as @2x, 196 pairs. The table keeps the worst of the four tiles for each case; times are the median of the four, with the elevation tiles already in memory for the direct engine and a new 2048 px block for each browser tile.

CaseLargest mean difference (0-255)Largest share of pixels off by more than 24Direct, medianBrowser, median
hillshade (combined, default)0.90 %451 ms6290 ms
hillshade standard2.270.97 %141 ms5811 ms
hillshade igor1.60 %125 ms5885 ms
hillshade basic, light 200/300.210.09 %82 ms4002 ms
hillshade combined, exaggeration 0.6, coloured0.650 %122 ms5057 ms
hillshade multidir-colors0.820 %124 ms4205 ms
hillshade duotone-nw-ne0.510 %110 ms5075 ms
hillshade aspect-multidir1.080 %112 ms4524 ms
colour relief (default)0.220 %53 ms3931 ms
colour relief dem_screen 300-4500, opaque0.070 %54 ms4555 ms
slope0.020 %864 ms4607 ms
slope 0-45 inverted0.040 %121 ms5509 ms
aspect0.150 %174 ms5589 ms
TRI0.10 %122 ms5216 ms
curvature0.170 %121 ms5423 ms
TPI0.220 %141 ms4948 ms
roughness0.210 %190 ms5446 ms
shape index5.613.24 %188 ms5579 ms
blobness0.130 %168 ms4610 ms
eigen ratio0.180 %206 ms5635 ms
orientation0.070 %263 ms5047 ms
LRM0.170 %343 ms4234 ms
LRM radius 320.20 %366 ms4578 ms
sky-view factor0.060 %855 ms5691 ms
openness0.070 %765 ms5597 ms
local dominance0.090 %1112 ms5703 ms
contours2.831.8 %556 ms5973 ms
contours 20/1005.343.15 %440 ms5829 ms
matcap (live renderer in the app)1.820.26 %222 ms5165 ms
matcap, raster renderer0.640 %286 ms5431 ms
phong (live renderer in the app)1.720.15 %211 ms4952 ms
phong, raster renderer0.260 %225 ms4848 ms
cast shadows00 %228 ms4094 ms
cast shadows, sun at 15 degrees00 %217 ms4140 ms
phong, rim light 0.6, two lights1.360.14 %239 ms5138 ms
hillshade + colour relief + contours2.031.07 %799 ms6742 ms
slope + hillshade0.90 %199 ms5607 ms
LRM + sky-view factor + hillshade10 %977 ms5699 ms
contours, no labels2.130.97 %70 ms4046 ms
contours of the local relief model8.464.66 %1796 ms5905 ms
iso-line, slope 30 degrees1.882.36 %408 ms5824 ms
iso-line, slope 30 with fill and cliff teeth5.217.6 %1802 ms7714 ms
iso-line, slope every 10 degrees1.912.13 %355 ms4419 ms
iso-line, elevation every 50 m1.541.6 %136 ms4070 ms
graticules0.930 %127 ms5543 ms
plane slicer at 2800 m0.530 %135 ms5128 ms
plane slicer, local relief above 00.780 %184 ms5512 ms
mound detector2.041.02 %917 ms5964 ms
dark theme, hillshade + contours2.571.27 %293 ms6904 ms

What the remaining differences are:

  • Contour labels: the lines are the same, from the same library and options, and the labels are placed as MapLibre places them, but MapLibre decides collisions over the whole 2048 px block in its own order and bends the letters along the line, so a few labels are kept by one engine only. Without labels, 2.1; what is left is the anti-aliasing of thin lines where they crowd, at the local relief model 5.0.
  • Shape index: in Paris, every difference is a pixel at exactly +1 (a dome), drawn transparent by the app and dark red by the direct engine. That is an app bug, fixed in this release (see the changelog): MapLibre rounds a ramp's stops to the elevation's encoding, so the last pair of a discrete ramp became one value and the shader divided 0 by 0. Once the fix is deployed both engines draw it dark red.
  • Iso-line cliff teeth: placed as MapLibre places them; a few teeth are kept on one side only near the ends of short lines.
  • Mound markers: the same circles; MapLibre's circle shader smooths a ring's edges inside it, which the server's rings now follow (half a pixel inward), from 11 to 2.
  • Hillshade on flat ground: the gradient is kept in 8 bits, as in MapLibre's own texture, and a tiny slope rounds one way or the other.
  • Matcap and Phong: compared with the app's default live renderer, and with its raster renderer when matcapRenderer=raster or phongRenderer=raster.

Sources other than Mapterhorn compare the same way: a COG within 0.4 to 2.5, a VRT 0.2 to 0.8, a WMS 0.02 to 1.3, LERC 0.02 to 1.7, quantized mesh 0.01 to 0.5 (hillshade, colour relief and slope). Where a source has holes, the direct engine leaves them transparent while the map draws them at the fill height titiler gives them (0 m), so a GEM-15 hole or the ground under a building in a nDSM differs; the map's own source configuration and the decoders' will be one in the coming source schema.

node mcp/compare-engines.mjs <service> runs the comparison again and writes the table and, for each case, the two tiles side by side with their difference.

How the browser draws a tile, and how fast

The browser engine does not compute a tile: the app draws it. For a tile, the app is opened on the 2048 px block that holds it (8 by 8 tiles of 256 px), the picture is cut into tiles, and all of them are kept a week on disk (/data/tiles in the image).

Measured on a laptop on 2026-11-21:

Time
Direct tile, one mode0.03 to 0.4 s once the elevation tiles are in memory; up to 2.5 s for local dominance or a first tile
Direct viewport, 900 by 600, three modes (MCP picture)1.8 s
Browser, first tile of a block, Chrome with a graphics card3 to 9 s
Browser, first tile of a block, in the container (no graphics card)10 s
Browser, its 63 neighbours, and any tile asked again within a weekunder 0.1 s
Browser viewport, 600 by 400, 3D slope3 s

An imagery tile from the browser engine equals the provider's own tile of the same index (mean difference 1.7 on 255, the JPEG compression), and joins its neighbour without a seam.

The browser engine suits a few views, a cache filled in advance, or pictures of 3D views for a report or an assistant; not a busy map. The direct engine can serve a live map.

Settings

VariableMeaningDefault
PORTThe port3400
TV_BASE_URLThe app to renderhttps://terrain-viewer.iconem.com/
TILE_CACHE_DIRWhere tiles and pictures are kept a week/data/tiles in the image
TV_RENDER_CONCURRENCYPages rendered at the same time; each is a whole app2
TV_ALLOWED_HOSTSHost names accepted in the Host header, comma-separatedany
TV_MAPBOX_KEY, TV_MAPTILER_KEY, TV_CESIUM_ION_KEYThe operator's keys, used when a request gives none: anyone who can reach the service then uses themnone

The browser in the container reads any address given as a source: keep the service away from a private network, or behind a proxy that restricts who can call it. It has no sign-in.

The code is mcp/tile-server.mjs. The direct engine is mcp/direct.mjs, on the elevation reader mcp/dem.mjs, which the MCP server's elevation and export_geotiff tools use too. The browser engine is mcp/render.mjs, shared with the MCP server's pictures. Neither service imports the other. With TV_RENDER_URL set to the tile service's address, the MCP server asks it for its pictures in place of rendering them, which is how mcp/docker-compose.yml wires the two. The MCP server's elevation tools need no browser any more, and its pictures of flat views are drawn by the direct engine in the server itself; only 3D, imagery and the other browser layers need a browser, its own or the tile service's.

Not yet run on a server.

Reference

The document is written by mcp/tile-openapi.mjs. Test request below calls http://localhost:3400, so it answers when the container runs on your computer.

On this page