Claude Skill

maplibre-terrain-rendering

Drawing elevation in MapLibre GL JS once a raster-dem source works — hillshade and `hillshade-method`, the `color-relief` layer and the `["elevation"]` expression, runtime contours with `maplibre-contour`, and 3D terrain with its camera and sky. Use when relief looks harsh, flat,

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download maplibre-maplibre-agent-skills-skills_maplibre-terrain-rendering-a79dc7f.zip · 4 KB

Install

skills CLI npx skills add https://github.com/maplibre/maplibre-agent-skills/tree/main/skills/maplibre-terrain-rendering
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install maplibre-maplibre-agent-skills@llmmart
Git git clone https://github.com/maplibre/maplibre-agent-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole maplibre/maplibre-agent-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

MapLibre Terrain Rendering

A raster-dem source is elevation, not a picture. Four different things draw it, each with its own layer type or API, and most of the wrong answers here are Mapbox GL JS properties that MapLibre never had.

When to Use This Skill

These are symptoms as you would observe them, before you know the cause:

  • Harsh hillshade contrast: black-and-white ridges, blown-out slopes, chalky valleys — or several hillshade layers stacked to soften them (one layer with hillshade-method: "multidirectional").
  • Dynamic elevation coloring: the map needs coloring by height, client-side, with no pre-rendered tiles (a color-relief layer over ["elevation"], not raster-color on a raster layer).
  • Runtime contour lines: contour lines straight from a raster-dem source, with no pre-generated contour tileset (maplibre-contour, not a hand-rolled marching-squares pipeline).
  • Flat 3D terrain: map.setTerrain() is on and nothing extrudes (the camera is at pitch: 0, and raising exaggeration will not fix it).
  • Blank horizon: pitching the camera shows empty page background above the terrain (no root-level sky object or map.setSky(); there is no type: "sky" layer in MapLibre).
  • Unknown-property errors: a hillshade, sky, or terrain-coloring property makes the console log unknown property; the call that set it changes nothing, and a style that holds it does not load (a Mapbox GL JS property MapLibre never had).
  • Terrain lag or frame drops: stutter when panning or tilting with terrain on (stacked hillshade passes, dense draped layers).

Not this skill. Elevation values that are wrong, spiky, or inverted, choosing an elevation tileset, encoding, and generating DEM tiles — the style specification's raster-dem source page, https://maplibre.org/maplibre-style-spec/sources/#raster-dem. Where hillshade sits among the other layers of a style — maplibre-cartography.

Which one you want

Goal What draws it
Shaded relief under a 2D map A hillshade layer. No setTerrain needed — the two are independent
Color by height (hypsometric tint) A color-relief layer (GL JS 5.6)
Contour lines, without pre-generating a tileset The maplibre-contour library, feeding a vector source
A tilted, extruded surface you fly over map.setTerrain() plus camera pitch

All four read the same raster-dem source; one source can serve all of them.

Hillshade, and the harshness fix that is not stacking

Every hillshade-* property is a paint property.[1] The defaults that matter: hillshade-exaggeration 0.5, hillshade-illumination-direction 335, hillshade-illumination-anchor viewport (the light is fixed to the top of the screen, so it does not turn with the map's bearing unless you set map), hillshade-shadow-color #000000, hillshade-highlight-color #FFFFFF.

Harsh output usually comes from the shading method, not the colors. hillshade-method (GL JS 5.5) takes standard (the default), basic, combined, igor, and multidirectional.[1] multidirectional lights the surface from several independent directions in one pass and igor minimizes the effect on the map features drawn beneath it; both soften terrain on a single layer.

{
  "id": "hillshade",
  "type": "hillshade",
  "source": "terrain-dem",
  "paint": {
    "hillshade-method": "multidirectional",
    "hillshade-exaggeration": 0.4,
    "hillshade-illumination-anchor": "map",
    "hillshade-shadow-color": "rgba(30,40,80,0.45)",
    "hillshade-highlight-color": "rgba(255,240,200,0.4)"
  }
}

Do not stack several hillshade layers at different illumination directions. It was the only way to get multi-directional shading before 5.5; since then it is one paint property against N extra draw passes over the same DEM. Pure black shadows and pure white highlights are the other harshness lever: give both an alpha, and use warm highlights with cool shadows over imagery.

Color-relief: coloring by height

color-relief (GL JS 5.6) colors a raster-dem source directly, client-side; there is no pre-rendering step and no raster layer involved. Its paint properties are color-relief-color, color-relief-opacity (default 1), and, from GL JS 5.20, resampling.[1] The ramp is an interpolate expression over ["elevation"], which returns meters above the DEM's vertical datum and is only valid inside color-relief-color.[2]

{
  "id": "hypsometric",
  "type": "color-relief",
  "source": "terrain-dem",
  "paint": {
    "color-relief-color": [
      "interpolate",
      ["linear"],
      ["elevation"],
      0,
      "#2c7bb6",
      500,
      "#abd9e9",
      1500,
      "#ffffbf",
      2500,
      "#fdae61",
      4000,
      "#ffffff"
    ],
    "color-relief-opacity": 0.8
  }
}

MapLibre has no raster-color, raster-value, or raster-color-mix; those belong to another renderer and will be dropped as unknown properties. A raster layer pointed at a DEM shows packed RGB, not a tint.

Contours at runtime

maplibre-contour derives vector contour tiles in a Web Worker from the same DEM tiles and serves them through a registered protocol — no contour tileset to build.[3]

import mlcontour from 'maplibre-contour';

const demSource = new mlcontour.DemSource({
  url: 'https://tiles.mapterhorn.com/{z}/{x}/{y}.webp',
  encoding: 'terrarium',
  maxzoom: 12,
  worker: true
});
demSource.setupMaplibre(maplibregl);

map.addSource('contours', {
  type: 'vector',
  tiles: [
    demSource.contourProtocolUrl({
      thresholds: { 11: [200, 1000], 12: [100, 500], 14: [50, 200] },
      elevationKey: 'ele',
      levelKey: 'level',
      contourLayer: 'contours'
    })
  ],
  maxzoom: 15
});

map.addLayer({
  id: 'contour-lines',
  type: 'line',
  source: 'contours',
  'source-layer': 'contours',
  paint: { 'line-color': 'rgba(0,0,0,0.4)', 'line-width': ['match', ['get', 'level'], 1, 1.2, 0.6] }
});

thresholds maps zoom to [minor, major] intervals in meters; level is 1 on major contours, which is what the line width and any label layer key on.[3] The encoding here must match the DEM exactly as it does on the style source.

3D terrain, the camera, and the sky

map.addSource('terrain-dem', { type: 'raster-dem', url: 'https://tiles.mapterhorn.com/tilejson.json' });
map.setTerrain({ source: 'terrain-dem', exaggeration: 1 });
map.setSky({
  'sky-color': '#199EF3',
  'sky-horizon-blend': 0.5,
  'horizon-color': '#ffffff',
  'horizon-fog-blend': 0.5,
  'fog-color': '#0000ff',
  'fog-ground-blend': 0.5
});
  • terrain takes only source and exaggeration (default 1).[4] It is a root-level style object, set in the style or through map.setTerrain(); map.setTerrain(null) turns it off.
  • Pitch is what makes it visible. At pitch: 0 an extruded surface is seen straight down and reads as flat. Set pitch on the map (or map.easeTo({ pitch: 60 })) before concluding the terrain is broken — and raise exaggeration only after the camera is tilted, never as the fix for a flat-looking map.
  • There is no sky layer type in MapLibre. The layer types are fill, line, symbol, circle, heatmap, fill-extrusion, raster, hillshade, color-relief, and background.[1] Sky is a root-level sky object, or map.setSky(): sky-color, horizon-color, fog-color, sky-horizon-blend, horizon-fog-blend, fog-ground-blend, atmosphere-blend.[5] sky-type, sky-atmosphere-sun, and sky-atmosphere-sun-intensity are Mapbox GL JS properties that style validation rejects: setSky with one applies nothing, and a style whose sky holds one does not load. fog-color requires 3D terrain.[5]
  • Fog is part of sky. MapLibre GL JS has no setFog method and no root fog object; haze comes from fog-color, horizon-fog-blend, and fog-ground-blend in sky.[5] [6]
  • map.queryTerrainElevation(lngLat) returns the elevation under a location once terrain is on.[6]

Cost. Terrain decodes DEM tiles, builds a mesh, and re-draws every layer draped over it, so it is the most expensive thing on this page — noticeably so at high zoom and pitch on low-end devices. Keep the terrain stack small: one shared raster-dem source, one or two elevation layers, and only the overlays you need.

Related Skills

References

  1. Style Specification: layers — hillshade and color-relief paint properties, defaults, hillshade-method values, and the complete list of layer types — https://maplibre.org/maplibre-style-spec/layers/
  2. Style Specification: expressions — ["elevation"], valid only in color-relief-color — https://maplibre.org/maplibre-style-spec/expressions/
  3. maplibre-contour — DemSource, setupMaplibre, contourProtocolUrl — https://github.com/onthegomap/maplibre-contour
  4. Style Specification: terrain — https://maplibre.org/maplibre-style-spec/terrain/
  5. Style Specification: sky — https://maplibre.org/maplibre-style-spec/sky/
  6. GL JS Map API — setTerrain, setSky, queryTerrainElevation — https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/
  7. Examples — 3D terrain, sky, fog, terrain, color relief, contour lines, multidirectional hillshade

This skill is a snapshot. Where a primary source contradicts it — the References above, MapLibre's current documentation, or what MapLibre does when you run it — that source wins. Follow it, then report the disagreement, citing the source and your MapLibre version: editing your installed copy helps no one else and is overwritten on the next update.

Files (maplibre-agent-skills)
  • SKILL.md 11.1 KB
    ---
    name: maplibre-terrain-rendering
    description: Drawing elevation in MapLibre GL JS once a raster-dem source works — hillshade and `hillshade-method`, the `color-relief` layer and the `["elevation"]` expression, runtime contours with `maplibre-contour`, and 3D terrain with its camera and sky. Use when relief looks harsh, flat, or absent, or when the layer type or property for an elevation effect is unclear.
    metadata:
      status: verified
    ---
    
    # MapLibre Terrain Rendering
    
    A `raster-dem` source is elevation, not a picture. Four different things draw it, each with its own layer
    type or API, and most of the wrong answers here are Mapbox GL JS properties that MapLibre never had.
    
    ## When to Use This Skill
    
    These are symptoms as you would observe them, before you know the cause:
    
    - **Harsh hillshade contrast:** black-and-white ridges, blown-out slopes, chalky valleys — or several hillshade layers stacked to soften them (one layer with `hillshade-method: "multidirectional"`).
    - **Dynamic elevation coloring:** the map needs coloring by height, client-side, with no pre-rendered tiles (a `color-relief` layer over `["elevation"]`, not `raster-color` on a `raster` layer).
    - **Runtime contour lines:** contour lines straight from a `raster-dem` source, with no pre-generated contour tileset (`maplibre-contour`, not a hand-rolled marching-squares pipeline).
    - **Flat 3D terrain:** `map.setTerrain()` is on and nothing extrudes (the camera is at `pitch: 0`, and raising `exaggeration` will not fix it).
    - **Blank horizon:** pitching the camera shows empty page background above the terrain (no root-level `sky` object or `map.setSky()`; there is no `type: "sky"` layer in MapLibre).
    - **Unknown-property errors:** a hillshade, sky, or terrain-coloring property makes the console log `unknown property`; the call that set it changes nothing, and a style that holds it does not load (a Mapbox GL JS property MapLibre never had).
    - **Terrain lag or frame drops:** stutter when panning or tilting with terrain on (stacked hillshade passes, dense draped layers).
    
    **Not this skill.** Elevation values that are wrong, spiky, or inverted, choosing an elevation tileset,
    `encoding`, and generating DEM tiles — the style specification's `raster-dem` source page,
    <https://maplibre.org/maplibre-style-spec/sources/#raster-dem>. Where hillshade sits among the other layers
    of a style — [maplibre-cartography](../maplibre-cartography/SKILL.md).
    
    ## Which one you want
    
    | Goal                                            | What draws it                                                         |
    | ----------------------------------------------- | --------------------------------------------------------------------- |
    | Shaded relief under a 2D map                    | A `hillshade` layer. No `setTerrain` needed — the two are independent |
    | Color by height (hypsometric tint)              | A `color-relief` layer (GL JS 5.6)                                    |
    | Contour lines, without pre-generating a tileset | The `maplibre-contour` library, feeding a `vector` source             |
    | A tilted, extruded surface you fly over         | `map.setTerrain()` plus camera pitch                                  |
    
    All four read the same `raster-dem` source; one source can serve all of them.
    
    ## Hillshade, and the harshness fix that is not stacking
    
    Every `hillshade-*` property is a **paint** property.[1] The defaults that matter: `hillshade-exaggeration`
    `0.5`, `hillshade-illumination-direction` `335`, `hillshade-illumination-anchor` `viewport` (the light is
    fixed to the top of the screen, so it does not turn with the map's bearing unless you set `map`),
    `hillshade-shadow-color` `#000000`, `hillshade-highlight-color` `#FFFFFF`.
    
    Harsh output usually comes from the shading **method**, not the colors. `hillshade-method` (GL JS 5.5)
    takes `standard` (the default), `basic`, `combined`, `igor`, and `multidirectional`.[1] `multidirectional`
    lights the surface from several independent directions in one pass and `igor` minimizes the effect on the
    map features drawn beneath it; both soften terrain on a single layer.
    
    ```json
    {
      "id": "hillshade",
      "type": "hillshade",
      "source": "terrain-dem",
      "paint": {
        "hillshade-method": "multidirectional",
        "hillshade-exaggeration": 0.4,
        "hillshade-illumination-anchor": "map",
        "hillshade-shadow-color": "rgba(30,40,80,0.45)",
        "hillshade-highlight-color": "rgba(255,240,200,0.4)"
      }
    }
    ```
    
    **Do not stack several `hillshade` layers at different illumination directions.** It was the only way to
    get multi-directional shading before 5.5; since then it is one paint property against N extra draw passes
    over the same DEM. Pure black shadows and pure white highlights are the other harshness lever: give both an
    alpha, and use warm highlights with cool shadows over imagery.
    
    ## Color-relief: coloring by height
    
    `color-relief` (GL JS 5.6) colors a `raster-dem` source directly, client-side; there is no pre-rendering
    step and no `raster` layer involved. Its paint properties are `color-relief-color`,
    `color-relief-opacity` (default `1`), and, from GL JS 5.20, `resampling`.[1] The ramp is an `interpolate` expression over `["elevation"]`,
    which returns meters above the DEM's vertical datum and **is only valid inside
    `color-relief-color`**.[2]
    
    ```json
    {
      "id": "hypsometric",
      "type": "color-relief",
      "source": "terrain-dem",
      "paint": {
        "color-relief-color": [
          "interpolate",
          ["linear"],
          ["elevation"],
          0,
          "#2c7bb6",
          500,
          "#abd9e9",
          1500,
          "#ffffbf",
          2500,
          "#fdae61",
          4000,
          "#ffffff"
        ],
        "color-relief-opacity": 0.8
      }
    }
    ```
    
    MapLibre has no `raster-color`, `raster-value`, or `raster-color-mix`; those belong to another renderer and
    will be dropped as unknown properties. A `raster` layer pointed at a DEM shows packed RGB, not a tint.
    
    ## Contours at runtime
    
    [`maplibre-contour`](https://github.com/onthegomap/maplibre-contour) derives vector contour tiles in a Web
    Worker from the same DEM tiles and serves them through a registered protocol — no contour tileset to
    build.[3]
    
    ```javascript
    import mlcontour from 'maplibre-contour';
    
    const demSource = new mlcontour.DemSource({
      url: 'https://tiles.mapterhorn.com/{z}/{x}/{y}.webp',
      encoding: 'terrarium',
      maxzoom: 12,
      worker: true
    });
    demSource.setupMaplibre(maplibregl);
    
    map.addSource('contours', {
      type: 'vector',
      tiles: [
        demSource.contourProtocolUrl({
          thresholds: { 11: [200, 1000], 12: [100, 500], 14: [50, 200] },
          elevationKey: 'ele',
          levelKey: 'level',
          contourLayer: 'contours'
        })
      ],
      maxzoom: 15
    });
    
    map.addLayer({
      id: 'contour-lines',
      type: 'line',
      source: 'contours',
      'source-layer': 'contours',
      paint: { 'line-color': 'rgba(0,0,0,0.4)', 'line-width': ['match', ['get', 'level'], 1, 1.2, 0.6] }
    });
    ```
    
    `thresholds` maps zoom to `[minor, major]` intervals in meters; `level` is `1` on major contours, which is
    what the line width and any label layer key on.[3] The `encoding` here must match the DEM exactly as it
    does on the style source.
    
    ## 3D terrain, the camera, and the sky
    
    ```javascript
    map.addSource('terrain-dem', { type: 'raster-dem', url: 'https://tiles.mapterhorn.com/tilejson.json' });
    map.setTerrain({ source: 'terrain-dem', exaggeration: 1 });
    map.setSky({
      'sky-color': '#199EF3',
      'sky-horizon-blend': 0.5,
      'horizon-color': '#ffffff',
      'horizon-fog-blend': 0.5,
      'fog-color': '#0000ff',
      'fog-ground-blend': 0.5
    });
    ```
    
    - **`terrain` takes only `source` and `exaggeration`** (default `1`).[4] It is a root-level style object,
      set in the style or through `map.setTerrain()`; `map.setTerrain(null)` turns it off.
    - **Pitch is what makes it visible.** At `pitch: 0` an extruded surface is seen straight down and reads as
      flat. Set `pitch` on the map (or `map.easeTo({ pitch: 60 })`) before concluding the terrain is broken —
      and raise `exaggeration` only after the camera is tilted, never as the fix for a flat-looking map.
    - **There is no `sky` layer type in MapLibre.** The layer types are `fill`, `line`, `symbol`, `circle`, `heatmap`, `fill-extrusion`, `raster`, `hillshade`, `color-relief`, and `background`.[1] Sky is a root-level `sky` object, or `map.setSky()`: `sky-color`, `horizon-color`, `fog-color`, `sky-horizon-blend`, `horizon-fog-blend`, `fog-ground-blend`, `atmosphere-blend`.[5] `sky-type`, `sky-atmosphere-sun`, and `sky-atmosphere-sun-intensity` are Mapbox GL JS properties that style validation rejects: `setSky` with one applies nothing, and a style whose `sky` holds one does not load. `fog-color` requires 3D terrain.[5]
    - **Fog is part of `sky`.** MapLibre GL JS has no `setFog` method and no root `fog` object; haze comes from `fog-color`, `horizon-fog-blend`, and `fog-ground-blend` in `sky`.[5] [6]
    - `map.queryTerrainElevation(lngLat)` returns the elevation under a location once terrain is on.[6]
    
    **Cost.** Terrain decodes DEM tiles, builds a mesh, and re-draws every layer draped over it, so it is the
    most expensive thing on this page — noticeably so at high zoom and pitch on low-end devices. Keep the
    terrain stack small: one shared `raster-dem` source, one or two elevation layers, and only the overlays you
    need.
    
    ## Related Skills
    
    - [**maplibre-cartography**](../maplibre-cartography/SKILL.md) — Where a hillshade layer belongs in the layer order, and palettes that survive over relief.
    - [**maplibre-pmtiles-patterns**](../maplibre-pmtiles-patterns/SKILL.md) — Serving DEM and imagery tiles from a single PMTiles file.
    
    ## References
    
    1. **Style Specification: layers** — `hillshade` and `color-relief` paint properties, defaults, `hillshade-method` values, and the complete list of layer types — <https://maplibre.org/maplibre-style-spec/layers/>
    2. **Style Specification: expressions** — `["elevation"]`, valid only in `color-relief-color` — <https://maplibre.org/maplibre-style-spec/expressions/>
    3. **`maplibre-contour`** — `DemSource`, `setupMaplibre`, `contourProtocolUrl` — <https://github.com/onthegomap/maplibre-contour>
    4. **Style Specification: terrain** — <https://maplibre.org/maplibre-style-spec/terrain/>
    5. **Style Specification: sky** — <https://maplibre.org/maplibre-style-spec/sky/>
    6. **GL JS `Map` API** — `setTerrain`, `setSky`, `queryTerrainElevation` — <https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/>
    7. **Examples** — [3D terrain](https://maplibre.org/maplibre-gl-js/docs/examples/3d-terrain/), [sky, fog, terrain](https://maplibre.org/maplibre-gl-js/docs/examples/sky-fog-terrain/), [color relief](https://maplibre.org/maplibre-gl-js/docs/examples/add-a-color-relief-layer/), [contour lines](https://maplibre.org/maplibre-gl-js/docs/examples/add-contour-lines/), [multidirectional hillshade](https://maplibre.org/maplibre-gl-js/docs/examples/add-a-multidirectional-hillshade-layer/)
    
    ---
    
    **This skill is a snapshot.** Where a primary source contradicts it — the References above, MapLibre's current documentation, or what MapLibre does when you run it — that source wins. Follow it, then [report the disagreement](https://github.com/maplibre/maplibre-agent-skills/issues/new?template=ai-failure-report.md), citing the source and your MapLibre version: editing your installed copy helps no one else and is overwritten on the next update.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.