Video source

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

Видеоисточник реализуется через тип источника video, который интерпретируется движком рендеринга как растровое изображение, обновляющееся по кадрам. В отличие от статических растровых тайлов, видео не разбивается на сетку и не запрашивается по тайлам — используется единый HTMLVideoElement или массив URL, которые проигрываются непрерывно.

Структура видеоисточника

Видеоисточник описывается через объект источника карты:

  • type: всегда "video"
  • urls: массив адресов видеофайлов (обычно MP4/WebM)
  • coordinates: географические координаты углов прямоугольника

Пример базовой структуры:

map.addSource('video-source', {
  type: 'video',
  urls: [
    'https://example.com/video.mp4',
    'https://example.com/video.webm'
  ],
  coordinates: [
    [-122.51596391201019, 37.56238816766053],
    [-122.51467645168304, 37.56410183312965],
    [-122.51309394836426, 37.563391708549425],
    [-122.51423120498657, 37.56161849366671]
  ]
});

Координаты

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

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

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

Добавление слоя для видео

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

map.addLayer({
  id: 'video-layer',
  type: 'raster',
  source: 'video-source',
  paint: {
    'raster-fade-duration': 0
  }
});

Особенности raster-слоя

Видеоисточник всегда визуализируется через raster-слой, поскольку:

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

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

Помимо передачи URL, возможно использование уже созданного элемента <video>:

const videoElement = document.createElement('video');
videoElement.src = 'https://example.com/video.mp4';
videoElement.autoplay = true;
videoElement.loop = true;
videoElement.muted = true;

map.addSource('video-source', {
  type: 'video',
  video: videoElement,
  coordinates: [
    [-74.0125, 40.7055],
    [-74.0100, 40.7055],
    [-74.0100, 40.7030],
    [-74.0125, 40.7030]
  ]
});

Использование DOM-элемента позволяет:

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

Географическая привязка видео

Видео в Mapbox GL JS не существует в абстрактной плоскости — оно жестко привязывается к координатам карты.

Принцип наложения

Движок интерпретирует видео как текстуру, натянутую на четырёхугольник в географических координатах. При каждом кадре выполняется:

  • преобразование координат в экранное пространство
  • вычисление матрицы трансформации
  • отрисовка текстуры через WebGL

Искажения

При использовании проекций (например, Mercator) возможны:

  • неравномерное растяжение видео
  • перспективные искажения на больших масштабах
  • смещение при наклоне карты

Для минимизации эффектов применяются:

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

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

Видеоисточник может динамически изменять позицию на карте:

const source = map.getSource('video-source');

source.setCoordinates([
  [-122.516, 37.563],
  [-122.514, 37.563],
  [-122.514, 37.561],
  [-122.516, 37.561]
]);

Изменение координат приводит к перерасчёту матрицы трансформации без перезагрузки видео.

Синхронизация видео с картой

Видео может быть синхронизировано с состоянием карты:

  • масштабирование карты → изменение видимой плотности пикселей
  • вращение карты → поворот видеополигона
  • наклон (pitch) → изменение перспективы отображения

Внутри WebGL pipeline видео рассматривается как текстурный слой, привязанный к геометрии, поэтому оно автоматически участвует во всех трансформациях сцены.

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

Видеоисточник имеет ряд ограничений, связанных с рендерингом и декодированием.

Основные ограничения:

  • поддержка зависит от браузерного VideoDecoder
  • высокое разрешение увеличивает нагрузку на GPU
  • несколько видеоисточников одновременно снижают FPS
  • мобильные устройства ограничивают декодирование потоков

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

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

Применение видеоисточников

Видео как источник используется в задачах, где требуется динамическое отображение реального или синтетического движения:

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

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

Видеоисточник можно перезапускать или заменять:

const source = map.getSource('video-source');

source.setCoordinates(newCoordinates);

source.video.src = 'https://example.com/new-video.mp4';
source.video.play();

При смене источника происходит:

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

Работа с прозрачностью и наложением

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

  • символы (symbol layers)
  • линии (line layers)
  • полигоны (fill layers)

Порядок слоёв влияет на итоговое отображение. Видео обычно размещается ниже в стекe слоёв для корректного наложения данных.

Практика геометрической точности

При задании координат важно учитывать:

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

Неправильно заданные координаты приводят к:

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

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

Видеоисточник может реагировать на события:

  • изменение масштаба
  • перемещение центра
  • вращение

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

map.on('move', () => {
  const zoom = map.getZoom();

  if (zoom > 15) {
    map.setLayoutProperty('video-layer', 'visibility', 'visible');
  } else {
    map.setLayoutProperty('video-layer', 'visibility', 'none');
  }
});

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

Внутри Mapbox GL JS видео проходит несколько стадий обработки:

  1. декодирование видеопотока браузером
  2. загрузка кадра в текстуру WebGL
  3. применение матрицы геопривязки
  4. отрисовка в framebuffer сцены
  5. компоновка с остальными слоями

Каждый кадр видео фактически становится динамическим растровым тайлом, обновляющимся в реальном времени.

Совместимость и браузерные особенности

Поддержка видеоисточников зависит от:

  • возможностей WebGL
  • форматов кодеков (H.264, VP8, VP9)
  • политики автозапуска видео
  • ограничений фонового воспроизведения

Некоторые браузеры:

  • блокируют autoplay без muted
  • ограничивают FPS при сворачивании вкладки
  • снижают качество декодирования для экономии энергии

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

Если видео становится недоступным:

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

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

Оглавление