Landmarks 3D plugin
The Landmarks 3D plugin turns a TomTomMap into a 3D city. Well-known buildings stand as detailed models, every other building rises with windows and shadows, and the ground takes on rippling water, fields and asphalt, with trees on its woods and parks. The example below draws all of it around the Eiffel Tower, and a slider moves the sun across the day:
The plugin has three parts. Use any one of them alone, or combine them for the whole city. Each part has its own guide:
| Guide | Class | Draws | Access |
|---|---|---|---|
| 3D landmarks | Landmarks3D |
Textured 3D models of well-known buildings, such as stadiums, cathedrals and towers | Private Preview, on request |
| 3D buildings | Buildings3D |
The base map's buildings in 3D, with windows, lit windows at night and shadows from the sun or the moon | Public Preview, any API key |
| GL surfaces | GLSurfaces |
The style's water, land cover and roads as textures, with 3D trees on woods, parks and meadows | Public Preview, any API key |
Installation
This plugin uses
@tomtom-org/maps-sdk,maplibre-glandthreeas peer dependencies. Install all three, whichever parts you use.
npm install @tomtom-org/maps-sdk maplibre-gl three @tomtom-org/maps-sdk-plugin-landmarks-3d
- Follow the SDK Project Setup to create a
TomTomMap. - Pitch the camera. From straight above, a 3D city looks flat.
- Create the parts you want. Each one starts drawing once the map is ready, so there is nothing to await.
A whole 3D city
To draw the whole city, create the three parts, then place the map's light they share:
import { StylingFoundationsModule } from '@tomtom-org/maps-sdk/map';
import { Buildings3D, GLSurfaces, Landmarks3D } from '@tomtom-org/maps-sdk-plugin-landmarks-3d';
new GLSurfaces(map);
new Buildings3D(map);
new Landmarks3D(map);
await StylingFoundationsModule.get(map, { view: { light: { direction: 240, altitude: 25, alignment: 'map' } } });
- The three parts draw through one Three.js renderer. A landmark the buildings draw among them loads onto the GPU once.
Buildings3Ddraws the landmarks among its buildings, so they share its sun, its sky and its shadows. See With 3D landmarks.- A dark style turns all three to night: lit windows, a darker ground and the moon's light.
- Each part comes back after
setStyle, in the look of the new style. - On 3D terrain, all three stand on the raised ground. A landmark or a building stands on the lowest ground under it, and the textures and trees follow the relief.
Share the map's light
The buildings, the landmarks under them and the surfaces take their sun from the map's light, which the styling module's view.light knobs set. One light for all of them lines up the tree crowns, the dunes and the glint on the water with the buildings' shadows, and the trees stand in those shadows.
- With
alignment: 'map', the light keeps its compass direction as the map rotates. Otherwise, it turns with the map, and the buildings and the surfaces turn with it. - The standard styles place no light of their own. Until you set one, the sun comes from the south-west on light styles and the moon from the south-east on dark ones. Satellite imagery is a daylit photograph, so
streetSatellitetakes a day sun from the south-west. - To light one part on its own, set its
light.directionorlight.altitudeknob. A knob you set wins over the map's light. - The trees take the buildings' shadows only under one sun for both, which the parts share by default. If you give them different suns, with their own light knobs or a
Buildings3Dpreset of another theme, the trees leave the buildings' shadows out.
Set the look with knobs
The look of each part is a set of knobs, listed in its catalogue: landmarks3DKnobCatalogue, buildings3DKnobCatalogue and glSurfacesKnobCatalogue. Each part's guide lists its knobs and what they follow while you leave them unset.
import { setKnob } from '@tomtom-org/maps-sdk/map';
import { Buildings3D } from '@tomtom-org/maps-sdk-plugin-landmarks-3d';
import { buildings3DKnobCatalogue } from '@tomtom-org/maps-sdk-plugin-landmarks-3d/knobs';
const buildings = new Buildings3D(map, { facade: { pattern: 'office' } }); // the knobs to start with
buildings.updateConfig({ walls: { variation: 0.3 } }); // the parts you name
setKnob(buildings, buildings3DKnobCatalogue, 'light.altitude', 12); // one knob, held as data
buildings.resetConfig(); // every knob unset again
Every part follows the same rules as a map module:
- The catalogues come from
@tomtom-org/maps-sdk-plugin-landmarks-3d/knobs, which imports nothing from three.js. Read them at startup, to check values or build a settings panel, andimport()the plugin itself only when the map first draws 3D. applyConfig(config)replaces every knob, andupdateConfig(config)replaces each part of the configuration you name and keeps the others. Note thatupdateConfig({ walls: { variation: 0.3 } })also unsets the otherwallsknobs you set.- For values held as data, from a control, storage or a language model, use
setKnobandsetKnobswith the part's catalogue. They check every value before anything changes, and keep every knob you don't name. getKnobreturns the value in force: the one you set, otherwise what the part follows or its default.getConfig()returns only the knobs you set, andresetKnobunsets one.setVisible(false)hides a part, the same asupdateConfig({ visible: false }), andisVisible()reports it.
API reference
Related guides and examples
Related guides
- How plugins work - What every plugin of the SDK has in common
- Globe and sky - The map's light, which the three parts share
- Terrain - Hillshade and 3D elevation, which the three parts stand on
- three.js custom layers - Your own three.js scene on the map, as this plugin draws its own
- Map effects plugin - Bloom, depth of field and more over the 3D city
Related examples
- 3D city: landmarks, buildings and surfaces - The Eiffel Tower, the buildings round it and the textured Champ de Mars with its trees, under one sun from dawn to dusk
- 3D city on satellite - Sydney Harbour's water, trees, towers, bridge and Opera House over satellite imagery, on default settings
- 3D city at night - Westminster's lit windows and moonlit Thames on a dark style, glowing under bloom and glare
- Cinematic city fly-by - A bird's-eye flight round the landmarks of eight cities and down their avenues, over 3D buildings, and over five landscapes on the terrain