maplibre-terrain-patterns
Terrain and hillshade in MapLibre GL JS — raster-dem sources, Terrarium vs. Mapbox RGB encoding, hillshade layer configuration (single and multi-pass), 3D terrain, dynamic contour lines, and self-hosting DEM tiles. Use when adding elevation context, hillshade, or 3D terrain to a map.
maplibre · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add maplibre/maplibre-agent-skills --skill maplibre-terrain-patterns技能说明
name: maplibre-terrain-patterns description: Terrain and hillshade in MapLibre GL JS — raster-dem sources, Terrarium vs. Mapbox RGB encoding, hillshade layer configuration (single and multi-pass), 3D terrain, dynamic contour lines, and self-hosting DEM tiles. Use when adding elevation context, hillshade, or 3D terrain to a map. status: provisional
MapLibre Terrain Patterns
MapLibre GL JS can render terrain in several ways: hillshade (a 2D lighting effect from elevation data), 3D terrain (extruded mesh that uses elevation values and camera pitch), color-relief (direct coloring based on elevation values), and dynamic contour lines (vector contours generated at runtime).[1], [7] These methods are often combined in the same map to create rich terrain visualizations.
All of these methods use a raster-dem source, colloquially referred to as “terrain tiles”, which encodes elevation values into PNG/WebP pixel values.[1], [3]
There are additional earth observation analysis layers traditionally derived from a DEM, like slope, aspect, and curvature.[11], [14] When these are needed, they are typically precomputed in GIS workflows and served as raster layers, rather than computed client-side in MapLibre.
When to Use This Skill
- Adding hillshade, color-relief, contours, or 3D terrain to a MapLibre map
- Choosing a
raster-demsource and understanding encoding formats - Migrating from Mapbox terrain tiles to an open alternative
- Adding dynamic contour lines from terrain data
- Self-hosting terrain tiles in
raster-demformat - Troubleshooting terrain that looks flat, inverted, or visually wrong
Differences Between DEM, raster-dem, and Hillshade
Digital Elevation Model (DEM), raster-dem, and hillshade are distinct concepts that are often confused.
A DEM is a raster where each cell stores elevation as a numeric value (for example, GeoTIFF in meters).[15], [17]
MapLibre does not read those GeoTIFFs directly. Elevation is first encoded as RGB tiles (Terrain‑RGB or Terrarium), then exposed to MapLibre as a raster-dem source.[5], [6] A raster-dem source always represents elevation per pixel, decoded using one of the supported encodings ("mapbox" or "terrarium").[1], [3]
When creating a hillshade (or color‑relief, contours, or 3D terrain) in MapLibre, the key prerequisite is to choose and configure an appropriate raster-dem source; generating the DEM tiles yourself is computationally intensive, difficult, and usually unnecessary because high‑quality terrain services are freely or commercially available.[4], [8]
When to use precomputed rasters (instead of raster-dem)
In many cases it is simpler to use terrain visualizations that have already been computed in external workflows and exported as tiles. In these cases, configure your tiles as source type raster rather than raster-dem.
Services like OpenTopography or Blender and standard GIS workflows (GDAL, QGIS, ArcGIS) can generate hillshade and color-relief rasters with full artistic control over lighting, texture, and color ramps.[14], [21] Slope rasters and blended “color shaded relief” products must be created directly from DEMs in these tools.[11], [20]
The advantage is that you get rich terrain visualization with minimal layer and source configuration, and performance is better because the client only draws pre-rendered tiles.[14], [22]
The limitation is that these rasters do not contain encoded elevation values (Terrain-RGB/Terrarium), so they cannot power client-side hillshade/color-relief, 3D terrain, or runtime contours in MapLibre.[3], [23]
Precomputed rasters are a good fit when you:
- Only need terrain as a static background (terrain basemap, shaded relief backdrop).
- Want consistent cartography across platforms and don’t need MapLibre to recompute hillshade or color-relief client-side.
- Prefer to avoid the complexity of DEM encoding and
raster-demconfiguration.
When you need MapLibre features that depend on elevation (3D terrain via setTerrain(), client-side hillshade or color-relief, dynamic contours), point those layers at a raster-dem source backed by Terrain‑RGB or Terrarium tiles—for example AWS Terrain Tiles, Mapterhorn, Stadia Terrarium, or MapTiler Terrain RGB.[1], [4]
The raster-dem Source and Encoding
A raster-dem source provides elevation data encoded into PNG/WebP pixel values. MapLibre reads pixel colors and converts them to meter elevations using a formula specific to the encoding format.[1], [3]
This is the primary AI failure zone for terrain setup. MapLibre's default encoding is "mapbox" (Mapbox Terrain‑RGB formula), but many major open and free DEM sources (for example, AWS Terrain Tiles and Mapterhorn) use the Terrarium format.[5], [6] Using the wrong encoding produces silently incorrect elevations — terrain may appear flat, inverted, or wildly exaggerated with no error in the console.
| Encoding | Formula | Common sources |
|---|---|---|
"terrarium" | (R * 256 + G + B / 256) - 32768 | AWS Terrain Tiles, Mapterhorn, most open sources |
"mapbox" | (R * 256 * 256 + G * 256 + B) * 0.1 - 10000 | MapTiler terrain-rgb, Mapbox Terrain |
Terrarium and Mapbox formulas are defined by the Tilezen/Mapzen terrain pipeline and the Mapbox Terrain‑RGB specification.[5], [6]
Always verify the encoding of your DEM source before configuring the style. The encoding is a property of the data, not a preference.
{
"terrain": {
"type": "raster-dem",
"url": "pmtiles://terrain.pmtiles",
"tileSize": 512,
"encoding": "terrarium"
}
}
Open terrain tile sources
| Source | Encoding | Key required | Notes
阅读完整来源 ↗