This is the documentation of version 1.0.0-rc.7. Go to the latest version, 1.0.0.

Globe and sky

The Styling Foundations module's view knobs hold the projection, the sky and the light on the 3D buildings, the map-level MapLibre state that a style switch would otherwise reset. So a globe stays a globe across setStyle. Its buildings3D knob rounds the corners of those buildings. Like any other knobs, they work with setKnob, getKnob, resetKnob and getConfig(), the view knobs on every style.

Projection and sky

import { setKnob, StylingFoundationsModule, stylingFoundationsKnobCatalogue } from '@tomtom-org/maps-sdk/map';

const styling = await StylingFoundationsModule.get(map);
setKnob(styling, stylingFoundationsKnobCatalogue, 'view.projection', 'globe');
setKnob(styling, stylingFoundationsKnobCatalogue, 'view.sky.visible', true); // without it, a globe has no atmosphere

Sky colours

view.sky.color and view.sky.horizonColor colour the sky. If you don't set them, they take:

Note that the sky knobs write MapLibre's whole sky. A sky property you set with map.mapLibreMap.setSky, such as atmosphere-blend or a fog blend, goes back to the style's own value, otherwise the SDK's default, whenever a sky knob applies. That happens when you set or reset one, and after a style switch.

The colour behind the map

view.space.color is the colour behind the map. It shows around the planet on a globe, where the map canvas is transparent.

setKnob(styling, stylingFoundationsKnobCatalogue, 'view.space.color', '#05070d');

The light on 3D buildings

The view.light knobs set the map's light, which shades the sides of the 3D buildings. The standard styles ship their 3D buildings hidden, except the driving ones, so show them first through the Base map module's buildings3D group.

The plugins that draw their own lit surfaces follow the same light. The Landmarks 3D plugin's Buildings3D hides the style's 3D buildings and lights its own from it. The same plugin's GLSurfaces lights its tree crowns, dunes and water glint from it. A plugin's own light direction and altitude each follow it while you leave them unset.

To light the buildings with a warm sun from the west, set the light's parts:

import { BaseMapModule, StylingFoundationsModule } from '@tomtom-org/maps-sdk/map';

await BaseMapModule.get(map, { groups: { buildings3D: { visible: true } } });
const styling = await StylingFoundationsModule.get(map, {
    view: { light: { direction: 270, altitude: 35, alignment: 'map', color: '#ffd9a8', intensity: 0.7 } },
});

If you don't set a part, it takes the style's own light, otherwise MapLibre's default: white, at 0.5, measured from the top of the screen. Direction and altitude take 210° and 60° only once you set one of them. Until then, no position is placed.

Note that the light knobs write MapLibre's whole light. A light property you set with map.mapLibreMap.setLight goes back to the style's own value, otherwise MapLibre's default, whenever a light knob applies.

Once you've set a light knob, a clean style switch, setStyle(…, { resetState: true }), draws the new style's light, rather than keeping the one the knobs had set.

To light a layer of your own from the same direction, read the light with getMapLight. It gives the direction as a compass bearing from north, whatever the map's bearing, and the altitude above the horizon:

import { getMapLight } from '@tomtom-org/maps-sdk/map';

const light = getMapLight(map); // { direction: 270, altitude: 35 }

It returns undefined while the map has no light placed. That's the case on the standard styles until you set view.light.direction or view.light.altitude. The colour, intensity and alignment knobs alone place no light. A style light whose position is an expression, such as one that moves with the zoom, also returns undefined, since no one direction stands for it. A light aligned with the viewport turns with the map, so read it again after the camera moves.

Rounded building corners

The map softens the corners of the 3D buildings, rounding each one over the last metre of its walls. buildings3D.roundedCornerDistanceMeters sets how far along the walls the rounding reaches. Set 0 for sharp corners, or a few metres for rounder buildings. As for the light, show the buildings3D group first:

setKnob(styling, stylingFoundationsKnobCatalogue, 'buildings3D.roundedCornerDistanceMeters', 3);

A style that sets its own fill-extrusion-rounded-corner-distance keeps it, and resetKnob comes back to it. The rounding reaches only the style's 3D buildings, so it changes nothing while Buildings3D shows.

What to expect

The demo above zooms a globe into 3D terrain. The 3D terrain playground keeps a tilted camera, its sky and its relief across a style switch. The map effects plugin's depth of field keeps one distance of a tilted view sharp and blurs the rest.

Related guides and examples

Related guides

Related examples