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:
| Engine | Draws | Time per tile |
|---|---|---|
| Direct | Every 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 readers | 0.05 to 2.5 s |
| Browser | Everything: the app itself in a headless browser, so every source, every mode, imagery, 3D, split views and combined layouts | 3 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-tilesThen 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
| Address | Answers | Like |
|---|---|---|
/tiles/{z}/{x}/{y}.png or .jpg | One Web Mercator tile by its index. 256 px; {y}@2x or tilesize=512 for 512 px | An XYZ tile layer, titiler's /tiles |
/render.png or .jpg | A 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 split | A 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:
| Parameter | Meaning |
|---|---|
terrainSource | An 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) |
modes | Comma-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, imageryDate | Imagery under the terrain, drawn with the mode basemap |
engine | auto (the default: direct when it can), direct (an error when it cannot), browser |
mapboxKey, maptilerKey, cesiumIonKey | Your 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 else | Passed 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:
| Address | Lists |
|---|---|
/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 |
/algorithms | The 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.
| Mode | Layer | Features |
|---|---|---|
contours | contours | Lines, ele (metres) and level (1 for a major line), the app's own contour tiles; on the local relief model with contourReferenceMode=lrm |
isoline | isoband, isoline, isoline-cliff | At 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 |
moundDetector | tells | A point per candidate with its measures (a, blobness, plan, detHessian, pit, scaleM, ...) |
graticules | graticule | Meridians 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:
| Mode | Raster tile (/tiles) | Vector tile (/vector) |
|---|---|---|
| Hillshade, colour relief, the 14 computed modes, matcap, Phong, cast shadows | Yes | No: they are images |
| Plane slicer | Yes | No: 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, graticule | Yes, drawn from the same vector tiles | Yes |
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,contoursmap.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.
| titiler | Here |
|---|---|
/tiles/WebMercatorQuad/{z}/{x}/{y}@2x.png | The same tile as /tiles/{z}/{x}/{y}@2x.png |
/WebMercatorQuad/tilejson.json | A 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 |
url | Read as terrainSource |
algorithm | Read as one name of modes |
tilesize | 256 or 512 |
rescale, colormap_name, bidx, expression, nodata, other tile matrix sets | Not 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.
| Layers | How |
|---|---|
| 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 dominance | The 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 |
| Hillshade | MapLibre'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, Phong | The 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 shadows | The app's tile protocol |
| Contours | maplibre-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-line | At 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 detector | The 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 slicer | The colour relief the map draws for it, on the elevation or on the local relief model |
| Graticule | The 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 theme | The 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:
| Type | Read by |
|---|---|
| Terrarium, Terrain-RGB, custom RGB packing | The tiles fetched and decoded in the server |
| PMTiles | pmtiles://, Range reads of the archive |
| COG | cog:// (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 |
| VRT | vrt://: 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 mesh | quantized-mesh://, the meshes rasterised |
| Difference (nDSM, change) | demdiff:// over its two operands, each read as above |
| TileJSON | The 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.
| Case | Largest mean difference (0-255) | Largest share of pixels off by more than 24 | Direct, median | Browser, median |
|---|---|---|---|---|
| hillshade (combined, default) | 0.9 | 0 % | 451 ms | 6290 ms |
| hillshade standard | 2.27 | 0.97 % | 141 ms | 5811 ms |
| hillshade igor | 1.6 | 0 % | 125 ms | 5885 ms |
| hillshade basic, light 200/30 | 0.21 | 0.09 % | 82 ms | 4002 ms |
| hillshade combined, exaggeration 0.6, coloured | 0.65 | 0 % | 122 ms | 5057 ms |
| hillshade multidir-colors | 0.82 | 0 % | 124 ms | 4205 ms |
| hillshade duotone-nw-ne | 0.51 | 0 % | 110 ms | 5075 ms |
| hillshade aspect-multidir | 1.08 | 0 % | 112 ms | 4524 ms |
| colour relief (default) | 0.22 | 0 % | 53 ms | 3931 ms |
| colour relief dem_screen 300-4500, opaque | 0.07 | 0 % | 54 ms | 4555 ms |
| slope | 0.02 | 0 % | 864 ms | 4607 ms |
| slope 0-45 inverted | 0.04 | 0 % | 121 ms | 5509 ms |
| aspect | 0.15 | 0 % | 174 ms | 5589 ms |
| TRI | 0.1 | 0 % | 122 ms | 5216 ms |
| curvature | 0.17 | 0 % | 121 ms | 5423 ms |
| TPI | 0.22 | 0 % | 141 ms | 4948 ms |
| roughness | 0.21 | 0 % | 190 ms | 5446 ms |
| shape index | 5.61 | 3.24 % | 188 ms | 5579 ms |
| blobness | 0.13 | 0 % | 168 ms | 4610 ms |
| eigen ratio | 0.18 | 0 % | 206 ms | 5635 ms |
| orientation | 0.07 | 0 % | 263 ms | 5047 ms |
| LRM | 0.17 | 0 % | 343 ms | 4234 ms |
| LRM radius 32 | 0.2 | 0 % | 366 ms | 4578 ms |
| sky-view factor | 0.06 | 0 % | 855 ms | 5691 ms |
| openness | 0.07 | 0 % | 765 ms | 5597 ms |
| local dominance | 0.09 | 0 % | 1112 ms | 5703 ms |
| contours | 2.83 | 1.8 % | 556 ms | 5973 ms |
| contours 20/100 | 5.34 | 3.15 % | 440 ms | 5829 ms |
| matcap (live renderer in the app) | 1.82 | 0.26 % | 222 ms | 5165 ms |
| matcap, raster renderer | 0.64 | 0 % | 286 ms | 5431 ms |
| phong (live renderer in the app) | 1.72 | 0.15 % | 211 ms | 4952 ms |
| phong, raster renderer | 0.26 | 0 % | 225 ms | 4848 ms |
| cast shadows | 0 | 0 % | 228 ms | 4094 ms |
| cast shadows, sun at 15 degrees | 0 | 0 % | 217 ms | 4140 ms |
| phong, rim light 0.6, two lights | 1.36 | 0.14 % | 239 ms | 5138 ms |
| hillshade + colour relief + contours | 2.03 | 1.07 % | 799 ms | 6742 ms |
| slope + hillshade | 0.9 | 0 % | 199 ms | 5607 ms |
| LRM + sky-view factor + hillshade | 1 | 0 % | 977 ms | 5699 ms |
| contours, no labels | 2.13 | 0.97 % | 70 ms | 4046 ms |
| contours of the local relief model | 8.46 | 4.66 % | 1796 ms | 5905 ms |
| iso-line, slope 30 degrees | 1.88 | 2.36 % | 408 ms | 5824 ms |
| iso-line, slope 30 with fill and cliff teeth | 5.21 | 7.6 % | 1802 ms | 7714 ms |
| iso-line, slope every 10 degrees | 1.91 | 2.13 % | 355 ms | 4419 ms |
| iso-line, elevation every 50 m | 1.54 | 1.6 % | 136 ms | 4070 ms |
| graticules | 0.93 | 0 % | 127 ms | 5543 ms |
| plane slicer at 2800 m | 0.53 | 0 % | 135 ms | 5128 ms |
| plane slicer, local relief above 0 | 0.78 | 0 % | 184 ms | 5512 ms |
| mound detector | 2.04 | 1.02 % | 917 ms | 5964 ms |
| dark theme, hillshade + contours | 2.57 | 1.27 % | 293 ms | 6904 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=rasterorphongRenderer=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 mode | 0.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 card | 3 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 week | under 0.1 s |
| Browser viewport, 600 by 400, 3D slope | 3 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
| Variable | Meaning | Default |
|---|---|---|
PORT | The port | 3400 |
TV_BASE_URL | The app to render | https://terrain-viewer.iconem.com/ |
TILE_CACHE_DIR | Where tiles and pictures are kept a week | /data/tiles in the image |
TV_RENDER_CONCURRENCY | Pages rendered at the same time; each is a whole app | 2 |
TV_ALLOWED_HOSTS | Host names accepted in the Host header, comma-separated | any |
TV_MAPBOX_KEY, TV_MAPTILER_KEY, TV_CESIUM_ION_KEY | The operator's keys, used when a request gives none: anyone who can reach the service then uses them | none |
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.
URL as an API (Scalar)
The viewer's URL described as an OpenAPI document, browsed with Scalar — every parameter with the right control for its type
UX flows
The /ux-flows page, a map of the app's screens and the flows a user walks through them, with a real screenshot on every screen - its three views, how the screens are captured by agent-browser, and how to add a screen or a flow