Skip to main content
skill CX Codex

maplibre-terrain-rendering — Claude Code skill: setup and use

maplibre-terrain-rendering guides coding agents through elevation rendering in MapLibre GL JS, covering hillshade methods, color-relief layers, contours, and 3D terrain.

MIT 307 installs ★ 164 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add maplibre/maplibre-agent-skills --skill maplibre-terrain-rendering -a claude-code
Open on GitHub

What maplibre-terrain-rendering does

This skill prevents AI tools from generating incompatible Mapbox styling properties when configuring elevation in MapLibre GL JS. It clarifies how a single raster-dem source powers shaded relief, hypsometric tinting, runtime vector contours, and tilted 3D meshes.

Instead of stacking redundant hillshade layers to soften steep contrasts, it applies hillshade-method: "multidirectional" or igor. It also guides the setup of client-side elevation tints via the color-relief layer and the ["elevation"] expression, alongside browser-computed contour lines through maplibre-contour.

The color-relief layer requires at least MapLibre GL JS 5.6, while properties like raster-color or raster-value will silently fail because MapLibre does not support them.

What it helps with

  • fix harsh ridge contrast without stacking multiple hillshade layers
  • render dynamic elevation tints client-side using color-relief
  • generate runtime contour lines with maplibre-contour in a Web Worker
  • troubleshoot flat terrain output when calling map.setTerrain

Example prompts for the agent

  • Configure multidirectional hillshade on our raster-dem layer in MapLibre
  • Build a hypsometric tint layer using color-relief and the elevation expression
  • Set up dynamic runtime contour lines from our DEM source using maplibre-contour

How to install maplibre-terrain-rendering

1Skills CLI (Vercel)

npx skills add maplibre/maplibre-agent-skills --skill maplibre-terrain-rendering -a claude-code

2Manually: put the files in place

~/.claude/skills/maplibre-terrain-rendering/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/maplibre-terrain-rendering/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about maplibre-terrain-rendering

How to install maplibre-terrain-rendering in Claude Code?

Run npx skills add maplibre/maplibre-agent-skills --skill maplibre-terrain-rendering -a claude-code in your terminal.

What does maplibre-terrain-rendering do?

It gives your AI assistant concrete rules and layer structures for drawing terrain and elevation in MapLibre GL JS.

Does MapLibre support raster-color for elevation palettes?

No, MapLibre ignores raster-color; elevation tinting requires the dedicated color-relief layer introduced in GL JS 5.6.

Source text

SKILL.md · MIT
---
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).
- **Silent property failures:** a hillshade, sky, or terrain-coloring property does nothing and raises no error (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 and do nothing here.
  `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.

© maplibre · MIT · maplibre/maplibre-agent-skills

Similar skills

All skills for Frontend and UI →
mapbox-maplibre-migration mapbox mapbox-maplibre-migration is a Claude Code skill that guides projects moving from MapLibre GL JS to Mapbox GL JS. It covers API compatibility, token setup, and map styles. CX Codex +1 1,400installs seamless-isometric-terrain 0xheycat The seamless-isometric-terrain skill helps generate isometric terrain tiles in ComfyUI and assemble maps without visible gaps, edge mismatches, or color drift. CX Codex +1 ★ 51repo stars terrain-hydrology Muhammed Enes Duran terrain-hydrology — a skill for Claude Code, Codex, Cursor, Copilot, Gemini CLI, and OpenCode. Handles terrain, drainage, viewshed, and visibility analysis from elevation data: DEM selection, slope, flow, streams, watersheds. CX Codex +1 ★ 48repo stars threejs-landscape MengTo This skill builds a live Three.js landscape: terrain, grass, stones, sky and a time-of-day cycle. It suits hero backdrops where a subject has to sit somewhere, not float on a gradient. CX Codex +1 1,600installs pixijs-rendering gamedev-skills pixijs-rendering — a skill for Claude Code and Cursor that sets up and debugs 2D browser game rendering using PixiJS v8. It handles asynchronous initialization, asset loading, and scene graphs. CX Codex +1 10,800installs pixijs-custom-rendering pixijs pixijs-custom-rendering is a Claude Code skill for low-level rendering in PixiJS v8, including shaders, filters, batchers, and draw code. It activates for requests about GLSL, WGSL, uniforms, or textures. CX Codex +1 7,000installs

From the same set10

The whole set →
maplibre-pmtiles-patterns maplibre-pmtiles-patterns guides your agent on serving serverless vector and raster PMTiles in MapLibre GL JS. Useful when hosting maps on static storage like S3, Cloudflare R2, or GitHub Pages. CX Codex +1 899installs maplibre-cartography maplibre-cartography — a skill of cartographic rules for MapLibre GL JS: label and icon colors, layer order, contrast. Useful when a style is new or labels vanish over imagery. CX Codex +1 623installs maplibre-mapbox-migration The maplibre-mapbox-migration Claude Code skill guides a move from Mapbox GL JS to MapLibre GL JS. It activates for migration work or when a migrated map is blank or shows a mapbox:// or 401 error. CX Codex +1 532installs maplibre-source-wiring The maplibre-source-wiring skill diagnoses blank MapLibre GL JS maps, mismatched vector layers, and inactive feature state. Use it when a configured source draws nothing. CX Codex +1 408installs maplibre-fonts-glyphs The maplibre-fonts-glyphs Claude Code skill configures fonts and glyphs in MapLibre GL JS and MapLibre Native. It covers label font issues, glyph hosting, and non-Latin scripts. CX Codex +1 335installs maplibre-v6-migration maplibre-v6-migration guides a MapLibre GL JS upgrade from v5 to v6 across seven breaking changes, from the ESM-only build to event types. Useful when a map dies right after the dependency bump. CX Codex +1 286installs maplibre-skill-authoring maplibre-skill-authoring is a Claude Code skill that turns a MapLibre research session into a skill proposal while context is still available. It captures the initial mistake before the correct answer replaces it. CX Codex +1 229installs maplibre-sprites-icons maplibre-sprites-icons — a skill for Claude Code configures sprites and icon images for MapLibre GL JS maps. Runs when choosing between a Marker and a sprite or missing icons. CX Codex +1 136installs

Project sponsors

Companies that keep this analytics open