Rendering Real‑Time 3D Terrain in Mapbox GL JS with Terrain‑RGB Tiles

Why 3D Terrain Matters and Where Terrain‑RGB Fits

Map developers often need a realistic elevation surface for flight simulators, game worlds, or urban planning tools. Traditional approaches pull separate DEM (digital elevation model) files and stitch them into a heightmap, which doubles bandwidth and adds a preprocessing step. Mapbox’s Terrain‑RGB tiles solve this by encoding elevation directly into the RGB channels of a standard vector tile. The same tiles can be used for 2D map rendering and, with a custom GLSL shader, for on‑the‑fly 3D displacement.

Feature Overview: What Terrain‑RGB Gives You

• Elevations are stored as 8‑bit per channel RGB values, a compact 24‑bit representation.
• The tiles are served from the same CDN that hosts Mapbox’s vector tiles, so no extra server is required.
• Mapbox GL JS can access the tiles via a raster-dem source type, enabling the terrain property on the map.
• Because the tiles are vector‑style, you can toggle the same layer for 2D or 3D with a single source URL.

Implementation Steps

1. Enable the Terrain‑RGB service

   Go to your Mapbox account, navigate to the Data section, and enable the Terrain‑RGB dataset for your region. Note the mapbox://mapbox.terrain-rgb style URL that will be used in the source definition.

2. Set up the Mapbox GL JS map

   mapboxgl.accessToken = 'YOUR_MAPBOX_TOKEN';
   const map = new mapboxgl.Map({
     container: 'map',
     style: 'mapbox://styles/mapbox/streets-v12',
     center: [-122.4194, 37.7749],
     zoom: 12,
     pitch: 60,
     bearing: -20
   });
   

3. Add a terrain source

   map.addSource('terrain', {
     type: 'raster-dem',
     url: 'mapbox://mapbox.terrain-rgb',
     tileSize: 512,
     maxzoom: 14,
     encoding: 'raster-dem' // optional, defaults to 8-bit RGB
   });
   

4. Apply the terrain to the map

   map.setTerrain({ source: 'terrain', exaggeration: 1.0 });
   

   The exaggeration factor scales the height values; 1.0 shows true elevation, higher values accentuate ridges.

5. Optional: Add a custom shader for finer control

   Mapbox GL JS exposes a customLayer type that allows a GLSL fragment shader to manipulate the elevation data further. Below is a minimal example that demonstrates the RGB‑to‑height conversion formula used by Mapbox internally.

   map.addLayer({
     id: 'terrain-shader',
     type: 'custom',
     renderingMode: '3d',
     onAdd: function (map, gl) {
       this.program = createShaderProgram(gl);
     },
     render: function (gl, matrix) {
       gl.useProgram(this.program);
       // bind uniforms, textures, etc.
       gl.drawArrays(gl.TRIANGLES, 0, 6);
     }
   });
   
   function createShaderProgram(gl) {
     const vertSrc = `#version 300 es
       in vec4 a_position;
       uniform mat4 u_matrix;
       void main() {
         gl_Position = u_matrix * a_position;
       }`;
     const fragSrc = `#version 300 es
       precision highp float;
       uniform sampler2D u_terrain;
       out vec4 outColor;
       const float elevationScale = 0.1; // meters per unit
       void main() {
         vec4 tex = texture(u_terrain, gl_FragCoord.xy / vec2(512.0));
         float height = (tex.r * 256.0 + tex.g + tex.b / 256.0) * elevationScale;
         outColor = vec4(height, height, height, 1.0);
       }`;
     // compile and link shaders (omitted for brevity)
     return program;
   }
   

   In practice, you would use Mapbox’s built‑in terrain property instead of writing a custom shader unless you need extra filtering or stylized displacement.

6. Monitor tile usage

   Because Terrain‑RGB tiles count against your Mapbox quota, inspect the Analytics dashboard. A 429 Too Many Requests response indicates you’ve hit the limit. Use map.on('tileerror', …) to catch these errors in the browser console.

Trade‑Offs and Limitations

• Bandwidth vs. Detail – The 512‑pixel tiles are relatively small, but at high zoom levels (e.g., zoom > 14) they can still consume significant bandwidth if many tiles are requested simultaneously. Implement request throttling or limit maxzoom to reduce traffic.
• Memory Footprint – Each active tile occupies GPU memory for the height texture. On low‑end devices, this can cause frame drops. Consider using a lower tileSize (e.g., 256) or a maxzoom that matches your target audience.
• Elevation Accuracy – The 24‑bit RGB encoding limits vertical resolution to about 0.1 m per unit. At very low zoom levels, the decoded height may appear flat. Adjust exaggeration or use a higher‑resolution tileset if you need finer detail.
• Licensing – The Terrain‑RGB service is part of Mapbox’s paid plans. Free tier usage may be constrained, and commercial projects must ensure they have the appropriate license.
• Shader Complexity – Custom GLSL shaders can introduce bugs if the RGB‑to‑height conversion is mis‑implemented. Stick with Mapbox’s built‑in terrain if you’re not comfortable with WebGL.

Actionable Next Steps

1. Enable Terrain‑RGB in your Mapbox account and note the mapbox://mapbox.terrain-rgb URL.
2. Create a simple Mapbox GL JS map, add the raster-dem source, and call map.setTerrain({ source: 'terrain' });.
3. Adjust exaggeration to match your visual style and test on the target device family.
4. Set up a monitoring routine: add map.on('tileerror', …) and check the Analytics dashboard for request counts.
5. If you need advanced displacement (e.g., custom shading or terrain‑based lighting), experiment with a custom layer and the GLSL example above.
6. Review your Mapbox plan and consider upgrading if your tile usage regularly approaches the quota.

With these steps you can turn a single set of vector tiles into a fully interactive 3D terrain experience, all while keeping bandwidth low and keeping your asset pipeline simple.