Растровые источники данных | MapGL | 2GIS Documentation
MapGL JS API

Растровые источники данных

MapGL JS API позволяет отображать данные от внешних растровых источников, поэтому пользователь может добавлять на карту слои различных географических объектов, хилшейда, спутниковых снимков и других данных. Для этого нужно подключить RasterTileSource и добавить слой в стиль карты для этого источника. RasterTileSource позволяет запрашивать тайлы как по bounding box (Web Map Service — WMS), так и по их координатам в матрице тайлов (Web Map Tile Service — WMTS).

WMS — стандарт, разработанный OGC (Open Geospatial Consortium), позволяющий динамически получать географические данные в виде изображения (в форматах PNG, JPEG, GIF и др.) с привязкой к местности. Построение изображения производится на основе его параметров, переданных в пользовательском запросе: географических координат (bounding box), формата и размеров. WMS позволяет получать изображение данных по слоям, а также сделать фон итогового изображения прозрачным. Это дает возможность, например, накладывать друг на друга слои, полученные с разных серверов. Для кастомизации можно указать в запросе стили для слоев данных.

const source = new mapgl.RasterTileSource(map, {
    url: (_x, _y, _zoom, bbox) => {
        const southWest = bbox.southWest.map((c) => String(c).replace(',', '.')).join(',');
        const northEast = bbox.northEast.map((c) => String(c).replace(',', '.')).join(',');
        return `https://ows.terrestris.de/osm/service?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&FORMAT=image/png&TRANSPARENT=true&LAYERS=OSM-Overlay-WMS&HEIGHT=256&WIDTH=256&SRS=EPSG:3857&STYLES=&BBOX=${southWest},${northEast}`;
    },
    attribution:
        '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors',
    attributes: { bar: 'asd' },
});

Примечания

  • Аргумент bbox функции из опции url в RasterTileSourceOptions должен содержать значения координат в проекции EPSG:3857 (Веб-Меркатор, Псевдо-Меркатор).
  • Чтобы источник отличался от других, нужно добавить ему уникальное свойство через поле attributes — после этого его можно будет связать с новым слоем стиля карты, а значит и отобразить.
  • Помните, что большинство сервисов требуют указывать копирайт. Сделать это можно через поле attribution.

WMTS — стандарт, также разработанный OGC. Он разделяет логику работы с WMS, но заточен на производительность и масштабируемость: пользователю возвращаются уже преподготовленные или закешированные изображения размером 256 или 512 пикселей, что не требует манипуляций с ними и с обработкой географических данных.

const source = new mapgl.RasterTileSource(map, {
    url: (x, y, zoom) => `https://tile.openstreetmap.org/${zoom}/${x}/${y}.png`,
    attribution:
        '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors',
    attributes: { bar: 'asd' },
});

Примечания

  • Чтобы источник отличался от других, нужно добавить ему уникальное свойство через поле attributes — после этого его можно будет связать с новым слоем стиля карты, а значит и отобразить.
  • Помните, что большинство сервисов требуют указывать копирайт. Сделать это можно через поле attribution.

Стиль карты — это конфиг, который описывает, как отрисовывать данные карты. Стиль состоит из слоев, каждый из которых содержит:

  • в поле filter — логику фильтрации данных карты для определения, какие именно данные будет отрисовывать этот слой;
  • в поле style — описание внешнего вида объектов отрисовки (цвет, ширина, шрифт и пр.).

Подробнее про стиль карты можно узнать в Спецификации стиля.

Сначала создайте новый слой:

const layer = {
    id: 'raster-tile-layer', // ID каждого слоя должен быть уникальным

    // Логика фильтрации или выбора данных для этого слоя
    filter: [
        'match',
        ['sourceAttr', 'bar'],
        ['asd'],
        true, // Значение при совпадении атрибута "bar" источника cо значением "asd"
        false, // Значение при несовпадении
    ],

    // Тип объекта отрисовки
    type: 'raster',

    // Стиль объекта отрисовки
    style: {
        opacity: 1,
    },
};

Затем добавьте слой после загрузки стиля:

map.on('styleload', () => {
    map.addLayer(layer);
});

filter использует следующие выражения:

  • SourceAttrExpression — для получения значений из свойства bar источника данных;
  • MatchExpression — для сопоставления полученного свойства из атрибута bar со строковым значением asd.

Пример работы RasterTileSource со стандартом WMS:

<!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="RWMS example" />
        <style>
            html,
            body,
            #container {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
            }
        </style>
    </head>
    <body>
        <div id="container"></div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
        <script>
            const map = new mapgl.Map('container', {
                center: [82.920412, 55.030111],
                zoom: 11,
                key: 'Your API access key',
            });

            const source = new mapgl.RasterTileSource(map, {
                url: (_x, _y, _zoom, bbox) => {
                    const southWest = bbox.southWest.map((c) => String(c).replace(',', '.')).join(',');
                    const northEast = bbox.northEast.map((c) => String(c).replace(',', '.')).join(',');
                    return `https://ows.terrestris.de/osm/service?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&FORMAT=image/png&TRANSPARENT=true&LAYERS=OSM-Overlay-WMS&HEIGHT=256&WIDTH=256&SRS=EPSG:3857&STYLES=&BBOX=${southWest},${northEast}`;
                },
                attribution:
                    '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors',

                // Атрибут источника для логики фильтрации данных
                attributes: { bar: 'asd' },
            })

            const layer = {
                // Тип объекта отрисовки
                type: 'raster',

                // ID каждого слоя должен быть уникальным
                id: 'raster-tile-layer',

                // Логика фильтрации данных
                filter: [
                    'match',
                    ['sourceAttr', 'bar'], // Сопоставление с атрибутом из источника данных
                    ['asd'],
                    true, // Значение при совпадении атрибута "bar" источника cо значением "asd"
                    false // Значение при несовпадении
                ],
                // Стиль объекта отрисовки
                style: {
                    opacity: 1,
                },
            };

            map.on('styleload', () => {
                map.addLayer(layer);
            });
        </script>
    </body>
</html>

Пример работы RasterTileSource со стандартом WMTS:

<!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="WMTS example" />
        <style>
            html,
            body,
            #container {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
            }
        </style>
    </head>
    <body>
        <div id="container"></div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
        <script>
            const map = new mapgl.Map('container', {
                center: [82.920412, 55.030111],
                zoom: 11,
                key: 'Your API access key',
            });

            const source = new mapgl.RasterTileSource(map, {
                url: (x, y, zoom) => `https://tile.openstreetmap.org/${zoom}/${x}/${y}.png`,
                attribution:
                    '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors',

                // Source attribute for data filtering logic
                attributes: { bar: 'asd' },
            })

            const layer = {
                // Drawing object type
                type: 'raster',

                // Each layer ID must be unique
                id: 'raster-tile-layer',

                // Data filtering logic
                filter: [
                    'match',
                    ['sourceAttr', 'bar'], // Match with attribute from data source
                    ['asd'],
                    true, // Result if value of bar source attribute equals "asd"
                    false // Result if not
                ],
                // Style of drawing object
                style: {
                    opacity: 1,
                },
            };

            map.on('styleload', () => {
                map.addLayer(layer);
            });
        </script>
    </body>
</html>