Landmarks 3D plugin

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 the console warns, per tile, that the key needs it.

Use cases

• City-scale 3D visualization - Recognizable buildings (stadiums, cathedrals, towers) as detailed meshes instead of plain extrusions.
• Blend with the base map - Landmarks take the basemap building colour, or the look of streetDark or streetLight.

How it works

• A MapLibre custom layer fetches the landmark tiles covering the viewport and renders them with Three.js, lit to match the map style.
• The layer sits below the POI layer, so POI labels and icons draw over the meshes and roads stay below.
• The plugin shows the standard style's 3D building layer, hidden by default, so landmarks sit in a full 3D city. It filters out basemap buildings that overlap a landmark, which carry has_landmark, so they don't clip through the meshes.
• After setStyle, the plugin restores the layer, its visibility, the filter and the display mode.
• The plugin builds the tile URL from the global TomTomConfig (apiKey, commonBaseURL). Behind a credentialed proxy, tile requests send cookies like every other SDK request. withCredentials overrides that.
• Three.js decodes KTX2 textures with the Basis Universal transcoder. It ships with the plugin in a chunk loaded with the first landmark tile, so no request goes to a CDN.
  • A strict Content Security Policy needs data: in connect-src and blob: in worker-src.
  • Landmarks3D always uses the bundled copy. To serve your own, build the layer yourself with new ModelsLayer(layerSpecification, sourceSpecification) and set transcoderPath on the ModelsSourceSpecification.

Installation

This plugin uses @tomtom-org/maps-sdk, maplibre-gl and three as peer dependencies. Install all three.

npm install @tomtom-org/maps-sdk maplibre-gl three @tomtom-org/maps-sdk-plugin-landmarks-3d

1. Follow the SDK Project Setup to create a TomTomMap. Pitch the camera. From above, the meshes look flat.
2. Create the plugin. Rendering starts once the map is ready, so there is nothing to await.

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

const landmarks = new Landmarks3D(map);

Usage examples

Change the display mode

// 'inherited' (default) | 'dark' | 'light'
await landmarks.setDisplayMode('dark');
landmarks.getDisplayMode(); // 'dark'

• inherited - Mirrors the colour, opacity and vertical gradient of the basemap 3D building layer, so landmarks blend in. Without that layer, or when its colour doesn't resolve to one value, it falls back to the streetLight look.
• dark and light - Use the 3D building look of the streetDark and streetLight styles.

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);

Toggle visibility

await landmarks.setVisible(false);
landmarks.isVisible(); // false

Configuration

const landmarks = new Landmarks3D(map, {
  displayMode: 'inherited',
  visible: true,
  minZoom: 10,
});

API reference

For complete documentation see the Landmarks3D API Reference.

Related guides and examples

• Landmarks 3D plugin - Landmarks over a pitched city, with a display mode switcher
• 3D terrain map - Landmarks standing on the relief
• Terrain - Hillshade and 3D elevation