Bloom

Bloom is the map effects plugin's emphasis for dark and driving styles. Lit roads, traffic tubes and route lines glow. The playground below has every bloom knob on one panel, including the colour scope:

Turning it on

Bloom is off until bloom.intensity is above 0. bloom.threshold sets how bright a pixel must be to glow, and bloom.radius sets how far the glow spreads:

import { MapEffects } from '@tomtom-org/maps-sdk-plugin-map-effects';

const effects = new MapEffects(map);
effects.updateConfig({ bloom: { intensity: 0.5, threshold: 0.6 } });

The ranges of bloom.radius and bloom.onlyTolerance end where a slider would. setKnob refuses a value below the minimum, and a value above the maximum still applies.

Scoping bloom by colour

bloom.only lists the colours bloom may light. Entries mix freely, and the default [] lights the whole frame.

import { setKnob } from '@tomtom-org/maps-sdk/map';
import { effectKnobCatalogue } from '@tomtom-org/maps-sdk-plugin-map-effects';

effects.updateConfig({ bloom: { intensity: 0.9, only: ['traffic'] } }); // a group of style colours
setKnob(effects, effectKnobCatalogue, 'bloom.only', ['traffic.incidents.colors.major', 'traffic.incidents.colors.closed']); // single knobs

const routeColor = '#1a73e8';                                                 // the color your RoutingModule draws routes in
setKnob(effects, effectKnobCatalogue, 'bloom.only', ['traffic', routeColor]); // plus a CSS colour of your own

• The names come from the SDK's styleColorKnobIds, so you can scope a colour knob that any module gains without changing anything here. effectKnobCatalogue lists them in the knob's options. An entry that is neither a name nor a CSS colour throws RangeError.
• A scope keys on colour, not on layers. The effects see the rendered map as one flat image, so bloom keeps the pixels in a listed colour.
  • It follows the style. Each name is read with getStyleColor, so a recolour or a style switch moves the scope with nothing to keep in sync. A name resolves without any module.
  • Anything else in those colours glows too, since a colour key can't tell it from traffic.
  • Only what the style paints differently can be separated. The TomTom styles give flow and incidents one palette (traffic.flow.colors.stationary is traffic.incidents.colors.major), so traffic.flow also keys those incidents.
  • A colour no literal stands for (a data-driven expression) scopes to nothing. Bloom then lights the whole frame, with one console warning.
• Bloom doesn't compare brightness. An antialiased edge and its lit centre are one colour at two levels, and bloom.threshold judges level.
  • bloom.onlyTolerance covers the blending an edge picks up. Raise it if edges drop out, lower it if a neighbouring severity lights up.
  • Its 0.15 default keeps a moderate jam out of a traffic.incidents.colors.major scope, since the moderate colour sits 0.217 from the major one.
• A scope lets you lower the cut. With the city keyed out by colour, bloom.threshold can sit under the darkest thing worth lighting.
  • monoDark paints a major jam hsl(0, 100%, 28%). Of that colour, 64/255 survives a 0.45 cut and 110/255 survives a 0.25 one.
  • The Traffic flow with bloom example cuts at 0.25, with a grade deepening the city the traffic glows against.

How it renders

A glow needs the original picture and its blur, which a backdrop-filter can't give. So bloom draws in one of two ways:

• Without a scope, bloom is a canvas at a quarter of the pixels. The plugin redraws it every frame and blends it in screen mode.
• With bloom.only, bloom runs as the last stages of the GPU chain. It keys each pixel on the scope's colours, cuts and blurs on the GPU, then lays the glow over the picture in the same screen blend. Note that a scope needs a WebGL2 context, as the depth of field does. Without one, a scoped bloom draws no glow, and the plugin warns once.

Either way, bloom draws from the GPU chain's output, so it glows over the depth of field's defocus. If a pass of your own shifts hues, a scope may need a wider bloom.onlyTolerance to find its colours. Keep bloom.radius moderate on large canvases. What each effect costs compares the two ways.

Related guides and examples

Related guides

• Map effects plugin - Setup, how the effects render, and every knob
• Glare - Streaks out of the lights, scoped by colour as bloom is
• Map styling - The map-wide colour ids bloom.only names, and getStyleColor
• Traffic flow and Traffic incidents - The traffic a scoped bloom lights, and its colours

Related examples

• Bloom playground - Every bloom knob, the colour scope included
• Traffic flow with bloom - Live traffic glowing over a dark map
• Cinematic city orbit - Lit windows on a dark preset with bloom, alongside Buildings3D and Landmarks3D