Deck2gisLayer | MapGL | 2GIS Documentation
MapGL JS API

The rendering of deck.gl layers on the map

Deck2gisLayer plugin allows to render deck.gl layers inside the MapGl canvas / WebGL context.

To use deck.gl layers, you need to include the Deck2gisLayer plugin and the deck.gl framework in your project. To do this, add the following lines after the main MapGL scripts:

<script src="https://unpkg.com/@2gis/deck2gis-layer@^2/dist/deck2gislayer.js"></script>
<script src="https://unpkg.com/deck.gl@^8/dist.min.js"></script>

Or you can install the needed packages using npm:

npm install @2gis/deck2gis-layer @deck.gl/core @deck.gl/layers

Important

The current version of the Deck2gisLayer plugin is only compatible with the deck.gl@^8

To work with Deck2gisLayer, first you need to create the deck.gl instance by initializing it with the initDeck function.

import { Deck } from '@deck.gl/core';
import { Deck2gisLayer, initDeck } from '@2gis/deck2gis-layer';

const deck = initDeck(map, Deck, { antialiasing: 'msaa' });

The initDeck helper function creates deck.gl instance that will connect the resulting deck.gl to the MapGL map.

The next step is creating deck.gl layers on the MapGL map.

Deck2gisLayer object: As an example, let's add a new layer, namely HexagonLayer. The HexagonLayer aggregates data into a hexagon-based heatmap. The color and height of a hexagon are determined based on the objects it contains.

import { HexagonLayer } from '@deck.gl/aggregation-layers/typed';

const data = [
    {
        point: {
            lon: 55.296872,
            lat: 25.261885,
        },
    },
];

const deckHexagonLayer = new Deck2gisLayer({
    id: 'deckgl-HexagonLayer',
    deck,
    type: HexagonLayer,
    data,
    radius: 250,
    getPosition: (d) => [d.point.lon, d.point.lat],
});

When initializing the Deck2gisLayer, you have to specify the required attributes:

  • id (string) - a unique id across all map style layers.

  • deck (Deck) - a Deck instance that controls the rendering of this layer.

  • type (Layer) - a class that extends the deck.gl's base Layer class.

  • [...] — any other properties needed to render the deck.gl layer. See deck.gl's layer catalog and examples on how to create layers.

It is important to add new layers only after style has been loaded, because the new style will remove all added layers. To do this use the styleload event, which is emitted every time a new style has been set, for more see addLayer example

map.on('styleload', () => {
    map.addLayer(deckHexagonLayer);
});
<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>2GIS Map API</title>
    <meta name="description" content="Deck2gis-layer plugin example" />
    <style>
        html,
        body,
        #container {
            margin: 0;
            width: 500px;
            height: 300px;
            overflow: hidden;
        }
    </style>
</head>

<body>
    <script src="https://mapgl.2gis.com/api/js/v1"></script>
    <script src="https://unpkg.com/@2gis/deck2gis-layer@^2/dist/deck2gislayer.js"></script>
    <script src="https://unpkg.com/deck.gl@^8/dist.min.js"></script>

    <div id="container"></div>
    <script>
        const map = new mapgl.Map('container', {
            center: [55.296872, 25.261885],
            zoom: 12.5,
            key: 'Your API access key',
        });
        const deckgl = mapgl.Deck2gisLayer.initDeck(map, deck.Deck, { antialiasing: 'msaa' });
        const data = [
            {
                point: {
                    lon: 55.296872,
                    lat: 25.261885,
                },
            },
            {
                point: {
                    lon: 55.296644,
                    lat: 25.262364,
                },
            },
            {
                point: {
                    lon: 55.299031,
                    lat: 25.254415,
                },
            },
            {
                point: {
                    lon: 55.299031,
                    lat: 25.254415,
                },
            },
        ];
        const deckHexagonLayer = new mapgl.Deck2gisLayer({
            id: 'deckgl-HexagonLayer',
            deck: deckgl,
            type: deck.HexagonLayer,
            data,
            radius: 480,
            getPosition: (d) => [d.point.lon, d.point.lat],
        });
        map.once('styleload', () => {
            map.addLayer(deckHexagonLayer);
        });
    </script>
</body>

</html>