VideoSource

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

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

  • отображать трансляции с камер наблюдения в контексте карты;
  • визуализировать динамические процессы (погода, движение объектов, строительные работы);
  • накладывать видеослои поверх спутниковых или векторных подложек.

Ключевая особенность заключается в том, что видео интерпретируется как геопривязанная текстура, а не как медиа-элемент DOM.

Структура VideoSource

Источник типа video задаётся через map.addSource и требует указания:

  • массива URL-адресов видео;
  • координат четырёх углов, задающих привязку к карте.

Базовая структура:

map.addSource('drone-video', {
  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]
  ]
});

Параметры VideoSource

type

Всегда фиксированное значение:

type: 'video'

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

urls

Массив строк с путями к видеофайлам. Используется несколько форматов для кроссбраузерной совместимости (MP4, WebM).

urls: ['video.mp4', 'video.webm']

coordinates

Четыре пары координат в формате [longitude, latitude], задающие углы видеоплоскости:

coordinates: [
  topLeft,
  topRight,
  bottomRight,
  bottomLeft
]

Порядок критичен: он определяет корректное наложение текстуры на карту.

Привязка видео к геометрии

VideoSource всегда интерпретируется как накладываемый прямоугольник, деформируемый под географическую проекцию. Каждая координата соответствует углу видеоповерхности:

  • первая точка — верхний левый угол;
  • вторая — верхний правый;
  • третья — нижний правый;
  • четвёртая — нижний левый.

При изменении масштаба карты видеотекстура трансформируется вместе с проекцией, сохраняя географическую привязку.

Использование слоя для отображения VideoSource

VideoSource не отображается напрямую. Для визуализации используется слой типа raster:

map.addLayer({
  id: 'video-layer',
  type: 'raster',
  source: 'drone-video'
});

Такой слой интерпретирует видео как растровую текстуру и отображает его поверх базовой карты.

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

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

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

source.setCoordinates([
  [-122.52, 37.56],
  [-122.51, 37.56],
  [-122.51, 37.55],
  [-122.52, 37.55]
]);

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

Синхронизация воспроизведения

VideoSource опирается на HTML5 Video API. Управление воспроизведением осуществляется через стандартные методы:

  • play();
  • pause();
  • currentTime;
  • loop;
  • muted.

Пример синхронизации:

const video = document.querySelector('video');

video.play();
video.loop = true;
video.muted = true;

Mapbox GL JS использует этот элемент как источник кадров, обновляя текстуру в рендер-цикле WebGL.

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

В некоторых сценариях требуется полная замена видео:

map.getSource('drone-video').setVideoUrls([
  'new-video.mp4',
  'new-video.webm'
]);

Это позволяет переключать потоки без пересоздания слоя.

Геометрические особенности и проекции

VideoSource работает в координатной системе WGS84. При этом видео проецируется в Web Mercator вместе с картой, что приводит к визуальной деформации при больших масштабах.

Особенности поведения:

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

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

Наложение дрон-видео

Видео с беспилотника привязывается к области съёмки и синхронизируется с картой местности.

Видеонаблюдение

Камеры фиксированной установки отображают видеопоток в географическом контексте.

Аналитика движения

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

Ограничения VideoSource

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

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

VideoSource работает через WebGL-текстуру, обновляемую на каждом кадре видео. Это создаёт нагрузку на GPU, особенно при:

  • 4K видео;
  • нескольких видеослоях одновременно;
  • высокой частоте кадров.

Оптимизация достигается через:

  • ограничение разрешения видео;
  • использование одного активного слоя;
  • отключение невидимых источников через visibility.

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

При зуме карта перерасчитывает матрицу преобразования, и видеотекстура:

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

Интеграция с событиями карты

VideoSource может быть частью интерактивных сценариев:

map.on('click', 'video-layer', (e) => {
  console.log('Клик по видеообласти', e.lngLat);
});

События работают аналогично другим слоям Mapbox GL JS, так как видео рассматривается как часть рендер-дерева карты.

Управление жизненным циклом источника

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

map.removeLayer('video-layer');
map.removeSource('drone-video');

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

Оглавление