CameraOptions

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

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

  • точку, на которую направлен взгляд;
  • расстояние до поверхности (zoom);
  • поворот вокруг вертикальной оси (bearing);
  • наклон относительно поверхности (pitch).

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

CameraOptions как базовая структура состояния

CameraOptions — это набор параметров, описывающих положение камеры в момент времени. Он используется в методах Map, а также при инициализации карты.

Основные поля:

center

Определяет географический центр карты.

center: [lng, lat]
  • longitude и latitude задаются в градусах;
  • является ключевой точкой, вокруг которой строится отображение.

Пример:

map.setCenter([37.6173, 55.7558])

zoom

Определяет масштаб отображения.

  • типично диапазон: от 0 (глобус целиком) до 22+ (детализация зданий);
  • масштаб нелинеен: каждый шаг увеличения примерно удваивает детализацию.
zoom: 10

На низких значениях видны континенты, на высоких — отдельные улицы и здания.

bearing

Определяет поворот карты вокруг вертикальной оси.

  • измеряется в градусах;
  • 0° — север сверху;
  • положительное значение — поворот по часовой стрелке.
bearing: 45

Используется для создания ориентированных визуализаций маршрутов или 3D-сцен.

pitch

Определяет наклон камеры.

  • 0° — строго сверху;
  • до ~60–75° — перспективный вид;
  • используется для визуализации 3D-объектов и высотности.
pitch: 60

Полная структура CameraOptions

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

{
  center: [lng, lat],
  zoom: 12,
  bearing: 0,
  pitch: 0
}

Каждый параметр может быть опущен — в этом случае сохраняется текущее состояние камеры.

CameraOptions при инициализации карты

При создании карты параметры камеры задаются через объект Map:

const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v12',
  center: [30.3141, 59.9386],
  zoom: 9,
  bearing: 0,
  pitch: 0
})

Mapbox предоставляет стили и тайлы, которые интерпретируются движком карты и отображаются в соответствии с параметрами камеры.

Изменение CameraOptions во время работы карты

setCenter

Изменяет только центр, не затрагивая остальные параметры камеры.

map.setCenter([13.4050, 52.5200])

setZoom

Изменяет масштаб.

map.setZoom(14)

setBearing

Поворачивает карту.

map.setBearing(90)

setPitch

Изменяет наклон.

map.setPitch(45)

Плавные переходы камеры

Mapbox GL JS предоставляет анимационные методы, которые интерполируют CameraOptions.

jumpTo

Мгновенное изменение без анимации.

map.jumpTo({
  center: [2.3522, 48.8566],
  zoom: 11
})

easeTo

Плавное изменение с контролем скорости и кривой интерполяции.

map.easeTo({
  center: [2.3522, 48.8566],
  zoom: 12,
  duration: 2000
})

flyTo

Анимация с эффектом полёта через пространство.

map.flyTo({
  center: [151.2093, -33.8688],
  zoom: 13,
  pitch: 45,
  bearing: -17.6,
  speed: 1.2
})

Дополнительные параметры камеры

padding

Позволяет смещать центр визуально внутри контейнера карты.

padding: {
  top: 50,
  bottom: 50,
  left: 200,
  right: 200
}

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

around

Определяет точку, относительно которой происходит масштабирование и вращение.

around: [lng, lat]

Используется для создания эффектов «вращения вокруг объекта».

Внутренние преобразования

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

  • матрицу проекции (projection matrix);
  • матрицу вида (view matrix);
  • матрицу мировых координат.

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

Ограничения и допустимые диапазоны

  • zoom ограничен минимальным и максимальным уровнем стиля;
  • pitch обычно ограничен значениями до ~60–75° для предотвращения искажений;
  • bearing нормализуется в диапазон 0–360°.

Поведение при конфликтующих параметрах

Если одновременно задаются параметры через несколько источников (например, setCenter и easeTo), приоритет определяется последним вызовом метода. Камера всегда имеет единственное активное состояние, обновляемое по очереди через event loop рендера.

Связь CameraOptions с событиями карты

Изменение камеры генерирует события:

  • move
  • moveend
  • zoom
  • pitch
  • rotate

Эти события отражают текущее состояние CameraOptions и позволяют синхронизировать интерфейсы с картой.

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

CameraOptions фактически выступает как сериализуемое состояние карты. Его можно сохранять и восстанавливать:

const state = map.getCameraState()
localStorage.setItem('camera', JSON.stringify(state))

И затем восстанавливать:

map.jumpTo(JSON.parse(localStorage.getItem('camera')))

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

Оглавление