Параметры конфигурации источников

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

Источник задаётся в разделе sources объекта стиля:

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

Ключ верхнего уровня (my-source) используется слоями для привязки данных через source: "my-source". Внутри объекта источника ключевым параметром всегда выступает type, определяющий стратегию загрузки и обработки данных.

Базовые параметры конфигурации источников

Несмотря на различие типов источников, существует набор общих параметров, применимых ко многим из них.

type

Определяет тип источника. Поддерживаются:

  • geojson
  • vector
  • raster
  • raster-dem
  • image
  • video

Тип определяет допустимые остальные параметры и формат данных.

bounds

Ограничивает область действия источника географическим прямоугольником:

bounds: [-180, -85.0511, 180, 85.0511]

Формат: [west, south, east, north].

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

minzoom и maxzoom

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

minzoom: 0,
maxzoom: 14

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

attribution

Строка атрибуции источника данных:

attribution: "© OpenStreetMap contributors"

Отображается в элементах управления картой и используется для соблюдения лицензий.

Vector source (векторные тайлы)

Векторные источники используют тайлы формата Mapbox Vector Tile.

Основные параметры

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

url

Указывает на tileset или стиль Mapbox:

  • mapbox://... — ссылка на Mapbox tileset
  • URL на TileJSON

tiles

Альтернатива url, определяющая шаблоны тайлов:

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

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

scheme

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

  • xyz — стандартная схема (по умолчанию)
  • tms — перевёрнутая схема
scheme: "xyz"

promoteId

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

promoteId: "id"

или для отдельных слоёв:

promoteId: {
  buildings: "building_id"
}

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

GeoJSON source

GeoJSON источник представляет данные в формате GeoJSON и может работать как с локальными объектами, так и с удалёнными ресурсами.

Пример конфигурации

{
  type: "geojson",
  data: "https://example.com/data.geojson"
}

data

Определяет источник GeoJSON:

  1. URL
  2. Inline объект
  3. Функция обновления через API

Пример inline:

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

cluster

Включает кластеризацию точечных объектов:

cluster: true

При включении точки группируются в кластеры в зависимости от масштаба.

clusterRadius

Радиус кластеризации в пикселях:

clusterRadius: 50

Чем больше значение, тем более агрессивно происходит группировка.

clusterMaxZoom

Максимальный zoom, до которого выполняется кластеризация:

clusterMaxZoom: 12

После этого уровня кластеры распадаются на отдельные точки.

clusterProperties

Позволяет агрегировать свойства объектов внутри кластера:

clusterProperties: {
  sum: ["+", ["get", "value"]]
}

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

tolerance

Параметр упрощения геометрии (Douglas-Peucker):

tolerance: 0.375

Уменьшает количество вершин для оптимизации производительности.

Raster source (растровые тайлы)

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

Пример

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

tiles

Шаблоны URL растровых тайлов. Поддерживаются {z}, {x}, {y}.

tileSize

Размер тайла в пикселях:

tileSize: 256

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

Raster-dem source (цифровые модели рельефа)

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

Пример

{
  type: "raster-dem",
  url: "mapbox://mapbox.terrain-rgb",
  encoding: "mapbox"
}

encoding

Формат кодирования высот:

  • mapbox — Mapbox Terrain RGB
  • terrarium — альтернативный формат
encoding: "mapbox"

Image source

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

Пример

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

url

Ссылка на изображение.

coordinates

Массив из четырёх координат, задающих углы изображения в порядке:

  • верхний левый
  • верхний правый
  • нижний правый
  • нижний левый

Video source

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

Пример

{
  type: "video",
  urls: [
    "https://example.com/video.mp4"
  ],
  coordinates: [
    [-122.51596391201019, 37.56238816766053],
    [-122.51467645168304, 37.56410183312965],
    [-122.51309394836426, 37.563391708549425],
    [-122.51423120498657, 37.56161849366671]
  ]
}

urls

Список видеофайлов. Поддерживаются несколько источников для fallback.

coordinates

Геопривязка видеоповерхности аналогична image source.

Поведение обновления источников

Источники в Mapbox GL JS могут обновляться динамически через API:

  • setData для GeoJSON
  • setTiles косвенно через перезагрузку стиля
  • пересоздание источника через removeSource и addSource

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

map.getSource("my-source").setData(newData);

Ограничения и оптимизация

Конфигурация источников влияет на производительность рендеринга:

  • чрезмерная кластеризация снижает точность визуализации
  • большие GeoJSON без упрощения увеличивают нагрузку CPU
  • слишком широкий bounds приводит к лишним запросам тайлов
  • высокое tileSize увеличивает память GPU

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

  • minzoom / maxzoom
  • tolerance
  • clusterRadius
  • корректной разбиением данных на тайлы

Взаимодействие источников со слоями

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

{
  id: "points-layer",
  type: "circle",
  source: "my-source"
}

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

Оглавление