TomTom Maps SDK for JavaScript
This is the documentation of version 0.58.1. Go to the latest version, 1.0.0-rc.5.
TomTom Maps for JavaScript
    Preparing search index...

    Class MapEffects

    Practical post-processing for a TomTomMap: effects computed from the rendered map's own pixels, not from its style — so they work on every style, custom ones included, survive every style release, and cannot be reproduced by editing the style at all.

    Every effect is named by the problem it solves, and off by default:

    • bloom — emphasis on dark and driving styles: lit roads, traffic tubes and route lines glow;
    • grade (brightness, contrast, saturation) and tint — muting the base map so a data overlay reads first;
    • fog — depth: the rim is blurred and washed towards the colour of the air, which follows the map's light/dark theme;
    • edge blur — focus: the rim is blurred and keeps its colour, so it reads as a lens rather than as distance;
    • depth of field — depth on a tilted map: one band of distance stays sharp and the rest defocuses, worked out from the camera's pitch and field of view, so a flat map ends it;
    • vignette — focus too, by darkening or lightening the edges.

    Effects render live as layers over the map canvas (a WebGL2 chain, which also runs your own passes from addPass, under backdrop-filter overlays; bloom is a small canvas blended in screen mode) and are composited the same way into capture, so what is captured is what was on screen.

    Bloom, the depth of field, your passes and capture read the map canvas, which needs mapLibre: { canvasContextAttributes: { preserveDrawingBuffer: true } } when creating the map; the plugin warns once when it is missing.

    effectKnobCatalogue lists every knob as static data, the way stylingKnobCatalogue lists the SDK's styling knobs.

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

    const effects = new MapEffects(map);
    // The data-viz muting half: a dim, desaturated base under your own layers.
    effects.set({ 'grade.saturation': 0.4, 'grade.brightness': 0.85, 'tint.opacity': 0.15 });
    // Night-driving emphasis on a dark style:
    effects.set({ 'bloom.intensity': 0.5, 'bloom.threshold': 0.6 });

    const poster = await effects.capture({ pixelRatio: 3 });
    Index
    constructor
    addPass applyConfig capture get getConfig remove removePass reset set

    • Attaches the effects to a map. Nothing is visible until set turns an effect on.

      Parameters

      • map: TomTomMap

        The map to render effects over.

      • Optionalsettings: MapEffectsSettings

        Effect knob values to apply right away.

      Returns MapEffects

    • Runs a GPU pass of your own in the effects chain, ahead of every overlay effect, and in capture as on screen. Passes run in the order they were added, within their placement.

      Parameters

      Returns void

      A pass redraws with the map. One whose uniforms change on their own — a time-driven animation — asks for frames with map.mapLibreMap.triggerRepaint(). A pass that shifts hues runs before bloom's colour key too, so a bloom.only scope may need a wider bloom.onlyTolerance.

      Error when the pass has no id or its shader does not compile, with the compiler's log; RangeError for an unknown placement. A shader is checked only while there is a WebGL2 context: without one no pass runs and the plugin warns once, and after a lost one it is checked on restore.

      effects.addPass({
          id: 'posterise',
          fragment: `uniform float uLevels;
              void main() {
                  vec4 colour = texture(uSource, vUv);
                  fragColor = vec4(floor(colour.rgb * uLevels) / uLevels, colour.a);
              }`,
          uniforms: { uLevels: 5 },
      });

    • Replaces every knob with the given settings (an empty object turns everything off).

      Parameters

      Returns void

    • Renders the current view — map and effects — into a canvas, optionally at a higher pixel ratio for print. The map is re-rendered at that ratio (never resampled), read back once every tile is drawn, and restored to follow the device afterwards.

      Parameters

      Returns Promise<HTMLCanvasElement>

      Needs preserveDrawingBuffer: true on the map's canvas context; without it the map half of the capture is blank. Viewers cannot download from a sandboxed page, so hand the canvas to your own upload or toBlob flow.

    • The current value of a knob: the override, or the catalogue default.

      Type Parameters

      • ID extends
            | "bloom.intensity"
            | "bloom.radius"
            | "bloom.threshold"
            | "bloom.only"
            | "bloom.onlyTolerance"
            | "grade.brightness"
            | "grade.contrast"
            | "grade.saturation"
            | "fog.intensity"
            | "fog.reach"
            | "edgeBlur.intensity"
            | "edgeBlur.reach"
            | "depthOfField.intensity"
            | "depthOfField.focus"
            | "depthOfField.band"
            | "depthOfField.bokeh"
            | "tint.color"
            | "tint.opacity"
            | "vignette.intensity"
            | "vignette.reach"

      Parameters

      Returns EffectKnobValueOf<ID>

    • Detaches the effects from the map, removes their elements and releases the WebGL context the chain holds — which a page with several maps on it needs, since a browser caps how many it may keep alive.

      Returns void

    • Takes a pass added with addPass out of the chain. An id with no pass is ignored.

      Parameters

      • id: string

      Returns void

    • Turns a knob (or every knob) back to its default — for most effects, off.

      Parameters

      • Optionalid:
            | "bloom.intensity"
            | "bloom.radius"
            | "bloom.threshold"
            | "bloom.only"
            | "bloom.onlyTolerance"
            | "grade.brightness"
            | "grade.contrast"
            | "grade.saturation"
            | "fog.intensity"
            | "fog.reach"
            | "edgeBlur.intensity"
            | "edgeBlur.reach"
            | "depthOfField.intensity"
            | "depthOfField.focus"
            | "depthOfField.band"
            | "depthOfField.bokeh"
            | "tint.color"
            | "tint.opacity"
            | "vignette.intensity"
            | "vignette.reach"

      Returns void

    • Sets one or more effect knobs. Values are validated against the catalogue before anything is touched; knobs not mentioned keep their values.

      Parameters

      Returns void

      RangeError for a value outside its range or of the wrong kind; Error for an unknown id.

      effects.set({ 'vignette.intensity': -0.4 });

    Settings
    Member Visibility

    On This Page
    Constructors
    Methods