Добавление источников на карту

Источники данных в Mapbox GL JS являются фундаментальным уровнем архитектуры карты. Именно источники определяют, какие данные доступны для визуализации, как они загружаются, обновляются и связываются со слоями. Вся графическая модель карты строится вокруг связки «source → layer», где источник отвечает за данные, а слой — за их отображение.

Источники представляют собой абстракцию над различными форматами геоданных: GeoJSON, векторные тайлы, растровые изображения, DEM-данные и мультимедийные источники. Каждый источник имеет собственный тип, структуру и способ загрузки.

Ключевые особенности источников:

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

Добавление источников выполняется через метод map.addSource, который регистрирует объект источника в стиле карты.

map.on('load', () => {
  map.addSource('cities', {
    type: 'geojson',
    data: '/data/cities.geojson'
  });
});

После добавления источник становится доступным для всех слоёв текущего стиля.

GeoJSON источник

GeoJSON — наиболее часто используемый тип источника. Он подходит для точечных, линейных и полигональных данных, а также для динамически обновляемых объектов.

Базовая структура

map.addSource('parks', {
  type: 'geojson',
  data: {
    type: 'FeatureCollection',
    features: [
      {
        type: 'Feature',
        geometry: {
          type: 'Polygon',
          coordinates: [
            [
              [71.4, 51.1],
              [71.5, 51.1],
              [71.5, 51.2],
              [71.4, 51.2],
              [71.4, 51.1]
            ]
          ]
        },
        properties: {
          name: 'Central Park'
        }
      }
    ]
  }
});

Динамическое обновление данных

Источник можно обновлять без удаления:

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

source.setData('/data/updated_parks.geojson');

Это особенно важно для real-time приложений.

Кластеризация

GeoJSON поддерживает встроенную кластеризацию точек:

map.addSource('earthquakes', {
  type: 'geojson',
  data: '/data/earthquakes.geojson',
  cluster: true,
  clusterMaxZoom: 14,
  clusterRadius: 50
});

Кластеры формируются на стороне клиента и уменьшают нагрузку на рендеринг.

Векторные источники

Векторные источники основаны на тайлах и используются для больших наборов данных.

map.addSource('streets', {
  type: 'vector',
  url: 'mapbox://mapbox.mapbox-streets-v8'
});

Работа с source-layer

Векторный источник содержит несколько слоёв данных внутри тайла. Для доступа используется параметр source-layer.

map.addLayer({
  id: 'road-lines',
  type: 'line',
  source: 'streets',
  'source-layer': 'road',
  paint: {
    'line-color': '#333',
    'line-width': 2
  }
});

Особенности

  • высокая производительность на больших данных
  • стилизация выполняется на клиенте
  • данные загружаются по тайлам, а не целиком

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

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

map.addSource('satellite', {
  type: 'raster',
  tiles: [
    'https://example.com/tiles/{z}/{x}/{y}.png'
  ],
  tileSize: 256
});

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

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

Особенности

  • данные уже отрисованы на сервере
  • минимальная нагрузка на клиент
  • отсутствие сложной стилизации объектов

Raster DEM (рельеф)

Raster DEM используется для работы с высотами и 3D-рельефом.

map.addSource('terrain', {
  type: 'raster-dem',
  url: 'mapbox://mapbox.mapbox-terrain-dem-v1',
  tileSize: 512,
  maxzoom: 14
});

Применение:

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

Этот тип источника позволяет формировать трёхмерную поверхность карты.

Image источник

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

map.addSource('overlay', {
  type: 'image',
  url: '/images/overlay.png',
  coordinates: [
    [71.0, 51.0],
    [72.0, 51.0],
    [72.0, 52.0],
    [71.0, 52.0]
  ]
});

Применяется для:

  • исторических карт
  • тепловых изображений
  • пользовательских оверлеев

Video источник

Video source позволяет отображать видеопоток на географической области.

map.addSource('drone-video', {
  type: 'video',
  urls: [
    'https://example.com/video.mp4'
  ],
  coordinates: [
    [71.0, 51.0],
    [72.0, 51.0],
    [72.0, 52.0],
    [71.0, 52.0]
  ]
});

Используется в системах мониторинга, трансляциях и аналитике.

Общие параметры источников

bounds

Ограничивает область загрузки данных:

map.addSource('restricted', {
  type: 'geojson',
  data: '/data.json',
  bounds: [71, 51, 72, 52]
});

minzoom и maxzoom

Определяют диапазон масштабов:

map.addSource('zoomed', {
  type: 'vector',
  url: 'mapbox://example.data',
  minzoom: 5,
  maxzoom: 14
});

promoteId

Используется для указания уникального идентификатора объектов:

map.addSource('places', {
  type: 'geojson',
  data: '/places.geojson',
  promoteId: 'id'
});

Это улучшает работу с feature-state.

Связь источников и слоёв

Источник сам по себе не отображается на карте. Он становится видимым только через слой:

map.addLayer({
  id: 'parks-fill',
  type: 'fill',
  source: 'parks',
  paint: {
    'fill-color': '#00ff00',
    'fill-opacity': 0.4
  }
});

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

map.addLayer({ id: 'parks-border', type: 'line', source: 'parks' });
map.addLayer({ id: 'parks-fill', type: 'fill', source: 'parks' });

Обновление и удаление источников

Удаление:

map.removeSource('parks');

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

map.getSource('parks').setData(newData);

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

Практические аспекты архитектуры

Использование источников требует учета нескольких факторов:

  • выбор типа источника напрямую влияет на производительность
  • GeoJSON подходит для малых и средних наборов данных
  • векторные тайлы оптимальны для больших и сложных карт
  • растровые источники эффективны при готовой визуализации на сервере
  • динамические данные лучше реализовывать через setData или feature-state

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

Оглавление