TomTom Maps SDK for JavaScript
This is the documentation of version 0.59.0. Go to the latest version, 1.0.0-rc.5.

Terrain module

The Terrain Module draws the relief of the map from the elevation data of the map style, in two ways that combine freely:

What this module owns: whether the hillshade is shown, and whether and how high the surface is raised. How the shading looks is a Styling module knob (hillshade.*) — see Appearance below. See Who owns what.

Initialization

import { TomTomMap, TerrainModule } from '@tomtom-org/maps-sdk/map';

const map = new TomTomMap({ mapLibre: { container: 'map' } });
const terrain = await TerrainModule.get(map, { hillshade: true, elevation: true });

get() adds the hillshade style part, which carries the elevation data, when the style does not include it yet. The SDK keeps one terrain module per map, so a second get() returns the same instance.

TerrainModule.get(map) on its own changes nothing on screen. The style parts the SDK adds — traffic flow, traffic incidents and the hillshade — are hidden until you show them, and the surface stays as the style draws it. On a TomTom style that is flat, which is also where resetConfig() returns it; a terrain your own style or MapLibre code raised stays until you set elevation.

Hillshade

Show the shading at initialization, or toggle it later:

const terrain = await TerrainModule.get(map, { hillshade: true });

terrain.setHillshadeVisible(false);
terrain.isHillshadeVisible(); // false

Appearance

The shading's method, light direction, strength, zoom range and colours are knobs of the Styling module: hillshade.method, hillshade.lightDirection, hillshade.exaggeration, hillshade.maxZoom, hillshade.shadowColor, hillshade.highlightColor, hillshade.accentColor. They shape the shading once this module shows it.

The standard styles ramp the shading's exaggeration to zero by zoom 13 and stop drawing it there, so on a city-zoom map the shading shows nothing until both are set. The light comes from 335° (north-west) by cartographic convention: relief lit from the south reads inside-out to most people.

const styling = await StylingModule.get(map);
styling.set('hillshade.method', 'multidirectional');
// Keep the shading at every zoom:
styling.set('hillshade.exaggeration', 0.5);
styling.set('hillshade.maxZoom', 22);

hillshade.exaggeration is how strongly the slopes are shaded and raises nothing; to exaggerate the height of the 3D surface, use elevationExaggeration below.

3D elevation

Raise the surface, and scale the relief with elevationExaggeration (1 is true elevation). It scales height only; the shading's strength is the hillshade.exaggeration knob:

const map = new TomTomMap({
    mapLibre: { container: 'map', center: [7.66, 45.98], zoom: 12.5, pitch: 70, maxPitch: 85 },
});
const terrain = await TerrainModule.get(map, { elevation: true, elevationExaggeration: 1.5, hillshade: true });

terrain.setElevationExaggeration(2);
terrain.setElevationEnabled(false); // flat again, still shaded
terrain.isElevationEnabled(); // false

The 3D buildings of the base map (BaseMapModule layer group buildings3D) and the Landmarks 3D plugin stand on the raised surface.

Style changes

Both parts are map configuration, not style content: the module re-applies them on top of every style that setStyle loads, and a clean switch (resetState: true) turns them off. The sky above a tilted horizon is a styling knob, view.sky.

Events

The hillshade is a raster layer with no features to click or hover, so the module has lifecycle events only:

terrain.events.on('config-change', (config) => {
    console.log('Terrain config changed:', config);
});

API reference

For complete documentation of all Terrain Module properties, methods, and types, see the TerrainModule API Reference.

Related guides and examples

Related examples

Related map modules