TomTom Maps SDK for JavaScript
This is the documentation of version 0.56.0. 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 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 and capture read the map canvas, which needs mapLibre: { canvasContextAttributes: { preserveDrawingBuffer: true } } when creating the map; the plugin warns once when it is missing.

    describe returns the knobs in the same shape as StylingModule.describe(), so a control panel or an agent tool built for the SDK's styling catalogue reads this one unchanged.

    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
    applyConfig capture describe get getConfig remove 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

    • 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 effects catalogue: every knob with kind, range, default, current value and the practical use case it serves. Same descriptor shape as StylingModule.describe().

      Returns MapEffectsCatalogue

    • 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

    • 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