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

3D landmarks

Request Access

Important note 3D Landmarks are in Private Preview and unavailable on a Freemium or Pay As You Grow (PAYG) basis. Click the Request Access button above to contact our Sales team. With a key that lacks the access, the map draws no landmarks, and its error handlers get one INSUFFICIENT_PERMISSIONS that names the access to request. See Handle errors.

Landmarks3D, part of the Landmarks 3D plugin, draws well-known buildings as detailed, textured 3D models. Stadiums, cathedrals and towers stand out as themselves, not as plain boxes. The example below shows landmarks in seven cities, with a control for each knob of their look:

Use cases

How it works

Get started

Install the plugin and create a pitched map, as the overview shows. To have the landmarks stand in a 3D city, show the base map's 3D buildings too. Most standard styles ship the buildings3D group hidden. Leave that step out for landmarks alone, or draw the city with Buildings3D instead.

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

await BaseMapModule.get(map, { groups: { buildings3D: { visible: true } } });
const landmarks = new Landmarks3D(map);

Set the look

The look of the landmarks is a set of knobs, which follow the rules every part of the plugin follows (Set the look with knobs). Set the ones you want, and leave the others to the base map or their defaults:

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

landmarks.updateConfig({ color: '#c8b28a', opacity: 0.9 });               // the rest still follows the base map
setKnob(landmarks, landmarks3DKnobCatalogue, 'verticalGradient', false); // a value held as data
resetKnob(landmarks, landmarks3DKnobCatalogue, 'color');                 // back to the base map's colour
landmarks.resetConfig();                                                 // every knob unset again

Knobs

Knob Values Unset
visible true or false true
color a CSS colour the colour of the base map's 3D buildings
palette CSS colours, or map colours by their knob ID such as colors.accent: each landmark takes one none, or the walls' palette while a Buildings3D shows and color is unset
paletteMode, paletteIntensity, variation as the walls' knobs of the same names pick, 1 and 0, or the walls' ones while a Buildings3D shows
hover.color, click.color a CSS colour: what the hovered and the clicked landmark turn towards the map's colors.accent, otherwise blue, or the buildings' hover.color and click.color while a Buildings3D shows
hover.intensity, click.intensity 0 (no change) to 1 (the full colour) 0.35 and 0.7, or the buildings' ones while a Buildings3D shows
texture mask, detail or color: what each landmark's own texture adds to its outline. mask adds nothing, detail adds its light and shade over color, and color draws its own colours in place of color color on streetSatellite; otherwise mask, or detail while a Buildings3D shows
opacity 0 to 1 the opacity of the base map's 3D buildings
verticalGradient true or false: whether the walls darken towards the ground as the base map's 3D buildings
minZoom, maxZoom 0 to 22: the lowest and highest whole zoom levels the landmarks are drawn at the zoom range of the base map's 3D buildings

Show the landmarks' own colours

Each landmark comes with a texture of its own stone, brick, roofs and windows. By default, the texture only carves the landmark's outline, and the color knob paints it. Over satellite imagery, streetSatellite, the landmarks show their own colours instead, which sit better in a photograph. To draw the landmarks in their own colours on any style, set texture to color:

landmarks.updateConfig({ texture: 'color' });

Terrain

Landmarks stand on 3D terrain without any configuration. The plugin lowers each one onto the lowest ground under its footprint, so no wall floats above a slope. Landmarks follow the terrain as it loads or its exaggeration changes.

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

await TerrainModule.get(map, { elevation: { visible: true }, hillshade: { visible: true } });
const landmarks = new Landmarks3D(map);

Several maps

Create one Landmarks3D per map. Each one loads the tiles of its own map's view:

const landmarks = maps.map((map) => new Landmarks3D(map));

To frame a tall landmark, aim the camera at its mid-height instead of its foot. Set centerClampedToGround: false on the map and give the camera an elevation in metres. MapLibre's flyTo and easeTo leave the elevation where it was, so move with jumpTo:

const map = new TomTomMap({
    mapLibre: {
        container: 'map',
        centerClampedToGround: false,
        center: [2.2945, 48.8584],
        elevation: 165, // halfway up the Eiffel Tower
        zoom: 15.4,
        pitch: 60,
    },
});
new Landmarks3D(map);

map.mapLibreMap.jumpTo({ center: [-122.3493, 47.6205], elevation: 92 }); // on to the Space Needle

Aim at the ground again before the reader zooms in. MapLibre picks how detailed its tiles are from the camera's distance to the point it aims at, not to the streets. Closing in on a point halfway up a tower draws the streets in thousands of tiles, and the map stalls. On pointerdown, wheel and keydown, jump to the same view aimed at the ground under the middle of the screen, as the demo below does. Listen in the capture phase, so the jump comes before the gesture starts: a jump during a gesture cancels it.

The demo below shows four landmarks of one kind, one per map:

Hover, click and colour single landmarks

landmarks.events reports the landmark under the pointer, and setLandmarkColors gives landmarks a colour of their own by the ids those events report:

landmarks.events.on('hover', (landmark) => console.log(landmark.properties.position)); // [longitude, latitude]
landmarks.events.on('click', (landmark) => landmarks.setLandmarkColors({ [landmark.id]: '#1faa59' }));

Landmarks and buildings share these events and colours, with or without a Buildings3D on the map. Hover and click and Colour single buildings and landmarks cover them in full, with a demo.

Handle errors

The landmark tiles report their failures to the map's error handlers, as the map's own tiles do. Each one is a TomTomMapError whose sourceId is the id of the landmarks layer, landmarks.layer.id. To tell the reader their key needs access, read its privatePreviewAccess:

const landmarks = new Landmarks3D(map);
map.addErrorHandler((error) => {
    if (error.sourceId === landmarks.layer.id && error.privatePreviewAccess) {
        const { product, requestAccessURL } = error.privatePreviewAccess;
        showMessage(`${product} needs access on your API key: ${requestAccessURL}`);
    }
});

Configuration

Pass the knobs to start with in the constructor, alongside withCredentials and transcoderPath. The first sends cookies with each tile request, and follows the SDK's proxy configuration unless you set it.

const landmarks = new Landmarks3D(map, { minZoom: 16, opacity: 1 });

To load the texture transcoder from your own host, copy basis_transcoder.js and basis_transcoder.wasm from node_modules/@tomtom-org/maps-sdk-plugin-landmarks-3d/dist there. Then set transcoderPath to the path you serve them at, ending in /:

const landmarks = new Landmarks3D(map, { transcoderPath: 'https://assets.example.com/basis/' });

Landmark tiles exist at zoom 15 only, so the landmarks show from zoom 15 at the earliest. A lower minZoom draws them from there.

API reference

Landmarks3D · landmarks3DKnobCatalogue

Related guides and examples

Related guides

Related examples