TomTom LogoDocs
Products
Resources
Pricing
Sign in
Maps SDK for JavaScript
Introduction
Guides
Examples
API Reference

Globe and sky

VERSION 1.0.0-rc.3PUBLIC PREVIEW

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. Like any other knobs, they work with setKnob, getKnob, resetKnob and getConfig(), 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
  • The globe preset sets both in one call.
  • 3D terrain is not a knob. It needs the elevation style part loaded first, which TerrainModule does for you.

Sky colours

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

  • The style’s own sky, if the style declares one that draws something. A sky with transparent sky and horizon colours and no atmosphere draws nothing, so it gives way to the theme’s.
  • Otherwise, the style’s light or dark theme: daylit blue with a white horizon on a light style, night blue with a dim horizon on a dark one.

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.

  • If your page already gives the map container a background, that colour is the knob’s default, and a reset returns to it.
  • Otherwise, it follows the style theme: white on a light style, the night sky’s blue on a dark one. The SDK re-applies it after a setStyle, so it follows a light-to-dark switch.
setKnob(styling, stylingFoundationsKnobCatalogue, 'view.space.color', '#05070d');

The light on 3D buildings

The view.light knobs set the light that shades the sides of the 3D buildings. Nothing else on the map takes it. The standard styles ship their 3D buildings hidden, except the driving ones, so show them first through the Base map module’s buildings3D group.

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 } },
});
  • view.light.direction - The direction the light comes from, in degrees clockwise from the top of the screen.
  • view.light.alignment - What the direction is measured from. With map, it’s measured from north, so the light stays on the same sides of the buildings as the map rotates.
  • view.light.altitude - The height of the light above the horizon, in degrees.
  • view.light.color - The colour of the light.
  • view.light.intensity - The strength of the light, from 0 to 1. A higher value sets the lit sides further apart from the shaded ones.

If you don’t set a part, it takes the style’s own light, otherwise MapLibre’s default: from 210° at an altitude of 60°, measured from the top of the screen, white, at 0.5.

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.

What to expect

  • The globe flattens to Mercator between zoom 11 and 12, by design.
  • Fog over a tilted view starts at pitch 60, which is also MapLibre’s default maxPitch. To see it, raise maxPitch on the map.

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.

  • Map styling — the knobs, their catalogue, presets and settings
  • Terrain — hillshade and the 3D surface a pitched globe shows