Наложение изображений

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

Платформа Mapbox предоставляет механизм добавления изображений через тип источника image, который позволяет накладывать любые растровые данные: исторические карты, сканы планов, тепловые карты, визуализации с дронов, схемы помещений.

Mapbox official website

Модель изображения как геопространственного слоя

Изображение в Mapbox GL JS рассматривается как текстура, закреплённая за четырьмя координатами:

  • северо-запад (top-left)
  • северо-восток (top-right)
  • юго-восток (bottom-right)
  • юго-запад (bottom-left)

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

Ключевой момент: изображение не «знает» про проекцию само по себе, оно лишь интерполируется в соответствии с текущей проекцией карты.

Добавление изображения через источник image

Основной способ наложения изображения — использование map.addSource с типом image.

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

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

Здесь:

  • url — источник изображения (PNG, JPEG, WebP)
  • coordinates — географическая привязка четырёх углов
  • слой типа raster отвечает за отображение

Геопривязка и система координат

Порядок координат строго фиксирован:

  1. верхний левый угол
  2. верхний правый угол
  3. нижний правый угол
  4. нижний левый угол

Любое нарушение порядка приводит к искажению изображения.

Пример логики привязки:

  • широта определяет вертикальное растяжение
  • долгота определяет горизонтальное растяжение

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

Изменение и обновление изображения

Источник изображения можно динамически заменять через setCoordinates и setUrl (через setSource-подход или удаление/добавление источника).

Типичный подход обновления координат:

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

source.setCoordinates([
  [-80.0, 46.0],
  [-71.0, 46.0],
  [-71.0, 38.0],
  [-80.0, 38.0]
]);

Обновление URL обычно реализуется через пересоздание источника:

map.removeSource('overlay-image');

map.addSource('overlay-image', {
  type: 'image',
  url: 'https://example.com/new-image.png',
  coordinates: [...]
});

Прозрачность и композитинг

Растровый слой поддерживает стандартные параметры рендеринга:

paint: {
  'raster-opacity': 0.5,
  'raster-fade-duration': 0
}

Особенности композитинга:

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

Пример вставки слоя под подписи:

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

Масштабирование и поведение при зуме

Изображение ведёт себя как геопривязанный слой:

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

В отличие от тайловых слоёв, изображение не пере-загружается и не дробится.

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

Исторические карты

Наложение старых карт на современную географию:

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

Архитектурные планы

Использование изображений как подложки:

  • планы зданий
  • схемы этажей
  • инженерные чертежи

Спутниковые и дрон-изображения

  • ортофотопланы
  • временные снимки территорий
  • локальные зоны мониторинга

Специализированные визуализации

  • тепловые карты, сгенерированные вне Mapbox
  • аналитические растровые слои
  • медицинские или научные визуализации

Управление видимостью и слоями

Видимость слоя регулируется стандартными свойствами:

map.setLayoutProperty('overlay-layer', 'visibility', 'none');

или

map.setLayoutProperty('overlay-layer', 'visibility', 'visible');

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

Оптимизация работы с изображениями

При работе с большими растровыми слоями важно учитывать ограничения WebGL:

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

Слишком большие изображения приводят к:

  • повышенному потреблению памяти GPU
  • снижению FPS при зуме и панорамировании

Рекомендуется использовать:

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

Формат

  • PNG — для прозрачности
  • JPEG — для фотографий
  • WebP — компромисс между размером и качеством

Ограничения модели image-source

Система имеет ряд архитектурных ограничений:

  • только один географический прямоугольник на изображение
  • отсутствие встроенной тайлинговой структуры
  • нет автоматического LOD (level of detail)
  • отсутствие встроенной кэш-стратегии как у vector tiles

Для больших наборов данных вместо image-source применяется:

  • raster tiles
  • tile server
  • custom WebGL layers

Поведение при перепроекции

При изменении проекции карты изображение:

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

Это особенно заметно при использовании наклонённого вида (pitch > 0), где верхняя часть изображения визуально «сжимается».

Интерактивное наложение и взаимодействие

Хотя image-layer не имеет встроенных событий, взаимодействие реализуется через:

  • queryRenderedFeatures
  • проверку попадания курсора в bounding box
  • отдельные GeoJSON-слои поверх изображения

Пример проверки попадания:

map.on('click', (e) => {
  const features = map.queryRenderedFeatures(e.point, {
    layers: ['overlay-layer']
  });

  if (features.length) {
    console.log('Клик по изображению');
  }
});

Комбинирование с векторными слоями

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

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

Порядок слоёв определяет читаемость:

  1. base map
  2. image overlay
  3. polygons/lines
  4. labels
Оглавление