Image source

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

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

Геопривязка изображения

Image source в Mapbox GL JS задаётся через четыре угловые точки:

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

Каждая точка задаётся в формате [longitude, latitude].

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

const coordinates = [
  [-80.425, 46.437],
  [-71.516, 46.437],
  [-71.516, 37.936],
  [-80.425, 37.936]
];

Такая схема позволяет «растянуть» изображение по поверхности карты с учётом проекции Web Mercator, используемой в Mapbox GL JS.

Добавление image source в стиль карты

Image source добавляется через метод addSource. В отличие от растровых тайлов, здесь используется тип image и объект coordinates.

map.on('load', () => {
  map.addSource('overlay-image', {
    type: 'image',
    url: 'https://example.com/overlay.png',
    coordinates: [
      [-80.425, 46.437],
      [-71.516, 46.437],
      [-71.516, 37.936],
      [-80.425, 37.936]
    ]
  });
});

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

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

Поведение и особенности рендеринга

Image source обрабатывается как единый текстурный объект. Это означает:

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

Внутри рендеринга Mapbox GL JS изображение накладывается как текстура на два треугольника, формирующих прямоугольник в пространстве карты.

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

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

Обновление координат

const source = map.getSource('overlay-image');

source.setCoordinates([
  [-80.0, 46.0],
  [-70.0, 46.0],
  [-70.0, 37.0],
  [-80.0, 37.0]
]);

Это позволяет «перетягивать» изображение по карте в реальном времени.

Замена изображения

const source = map.getSource('overlay-image');

source.updateImage('https://example.com/new-overlay.png');

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

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

map.removeLayer('overlay-layer');
map.removeSource('overlay-image');

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

Отличие image source от raster source

В Mapbox GL JS существует принципиальное различие между image и raster источниками:

Image source

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

Raster source

  • тайловая система (XYZ или WMTS)
  • масштабирование через уровни зума
  • поддержка больших наборов данных
  • используется для спутниковых и базовых слоёв

Работа с addImage и sprite

Отдельный механизм — addImage, который не относится к image source напрямую.

map.loadImage('icon.png', (error, image) => {
  if (error) throw error;

  map.addImage('custom-icon', image);
});

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

Разграничение:

  • addImage → иконки в стилях
  • image source → геопривязанные растровые оверлеи

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

Оверлей исторической карты

Image source применяется для наложения отсканированных карт:

map.addSource('historic-map', {
  type: 'image',
  url: '/maps/1900.png',
  coordinates: [...]
});

Медицинские и инженерные схемы

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

  • планы этажей
  • тепловые карты помещений
  • инженерные чертежи инфраструктуры

Аналитические визуализации

Image source часто служит контейнером для заранее подготовленных heatmap-рендеров или научных визуализаций.

Ограничения и особенности производительности

Image source имеет ряд ограничений, связанных с архитектурой WebGL:

  • отсутствие LOD (levels of detail)
  • фиксированное разрешение изображения
  • ограниченная точность при масштабировании
  • возможные артефакты при сильном зуме

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

Взаимодействие с системой стилей Mapbox GL JS

Image source интегрируется в стиль карты как полноценный слой данных. Он участвует в:

  • порядке рендеринга слоёв (layer stack)
  • прозрачности и blending modes
  • маскировании другими слоями
  • управлении видимостью через layout.visibility
map.setLayoutProperty('overlay-layer', 'visibility', 'none');

Обработка трансформаций и проекций

Mapbox GL JS использует Web Mercator projection, поэтому геопривязка изображения выполняется в проекционном пространстве.

Это означает:

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

Частые ошибки при использовании image source

Некорректный порядок координат

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

Несовпадение пропорций

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

Попытка использования как тайлового слоя

Image source не поддерживает tile-based рендеринг, поэтому не масштабируется как raster source.

Взаимодействие с событиями карты

Image source можно комбинировать с событиями Mapbox GL JS:

map.on('click', 'overlay-layer', (e) => {
  console.log(e.lngLat);
});

Хотя сам image source не является интерактивным по умолчанию, слой поверх него может обрабатывать события.

Динамические сценарии обновления

При работе с временными данными image source часто обновляется в зависимости от состояния приложения:

  • смена временного периода
  • переключение слоёв анализа
  • обновление внешних данных
function updateOverlay(url, coords) {
  const source = map.getSource('overlay-image');
  source.updateImage(url);
  source.setCoordinates(coords);
}

Архитектурная роль image source

Внутри Mapbox GL JS image source выступает как минималистичный тип данных, обеспечивающий:

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

Он занимает промежуточное положение между статическим изображением и полноценным геоданным слоем.

Оглавление