Настройка в source

В Mapbox GL JS источники данных (sources) являются фундаментальным уровнем, на котором строится вся визуализация карты. Именно source определяет, откуда поступают географические данные, в каком формате они приходят и как они будут использоваться слоями (layers) для рендеринга.

Source — это абстракция над набором данных, которая отделяет хранение данных от их отображения. Один и тот же источник может использоваться несколькими слоями одновременно, что обеспечивает переиспользование данных без дублирования.

Структурно source описывается внутри стиля карты и всегда имеет уникальный идентификатор:

{
  "sources": {
    "my-source": {
      "type": "geojson",
      "data": "https://example.com/data.geojson"
    }
  }
}

Ключевым моментом является то, что source не отображается сам по себе — он только предоставляет данные слоям.

Роль source в системе слоёв

Архитектура Mapbox GL JS строится по принципу разделения ответственности:

  • source — данные
  • layer — визуализация данных

Один source может быть использован множеством layers:

  • fill-слой для полигонов
  • line-слой для границ
  • circle-слой для точек

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

Основные типы source

Mapbox GL JS поддерживает несколько типов источников, каждый из которых предназначен для определённого сценария работы с геоданными.

GeoJSON source

Наиболее универсальный тип источника. Используется для работы с объектами в формате GeoJSON.

{
  "type": "geojson",
  "data": {
    "type": "FeatureCollection",
    "features": []
  }
}

Особенности:

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

Vector tiles source

Векторные тайлы — основной формат для масштабируемых карт в Mapbox.

{
  "type": "vector",
  "url": "mapbox://mapbox.mapbox-streets-v8"
}

или

{
  "type": "vector",
  "tiles": [
    "https://example.com/tiles/{z}/{x}/{y}.pbf"
  ]
}

Особенности:

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

Raster source

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

{
  "type": "raster",
  "tiles": [
    "https://example.com/tiles/{z}/{x}/{y}.png"
  ],
  "tileSize": 256
}

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

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

Image source

Позволяет накладывать одиночное изображение на географические координаты.

{
  "type": "image",
  "url": "https://example.com/image.png",
  "coordinates": [
    [-80, 45],
    [-70, 45],
    [-70, 40],
    [-80, 40]
  ]
}

Особенности:

  • фиксируется на координатной рамке
  • не масштабируется как тайлы
  • подходит для overlay-данных

Video source

Источник для привязки видео к географическим координатам.

{
  "type": "video",
  "urls": [
    "https://example.com/video.mp4"
  ],
  "coordinates": [
    [-80, 45],
    [-70, 45],
    [-70, 40],
    [-80, 40]
  ]
}

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

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

Общая структура конфигурации source

Несмотря на различие типов, многие свойства являются общими.

id источника

Каждый source регистрируется под уникальным ключом:

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

data

Используется только в GeoJSON:

  • объект GeoJSON
  • URL к GeoJSON файлу

url

Применяется в vector sources:

"url": "mapbox://mapbox.mapbox-streets-v8"

tiles

Массив шаблонов тайлов:

"tiles": [
  "https://example.com/{z}/{x}/{y}.pbf"
]

minzoom и maxzoom

Ограничивают диапазон отображения источника:

{
  "minzoom": 0,
  "maxzoom": 14
}

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

bounds

Определяет географические границы источника:

"bounds": [-180, -85, 180, 85]

Если камера выходит за пределы bounds, данные не загружаются.

scheme

Определяет схему тайлов:

  • "xyz" — стандартная Web Mercator схема
  • "tms" — перевёрнутая схема

attribution

Указание источника данных:

"attribution": "OpenStreetMap contributors"

Добавление source через JavaScript API

В Mapbox GL JS источники добавляются через метод addSource:

map.on('load', () => {
  map.addSource('points', {
    type: 'geojson',
    data: {
      type: 'FeatureCollection',
      features: []
    }
  });
});

После добавления source становится доступен для слоёв.

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

Привязка слоя к source осуществляется через source:

map.addLayer({
  id: 'points-layer',
  type: 'circle',
  source: 'points',
  paint: {
    'circle-radius': 6,
    'circle-color': '#ff0000'
  }
});

Обновление GeoJSON source

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

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

source.setData({
  type: 'FeatureCollection',
  features: [
    {
      type: 'Feature',
      geometry: {
        type: 'Point',
        coordinates: [30, 50]
      }
    }
  ]
});

Это ключевой механизм для:

  • realtime-данных
  • трекинга объектов
  • интерактивных карт

Векторные источники и производительность

Vector source в Mapbox экосистеме Mapbox оптимизированы под работу с большими объёмами данных.

Особенности обработки:

  • данные загружаются по тайлам
  • рендеринг происходит на GPU
  • фильтрация осуществляется на уровне слоёв
  • поддержка feature-state для динамических изменений

Feature-State и связь с source

Для vector и geojson источников доступна концепция feature-state:

map.setFeatureState(
  { source: 'states', id: 123 },
  { hover: true }
);

Это позволяет изменять внешний вид объектов без изменения самих данных source.

Удаление и замена source

Удаление выполняется через:

map.removeSource('points');

Важно учитывать:

  • все слои, использующие source, должны быть удалены заранее
  • замена source требует пересоздания зависимых layers

Ошибки при работе с source

Наиболее частые проблемы:

1. Source используется до загрузки карты

Решается использованием map.on('load').

2. Несоответствие типа данных

Например, попытка передать GeoJSON в vector source.

3. Дублирование ID

Каждый source должен иметь уникальный идентификатор.

4. Несовместимость слоёв и source

Circle layer не может работать с raster source.

Архитектурная модель работы source

Внутренне система Mapbox GL JS обрабатывает source по следующему принципу:

  1. регистрация source в стиле
  2. запрос данных (tiles, json, image)
  3. кэширование
  4. передача в рендерер
  5. связывание с layers
  6. GPU-отрисовка

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

Практическая организация source в стиле

Типичная структура style JSON:

{
  "version": 8,
  "sources": {
    "cities": {
      "type": "geojson",
      "data": "/data/cities.geojson"
    },
    "roads": {
      "type": "vector",
      "url": "mapbox://mapbox.mapbox-streets-v8"
    },
    "satellite": {
      "type": "raster",
      "tiles": [
        "https://example.com/satellite/{z}/{x}/{y}.png"
      ],
      "tileSize": 256
    }
  },
  "layers": []
}

Поведение источников при масштабировании

Разные типы source ведут себя по-разному при zoom:

  • GeoJSON — полностью загружается и фильтруется
  • Vector — подгружается по тайлам
  • Raster — загружается как изображения тайлов
  • Image/Video — масштабируются как единый слой

Взаимодействие source и фильтрации

Фильтрация в layers позволяет ограничивать отображение данных из source:

filter: ['==', ['get', 'type'], 'city']

При этом сам source остаётся неизменным.

Оптимизационные аспекты

Ключевые принципы эффективной работы:

  • минимизация GeoJSON при больших данных
  • использование vector tiles вместо GeoJSON
  • ограничение bounds для источников
  • настройка minzoom/maxzoom
  • повторное использование одного source для нескольких layers

Особенности жизненного цикла source

Источник проходит несколько стадий:

  • создание (addSource)
  • загрузка данных
  • кэширование
  • использование слоями
  • обновление (setData / tile reload)
  • удаление (removeSource)

Эти стадии управляются внутренним state manager библиотеки Mapbox GL JS

Оглавление