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

GL surfaces

GLSurfaces, part of the Landmarks 3D plugin, textures the water, land cover, built-up ground and roads of a TomTomMap with WebGL materials, and grows 3D trees on its woods, parks and meadows. Water ripples in the wind, mirrors the sky and rolls in onto open shores, forests show sunlit tree crowns, fields break into parcels and roads take on asphalt. Everything is drawn in the style's own colours, for the season you pick. The playground below puts the surface, season, tree, sky and wind knobs on one panel, beside the map's light:

What it textures

Surface Drawn over Looks like
water Seas, lakes, rivers and streams Waves that move with the wind, mirror the sky towards the horizon and glint in the sun, their faces lit from the light's side and their sparkles shimmering. Out at sea they run down the wind; near an open shore they turn to come in towards it and break in foam. Gusts drift across open water between brighter slicks. Canals, ponds and harbours stay calmer, and mirror the sky more
ice Glaciers, and snow and ice seen from afar Snow drifts lit by the sun, patches of bare blue ice and fields of crevasses
forest Woodland Broadleaf crowns and conifers, with leaf clumps up close and shadows between them
grass Grassland, parks, sports grounds, cemeteries and campsites Mown lawns in stripes and long meadow grass dotted with flowers, with gusts of wind running over them
scrub Shrubland and heath Bushes in clumps over dry grass, each lit on the sun's side and casting a shadow
farmland Agricultural land Field parcels in crop tones, with rows and furrows, tracks between them and hedges between farms
sand Sandy land cover Dunes lit by the sun, with ripples across the wind and wet sand along the water
mud Mud flats, and the beds of lakes and rivers that run dry Wet and drier stretches, with creeks and puddles that mirror the sky
gravel Shingle Banks of stones in every shade, rounded and lit one by one up close
rock Other bare land, breakwaters and groynes Weathered ridges
paving Squares, pedestrian streets, platforms, piers and bridges Slabs, smaller slabs or bricks in staggered rows, each stone its own shade, with joints up close
urban Built-up areas and the grounds of towns, industry, shops, schools, hospitals and airports Lots of lighter and darker ground with stains of use, kept faint
roads Eight road fills, from streets to motorways, and the asphalt areas: car parks, service areas, runways and aprons. Paths, tracks and ferries stay flat Smooth asphalt, softly streaked along each road, with the odd patch and crack. Up close, the roads' lanes show polished wheel paths, darker middles and sealed joints

surfaceKinds lists them. The materials vary the style's colour rather than replace it, so a restyle or map colours carry through to the textures.

3D trees

Trees stand on woods, parks, gardens, meadows, scrub, heaths, orchards, cemeteries and playgrounds, each as densely as that kind of ground grows them. Wild woods are the densest, parks and meadows open, and orchards stand in rows. They grow in from zoom 15, sway in the wind and cast shadows away from the sun. Their foliage takes the style's woodland and park colours. On satellite, it takes the colours of the crowns the imagery shows under them.

Get started

Install the plugin as the overview shows. GLSurfaces draws with Three.js, so install three for the surfaces alone too. To texture the map, create the class. It starts drawing once the map is ready:

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

const map = new TomTomMap({ mapLibre: { container: 'map', center: [6.6323, 46.507], zoom: 14.5, pitch: 70 } });
const surfaces = new GLSurfaces(map);

Tune the surfaces

The look of the surfaces is a set of knobs, listed in glSurfacesKnobCatalogue. They follow the rules every part of the plugin follows (Set the look with knobs):

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

surfaces.updateConfig({ wind: { direction: 270, speedFactor: 2 } });         // a brisk westerly
setKnob(surfaces, glSurfacesKnobCatalogue, 'surfaces.roads.intensity', 0);  // flat roads, as the style draws them
surfaces.updateConfig({ light: { direction: 260, altitude: 12 } });          // a low evening sun
surfaces.resetConfig();                                                       // every knob back to its default

Colour them for a season

Each surface and the trees are coloured for a season, from the style's own colours: spring, summer, autumn, winter or snow, as surfaceSeasons lists them. The season knob sets it for everything, and a part's own, such as surfaces.farmland.season, overrides it for that part. Each shade within a surface, such as the cereal fields or the foam, has a colour knob of its own:

surfaces.updateConfig({ season: 'winter' });                                                 // bare fields, pale grass
setKnob(surfaces, glSurfacesKnobCatalogue, 'trees.season', 'autumn');                       // the trees alone turn
setKnob(surfaces, glSurfacesKnobCatalogue, 'surfaces.farmland.colors.rapeseed', '#f2d43a');  // brighter rapeseed

Share the map's light

The surfaces take their sun from the map's light, as every part of the plugin does (Share the map's light). With Buildings3D beside them, the tree crowns, the dunes and the glint on the water line up with the buildings' shadows. To light them both with a low sun from the west, set the map's light:

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

const buildings = new Buildings3D(map);
await StylingFoundationsModule.get(map, { view: { light: { direction: 260, altitude: 20, alignment: 'map' } } });

The knobs belong to GLSurfaces. It adds its own layers to the loaded style and reads the map's sky and light, which it never writes:

GLSurfaces: glSurfacesKnobCatalogueMapLibre mapLand cover, water and road layersdrawn as the style draws themgl-surfaces-* layersright after each run of themThe style's skyThe map's light,set by view.light adds, and shows or hides with visible textures their pixelssky.color, sky.horizonColor while unsetlight.direction, light.altitude while unset

Place the trees

The textures always draw right after the layers they texture. The trees go under the style's lowest label by default. Set beforeLayerConfig to put them elsewhere, as the map modules take beforeLayerConfig:

const surfaces = new GLSurfaces(map, { beforeLayerConfig: 'lowest3D' }); // under the 3D buildings
surfaces.updateConfig({ beforeLayerConfig: 'top' });                     // over everything

Knobs

Knob Values Unset
visible true or false true
season spring, summer, autumn, winter or snow, the season every part is coloured for summer
surfaces.water.season, surfaces.ice.season, surfaces.forest.season, surfaces.grass.season, surfaces.scrub.season, surfaces.farmland.season, surfaces.sand.season, surfaces.mud.season, surfaces.gravel.season, surfaces.rock.season, surfaces.paving.season, surfaces.urban.season, surfaces.roads.season, trees.season a season, for that part alone season
surfaces.water.intensity, surfaces.ice.intensity, surfaces.forest.intensity, surfaces.grass.intensity, surfaces.scrub.intensity, surfaces.farmland.intensity, surfaces.sand.intensity, surfaces.mud.intensity, surfaces.gravel.intensity, surfaces.rock.intensity, surfaces.paving.intensity, surfaces.urban.intensity, surfaces.roads.intensity 0 (the style's flat colour) to 1 1 for water, 0.9 for forest and farmland, 0.7 for paving and roads, 0.5 for urban and 0.8 for the rest
surfaces.water.reflection.intensity 0 to 1: how much the water mirrors the sky, more towards the horizon as on real water 1
surfaces.water.glint.intensity 0 to 1: how brightly the waves catch the sun or the moon 1
surfaces.water.glint.color a CSS colour, the colour of the glint sunlight on light styles and streetSatellite, a dimmer moonlight on dark ones
surfaces.water.waves.heightFactor 0 to 3: how steep the wind waves on open water stand, 0 leaving a mirror 1
surfaces.water.enclosed.waves.heightFactor 0 to 1: how steep the ripples on canals, ponds and harbours stand, times the open water's 0.3
surfaces.water.shore.intensity 0 to 1: how strongly an open shore shows its shallows, its waves rolling in and its breakers 1
surfaces.water.shore.reachMeters 0 to 400: how far out from an open shore the waves turn to roll in, in metres 160
surfaces.forest.crowns.sizeFactor 0.5 to 2: how wide the forest's crowns stand, times their usual 8 m or so 1
surfaces.forest.conifer.fraction 0 to 1: the share of the forest's crowns that are conifers 0.38
surfaces.grass.mown.fraction 0 to 1: the share of lawns that are mown in stripes, rather than left long with flowers 0.5
surfaces.grass.stripes.intensity 0 to 1: how strongly the mown stripes show 0.5
surfaces.grass.flowers.fraction 0 to 0.2: the share of the long grass's half-metre squares holding a flower 0.02
surfaces.farmland.parcels.sizeFactor 0.5 to 3: how large the field parcels are, times their usual 35 to 125 m across 1
surfaces.farmland.rows.intensity, surfaces.farmland.hedges.intensity 0 to 1: how strongly the rows and furrows, then the hedges, show 0.5, 0.85
surfaces.sand.dunes.intensity, surfaces.sand.ripples.intensity 0 to 1: how strongly the dunes, then the wind's ripples, show 0.5
surfaces.sand.wet.widthMeters 0 to 12: how far up from the water the sand is wet, in metres 4
surfaces.ice.crevasses.intensity 0 to 1: how strongly the crevasses and the bare blue ice show 0.5
surfaces.scrub.bushes.intensity 0 to 1: how strongly the bushes and their shadows show 0.7
surfaces.mud.puddles.intensity, surfaces.gravel.stones.intensity 0 to 1: how strongly the mud's creeks and puddles, then the shingle's stones, show 0.5
surfaces.rock.ridges.intensity, surfaces.paving.joints.intensity, surfaces.urban.wear.intensity, surfaces.roads.wear.intensity 0 to 1: how strongly the rock's ridges, the paving's joints, the built-up ground's lots and stains, then the roads' stains, patches and cracks, show 0.5
surfaces.water.colors.shallow, surfaces.water.colors.foam, surfaces.forest.colors.broadleaf, surfaces.forest.colors.conifer, surfaces.grass.colors.lush, surfaces.grass.colors.dry, surfaces.grass.colors.flowers, surfaces.farmland.colors.young, surfaces.farmland.colors.cereal, surfaces.farmland.colors.soil, surfaces.farmland.colors.pasture, surfaces.farmland.colors.rapeseed, surfaces.farmland.colors.stubble, surfaces.farmland.colors.hedges, surfaces.sand.colors.wet, surfaces.ice.colors.crevasses, surfaces.scrub.colors.bushes, surfaces.mud.colors.wet, surfaces.paving.colors.joints, trees.colors.broadleaf, trees.colors.conifer a CSS colour for that shade of the part, whatever its season the style's colour, shaded for the season
trees.visible true or false: the 3D trees true
trees.densityFactor 0 to 3: how many trees stand on each kind of ground, times its own density 1
trees.sizeFactor 0.5 to 2: how tall the trees and bushes stand, times their usual height 1
trees.species.broadleaf.shareFactor, trees.species.conifer.shareFactor, trees.species.columnar.shareFactor, trees.species.umbrella.shareFactor, trees.species.bush.shareFactor 0 to 3: how often each kind grows, times the share its ground and latitude give it. At 0 it grows nowhere, and the other kinds take its place 1
trees.tracks.intensity 0 to 1: how strongly the roads, paths, railways and streams through a wood show over the crowns in front of them 0.6
trees.minZoom 13 to 19: the zoom the trees grow in from, reaching their full height three quarters of a zoom later 15
trees.shadows.intensity 0 to 1: how dark the trees' shadows on the ground are 0.55
light.direction, light.altitude 0 to 359 degrees clockwise from north, then 5 to 90 degrees above the horizon. The light shades the tree crowns, the trees and the dunes, casts the trees' shadows, and sets where the water glints the map's light, otherwise 215, 30 on light styles, 135, 35 on dark ones and 215, 35 on streetSatellite. A map light below 5° is drawn at 5°
sky.color, sky.horizonColor a CSS colour, the sky the water mirrors overhead and at the horizon the map's sky, otherwise a day or a night sky by the style's theme, and a day sky on streetSatellite
wind.direction 0 to 359 degrees clockwise from north, where the wind blows from. The waves and the sand ripples lie across it 225
wind.speedFactor 0 to 4: how fast the waves, the grass and the trees move, 0 holding them still 1

How it renders

For each run of style layers it textures, the plugin adds three things right after the run:

The materials draw on a grid over each tile, projected as the map projects its tiles:

The trees are placed on the GPU from the keyed ground, then drawn as instanced 3D shapes before the labels.

Limits

API reference

GLSurfaces · glSurfacesKnobCatalogue · surfaceKinds · surfaceSeasons

Related guides and examples

Related guides

Related examples