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

3D buildings

Buildings3D, part of the Landmarks 3D plugin, draws the base map's buildings in 3D with Three.js. Their walls get windows, a sun or a moon casts shadows across the buildings and the streets, and the dark street and mono presets light some windows from inside. It extrudes the buildings of the vector tiles your map already loads and makes no requests of its own. It's in Public Preview and works with any API key.

The playground below draws Manhattan's towers, with controls for their windows, colours, light and shadows, a style switch and a sun that crosses the day:

Get started

Install the plugin and create a pitched map, as the overview shows. Then create the class, with the knobs to start with if you like:

import { Buildings3D } from '@tomtom-org/maps-sdk-plugin-landmarks-3d';

const buildings = new Buildings3D(map, { facade: { pattern: 'office' } });

With 3D landmarks

With a Landmarks3D on the same map, the buildings draw the landmarks in their own scene, so the two stand in one city:

Tune the buildings

The look of the buildings is a set of knobs, which follow the rules every part of the plugin follows (Set the look with knobs). A preset gives each knob you leave unset its value. By default, the preset is auto, which follows the map style. Light styles and streetSatellite get a sun and glass that mirrors the street and the sky, and the dark street and mono styles get a moon and lit windows.

import { setKnob } from '@tomtom-org/maps-sdk/map';
import { buildings3DKnobCatalogue } from '@tomtom-org/maps-sdk-plugin-landmarks-3d/knobs';

buildings.updateConfig({ facade: { pattern: 'glass' } });                 // every building in glass
setKnob(buildings, buildings3DKnobCatalogue, 'light.altitude', 12);      // a low sun with long shadows
buildings.updateConfig({ preset: 'streetDark' });                        // a night city on any map
buildings.resetConfig();                                                 // every knob back to the map style

The knobs belong to Buildings3D and draw its own layer. A few reach past it, into the style's 3D buildings and the landmarks, and the map's light feeds two of them:

Buildings3D: buildings3DKnobCatalogueLandmarks3D: its unset knobsMapLibre maptomtom-3d-buildingsthe buildings and the landmarks, one scene3D - Buildingfiltered outThe map's light,set by view.light every knobvisiblewalls.color · walls.palette*walls.variation · hover · clickopacity · minZoom facade.intensity · reflections.intensityshadows.* on the landmarks toodrawn among the buildings light.direction · light.altitudewhile unset

Knobs

Knob Values Unset
visible true or false true
preset auto or a standard style ID auto
opacity 0 to 1 1
minZoom 13 to 22 15
facade.pattern mixed, residential, office, glass or plain. mixed picks one by the building's height mixed
facade.intensity 0 (plain walls) to 1 the preset's
facade.floorHeightMeters 2.5 to 6: the height of one storey, which spaces the rows of windows 3.4
walls.color, roofs.color a CSS colour the style's 3D building colours
walls.palette CSS colours, or map colours by their knob ID such as colors.artificial: each building takes one none
walls.paletteMode pick (one colour) or blend (a mix of two neighbouring ones) pick
walls.paletteIntensity 0 (the wall colour) to 1 (the palette colour) 1
roofs.palette, roofs.paletteMode, roofs.paletteIntensity as the walls' ones, for the roofs none, pick and 1: the roofs follow the walls
walls.variation 0 (all alike) to 1: how much each building's shade differs from the next 0.12
hover.color, click.color a CSS colour: what the hovered and the clicked building turn towards the map's colors.accent, otherwise blue
hover.intensity, click.intensity 0 (no change) to 1 (the full colour) 0.35 and 0.7
windows.color a CSS colour the preset's
reflections.intensity 0 (matte) to 1: how much the window glass mirrors the street, the facades across it with their windows, and the sky, and catches the sun. The reflection slides across the glass as the camera moves. The street it mirrors takes the same sun and sky light, the sky glows on the sun's side, and panes in shadow lose the sun. Glass curtain walls reflect the most, and ambientLight.color is the sky they mirror 0.7
litWindows.color, litWindows.fraction, litWindows.intensity a CSS colour, then the share and brightness of the windows lit from inside, 0 to 1 the preset's, no lit windows on light styles
light.direction, light.altitude 0 to 359 degrees clockwise from north, then 5 to 90 degrees above the horizon the map's light, otherwise the preset's
light.color, light.intensity a CSS colour, then 0 to 1 the preset's
ambientLight.color, ambientLight.intensity the light from the sky, which lights the walls in shade: a CSS colour, then 0 to 1 the preset's
shadows.visible, shadows.intensity true or false, then 0 to 1 the preset's
roadLabels.occluded, pois.occluded true draws the road names, or the style's POIs, under the buildings, so a building that covers a label hides it. A hidden POI still keeps other labels off its place, and the labels moved under give way to the ones above them where they collide false

Vary the colours

By default, every building takes its wall colour in a shade a little lighter or darker than its neighbours. Give the walls a palette, an array of your own colours, and each building takes one of them instead:

buildings.updateConfig({ walls: { palette: ['#b5654a', '#c47f5e', '#d2a98c'] } });              // brick and stucco
buildings.updateConfig({ walls: { palette: ['#efe4cf', '#cdb07f'], paletteMode: 'blend' } });   // every shade in between
buildings.updateConfig({ walls: { palette: ['colors.artificial', 'colors.land'], paletteIntensity: 0.3 } }); // a hint of the map's colours
buildings.updateConfig({ roofs: { palette: ['#5b6770', '#8c5a44'] } });                         // roofs of their own
buildings.updateConfig({ walls: { variation: 0.4 } });                                         // one colour, a shade per building

Hover and click

buildings.events and landmarks.events are user events, as on a map module. A handler gets the building or the landmark under the pointer as a BuildingHit, with its id and its properties:

buildings.events.on('click', (building) => console.log(building.id, building.properties.height));
landmarks.events.on('hover', (landmark) => console.log(landmark.properties.position)); // [longitude, latitude]

The example below picks buildings and landmarks over Amsterdam and paints the selected one:

Colour single buildings and landmarks

Give buildings and landmarks a colour of their own by the ids their events report:

buildings.setBuildingColors({ 6183703601: '#e4572e', 6183703602: '#29335c' });
landmarks.setLandmarkColors({ [landmark.id]: '#1faa59' });
buildings.getBuildingColors(); // { 6183703601: '#e4572e', 6183703602: '#29335c' }
landmarks.getLandmarkColors(); // { [landmark.id]: '#1faa59' }
buildings.setBuildingColors({}); // every building back to its own colour

With map effects and a map theme

The buildings and the landmarks pair with two other plugins. The map effects plugin makes lit windows glow and softens the city with distance, and the map-theme plugin gives the map colours the walls follow. The playground below circles the Empire State Building in eight looks, each setting the style, the colours, the buildings, the landmarks and the effects together:

API reference

Buildings3D · buildings3DKnobCatalogue

Related guides and examples

Related guides

Related examples