跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
搜索与研究

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-dem source 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-dem format
  • 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-dem configuration.

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.

EncodingFormulaCommon sources
"terrarium"(R * 256 + G + B / 256) - 32768AWS Terrain Tiles, Mapterhorn, most open sources
"mapbox"(R * 256 * 256 + G * 256 + B) * 0.1 - 10000MapTiler 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

阅读完整来源 ↗