Источники данных в стиле

Система отображения карт в MapLibre GL JS строится на разделении данных и визуального представления. Геометрия объектов, растровые изображения, цифровая модель рельефа и другие сведения поступают через источники данных (sources), а внешний вид определяется слоями (layers).

Источник данных описывает:

откуда загружаются данные;
в каком формате они представлены;
каким образом движок должен их интерпретировать.

Каждый источник получает уникальный идентификатор и регистрируется в объекте карты. После регистрации на него могут ссылаться один или несколько слоёв.

Базовая структура определения источника выглядит следующим образом:

map.addSource('cities', {
    type: 'geojson',
    data: 'cities.geojson'
});

После добавления источник становится доступным для использования в слоях:

map.addLayer({
    id: 'city-points',
    type: 'circle',
    source: 'cities'
});

Один источник может использоваться сразу несколькими слоями:

map.addLayer({
    id: 'city-circles',
    type: 'circle',
    source: 'cities'
});

map.addLayer({
    id: 'city-labels',
    type: 'symbol',
    source: 'cities'
});

В данном случае геометрия загружается только один раз, а отображается двумя различными способами.

Добавление источников через стиль карты

Источники могут определяться не только программно, но и непосредственно внутри объекта стиля.

Пример структуры стиля:

const style = {
    version: 8,

    sources: {
        cities: {
            type: 'geojson',
            data: 'cities.geojson'
        }
    },

    layers: [
        {
            id: 'cities',
            type: 'circle',
            source: 'cities'
        }
    ]
};

Создание карты:

const map = new maplibregl.Map({
    container: 'map',
    style: style
});

Такой подход особенно удобен при создании собственных стилей и конфигураций карт.

Основные типы источников

MapLibre GL JS поддерживает несколько типов источников данных:

Тип	Назначение
GeoJSON	Геометрические объекты
Vector	Векторные тайлы
Raster	Растровые тайлы
Raster DEM	Цифровая модель рельефа
Image	Одно изображение на карте
Video	Видео, привязанное к координатам
Canvas	HTML Canvas как источник

Каждый тип предназначен для решения определённого класса задач.

Источник GeoJSON

GeoJSON является самым популярным типом источника в MapLibre GL JS.

Поддерживаются объекты:

Point;
MultiPoint;
LineString;
MultiLineString;
Polygon;
MultiPolygon;
GeometryCollection;
FeatureCollection.

Пример встроенных данных:

map.addSource('point', {
    type: 'geojson',

    data: {
        type: 'Feature',
        geometry: {
            type: 'Point',
            coordinates: [69.2401, 41.2995]
        }
    }
});

Пример загрузки файла:

map.addSource('roads', {
    type: 'geojson',
    data: '/data/roads.geojson'
});

Источник автоматически загружает файл и преобразует данные в формат, пригодный для визуализации.

Работа с FeatureCollection

Наиболее распространённой структурой является FeatureCollection.

map.addSource('places', {
    type: 'geojson',

    data: {
        type: 'FeatureCollection',

        features: [
            {
                type: 'Feature',

                properties: {
                    name: 'Park'
                },

                geometry: {
                    type: 'Point',
                    coordinates: [37.6, 55.7]
                }
            },

            {
                type: 'Feature',

                properties: {
                    name: 'Museum'
                },

                geometry: {
                    type: 'Point',
                    coordinates: [37.62, 55.75]
                }
            }
        ]
    }
});

Каждый объект может содержать произвольный набор атрибутов внутри секции properties.

Обновление GeoJSON-данных

Одним из преимуществ GeoJSON является возможность динамического обновления.

Получение ссылки на источник:

const source = map.getSource('places');

Замена данных:

source.setData(newGeoJson);

Пример:

source.setData({
    type: 'FeatureCollection',

    features: [
        {
            type: 'Feature',

            geometry: {
                type: 'Point',
                coordinates: [30.3, 59.9]
            }
        }
    ]
});

После вызова setData() карта автоматически перерисовывается.

Генерация данных в реальном времени

GeoJSON часто применяется для отображения движущихся объектов.

Пример обновления координат:

const vehicle = {
    type: 'FeatureCollection',

    features: [
        {
            type: 'Feature',

            geometry: {
                type: 'Point',
                coordinates: [37.6, 55.7]
            }
        }
    ]
};

map.addSource('vehicle', {
    type: 'geojson',
    data: vehicle
});

Изменение положения:

setInterval(() => {

    vehicle.features[0].geometry.coordinates[0] += 0.001;

    map.getSource('vehicle').setData(vehicle);

}, 1000);

Такой подход широко применяется в системах мониторинга транспорта, логистике и навигации.

Источник Vector

Векторные тайлы предназначены для работы с большими объёмами данных.

В отличие от GeoJSON, где загружается целый набор объектов, векторные тайлы подгружаются по частям в зависимости от текущего масштаба и области просмотра.

Пример подключения:

map.addSource('vector-source', {
    type: 'vector',
    tiles: [
        'https://server.com/tiles/{z}/{x}/{y}.pbf'
    ]
});

Использование в слое:

map.addLayer({
    id: 'roads',

    type: 'line',

    source: 'vector-source',

    'source-layer': 'roads'
});

Параметр source-layer обязателен и определяет слой внутри векторного тайла.

Преимущества векторных тайлов

Использование Vector Source обеспечивает:

высокую производительность;
минимальный сетевой трафик;
плавное масштабирование;
работу с миллионами объектов;
серверную генерацию данных.

Именно векторные тайлы лежат в основе большинства современных веб-карт.

Настройка диапазона масштабов

Для векторных источников можно ограничивать масштаб загрузки.

map.addSource('vector-source', {
    type: 'vector',

    tiles: [
        'https://server.com/{z}/{x}/{y}.pbf'
    ],

    minzoom: 0,
    maxzoom: 14
});

Параметры позволяют контролировать объём загружаемых данных и снижать нагрузку на сервер.

Источник Raster

Raster Source используется для отображения растровых тайлов.

Пример:

map.addSource('satellite', {
    type: 'raster',

    tiles: [
        'https://server.com/tiles/{z}/{x}/{y}.png'
    ],

    tileSize: 256
});

Добавление слоя:

map.addLayer({
    id: 'satellite-layer',
    type: 'raster',
    source: 'satellite'
});

Типичными примерами растровых данных являются:

спутниковые снимки;
сканированные карты;
ортофотопланы;
погодные карты.

Размер тайлов Raster Source

Параметр tileSize определяет размер тайла в пикселях.

Наиболее распространённые значения:

tileSize: 256

или

tileSize: 512

Если сервер отдаёт тайлы 512×512, необходимо указать соответствующее значение.

Источник Raster DEM

Raster DEM применяется для работы с рельефом.

Пример подключения:

map.addSource('terrain', {
    type: 'raster-dem',

    tiles: [
        'https://server.com/dem/{z}/{x}/{y}.png'
    ],

    tileSize: 256
});

Активация рельефа:

map.setTerrain({
    source: 'terrain',
    exaggeration: 1.5
});

Параметр exaggeration задаёт коэффициент вертикального преувеличения.

Использование цифровой модели высот

DEM-источники позволяют:

строить трёхмерный рельеф;
выполнять затенение поверхности;
отображать горные районы;
анализировать высоты.

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

Источник Image

Image Source позволяет разместить изображение на произвольной области карты.

Пример:

map.addSource('overlay', {
    type: 'image',

    url: '/images/map.png',

    coordinates: [
        [37.60, 55.80],
        [37.70, 55.80],
        [37.70, 55.70],
        [37.60, 55.70]
    ]
});

Добавление слоя:

map.addLayer({
    id: 'overlay-layer',
    type: 'raster',
    source: 'overlay'
});

Изображение автоматически деформируется в соответствии с указанными координатами.

Практическое применение Image Source

Image Source используется для:

исторических карт;
схем территорий;
планов зданий;
инженерных чертежей;
тепловых карт, созданных внешними системами.

Источник Video

Video Source работает аналогично Image Source, но вместо изображения используется видеопоток.

map.addSource('video', {
    type: 'video',

    urls: [
        '/video/demo.mp4'
    ],

    coordinates: [
        [37.60, 55.80],
        [37.70, 55.80],
        [37.70, 55.70],
        [37.60, 55.70]
    ]
});

Слой:

map.addLayer({
    id: 'video-layer',
    type: 'raster',
    source: 'video'
});

Видео воспроизводится непосредственно на поверхности карты.

Источник Canvas

Canvas Source связывает карту с элементом HTML Canvas.

Создание элемента:

<canvas id="animation"></canvas>

Подключение:

map.addSource('canvas-source', {
    type: 'canvas',

    canvas: 'animation',

    coordinates: [
        [37.60, 55.80],
        [37.70, 55.80],
        [37.70, 55.70],
        [37.60, 55.70]
    ],

    animate: true
});

Добавление слоя:

map.addLayer({
    id: 'canvas-layer',
    type: 'raster',
    source: 'canvas-source'
});

Параметр animate

Свойство animate определяет необходимость постоянного обновления содержимого Canvas.

animate: true

Используется для:

анимаций;
потоковых данных;
визуализации сенсоров;
отображения физических моделей;
специализированных графических эффектов.

Получение существующего источника

После регистрации источник можно получить через API карты.

const source = map.getSource('cities');

Проверка существования:

if (map.getSource('cities')) {
    console.log('Источник найден');
}

Подход часто используется при динамической загрузке данных.

Удаление источника

Удаление выполняется методом:

map.removeSource('cities');

Однако перед удалением необходимо удалить все связанные слои.

Неверный вариант:

map.removeSource('cities');

Правильный порядок:

map.removeLayer('city-layer');

map.removeSource('cities');

MapLibre GL JS не позволит удалить источник, который используется хотя бы одним слоем.

События загрузки источников

Контроль загрузки осуществляется через события карты.

Пример:

map.on('sourcedata', (event) => {

    console.log(event);

});

Событие вызывается при:

загрузке источника;
обновлении данных;
подгрузке тайлов;
изменении состояния кэша.

Проверка готовности источников

Для определения завершения загрузки карты используется метод:

if (map.isSourceLoaded('cities')) {
    console.log('Источник загружен');
}

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

Организация источников в крупных проектах

В больших картографических приложениях распространена следующая схема:

sources: {
    basemap: {},
    roads: {},
    buildings: {},
    terrain: {},
    vehicles: {},
    weather: {}
}

Каждый источник отвечает за отдельный набор данных:

базовая карта;
дорожная сеть;
здания;
рельеф;
транспорт;
погодная информация.

Такое разделение облегчает поддержку проекта, ускоряет поиск ошибок и позволяет независимо обновлять различные части картографической системы.

Источники данных в стиле

Добавление источников через стиль карты

Основные типы источников

Источник GeoJSON

Работа с FeatureCollection

Обновление GeoJSON-данных

Генерация данных в реальном времени

Источник Vector

Преимущества векторных тайлов

Настройка диапазона масштабов

Источник Raster

Размер тайлов Raster Source

Источник Raster DEM

Использование цифровой модели высот

Источник Image

Практическое применение Image Source

Источник Video

Источник Canvas

Параметр animate

Получение существующего источника

Удаление источника

События загрузки источников

Проверка готовности источников

Организация источников в крупных проектах

Рекомендации по выбору типа источника