Растровые WMS/WMTS источники | MapGL | 2GIS Documentation
MapGL JS API
Личный кабинет

Растровые WMS/WMTS источники

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>