Работа с pitch

В контексте MapLibre GL JS параметр pitch определяет наклон карты относительно горизонтальной плоскости. Он задаёт угол наклона камеры, позволяя переходить от классического «плоского» вида сверху к перспективной 3D-проекции, где объекты приобретают глубину и визуальную высоту.

Pitch измеряется в градусах и обычно находится в диапазоне от 0 до 85.

  • 0° — полностью плоская карта (вид сверху).
  • 85° — почти горизонтальный обзор с минимальным углом к поверхности карты.

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

Камера и роль pitch в системе координат

MapLibre GL JS использует камеру как абстракцию наблюдателя в 3D-пространстве. Камера определяется тремя основными параметрами:

  • center — координата центра обзора
  • zoom — масштаб
  • pitch — наклон
  • bearing — поворот относительно севера

Pitch управляет вращением камеры вокруг оси X в системе координат карты. При этом центр карты остаётся фиксированной точкой, вокруг которой происходит наклон.

С математической точки зрения pitch влияет на матрицу проекции, изменяя преобразование из координат мира (longitude/latitude) в экранные координаты.

Базовая установка pitch

Pitch задаётся через параметры карты при инициализации:

const map = new maplibregl.Map({
  container: 'map',
  style: 'https://demotiles.maplibre.org/style.json',
  center: [37.6173, 55.7558],
  zoom: 12,
  pitch: 45
});

В этом случае карта сразу загружается с наклоном 45°.

Если параметр не указан, используется значение по умолчанию — 0°.

Изменение pitch в процессе работы

setPitch

Основной метод управления наклоном:

map.setPitch(60);

Метод принимает угол в градусах и мгновенно изменяет положение камеры.

Также поддерживается анимация:

map.setPitch(60, {
  duration: 2000,
  easing: (t) => t * (2 - t)
});

При анимации происходит плавное интерполирование угла pitch с текущего значения до целевого.

getPitch

Получение текущего значения:

const currentPitch = map.getPitch();

Возвращает число в градусах, отражающее текущее состояние камеры.

setMaxPitch и ограничения

MapLibre GL JS позволяет ограничивать максимальный наклон:

map.setMaxPitch(70);

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

Pitch и взаимодействие пользователя

Pitch может изменяться через пользовательские жесты:

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

Эти взаимодействия контролируются параметрами:

map.dragRotate.enable();
map.touchZoomRotate.enable();

При включённом вращении камеры pitch становится частью интерактивного управления перспективой.

Анимация pitch и плавные переходы

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

map.flyTo({
  center: [37.6173, 55.7558],
  zoom: 14,
  pitch: 65,
  bearing: -20,
  speed: 1.2
});

В этом случае pitch становится частью общей анимации камеры, где одновременно изменяются несколько параметров.

Внутренне MapLibre использует интерполяцию значений, чтобы обеспечить плавность перехода без резких скачков перспективы.

Влияние pitch на отрисовку слоёв

Pitch напрямую влияет на визуализацию следующих типов слоёв:

Fill-extrusion слои

Наиболее выраженный эффект pitch наблюдается при использовании 3D-экструзии зданий:

{
  "id": "buildings",
  "type": "fill-extrusion",
  "paint": {
    "fill-extrusion-height": ["get", "height"],
    "fill-extrusion-base": 0,
    "fill-extrusion-opacity": 0.8
  }
}

При увеличении pitch здания приобретают объём и читаемую высоту.

Symbol слои

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

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

Line слои

Линии дорог и маршрутов при наклоне визуально расходятся в перспективе, создавая эффект глубины. Это особенно заметно при высоком zoom.

Pitch и производительность

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

  • активируется 3D-рендеринг слоёв
  • увеличивается количество пересчётов матрицы камеры
  • усложняется отрисовка символов в перспективе

На слабых устройствах высокие значения pitch в сочетании с большим количеством 3D-слоёв могут снижать FPS.

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

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

  • при pitch = 0 отключается перспективное искажение
  • при максимальных значениях возможна частичная потеря видимости объектов за пределами горизонта
  • некоторые стили карты могут не поддерживать полноценную 3D-проекцию
  • поведение зависит от projection matrix и настроек render mode

Также pitch тесно связан с fog, terrain и другими параметрами визуализации, влияющими на восприятие глубины.

Взаимодействие pitch с terrain

При использовании рельефа (terrain) pitch становится ключевым параметром визуализации:

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

Комбинация terrain + pitch формирует полноценную псевдо-3D сцену, где карта перестаёт быть плоской поверхностью.

Синхронизация pitch с другими параметрами камеры

Pitch редко используется изолированно. Наиболее типичные комбинации:

Pitch + Zoom

Увеличение zoom при высоком pitch усиливает эффект глубины:

  • объекты становятся крупнее
  • перспектива становится более выраженной
  • уменьшается обзорность

Pitch + Bearing

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

map.setBearing(30);
map.setPitch(50);

Использование pitch в аналитических и навигационных интерфейсах

Pitch применяется для изменения восприятия карты в зависимости от сценария:

  • навигационные системы используют небольшой наклон (20–40°) для улучшения ориентации
  • аналитические панели применяют нулевой pitch для точности восприятия данных
  • визуализация городской застройки использует высокий pitch (60–80°) для демонстрации плотности объектов

Изменение pitch часто связано с переключением режимов интерфейса.

Управление pitch через события карты

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

map.on('pitch', () => {
  console.log(map.getPitch());
});

Также доступны более общие события:

  • move
  • rotate
  • zoom

Pitch обычно обрабатывается в рамках move, так как изменение наклона считается частью трансформации камеры.

Математическая интерпретация pitch

Внутри WebGL-рендеринга pitch влияет на матрицу вида (view matrix). Наклон реализуется через вращение вокруг оси X:

  • применяется тригонометрическое преобразование координат
  • изменяется положение горизонта
  • корректируется перспектива глубины (depth buffer)

Это обеспечивает согласованное отображение всех слоёв в единой 3D-сцене.

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

При высоких значениях pitch возникают характерные особенности:

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

Эти эффекты не являются ошибками, а следствием перспективной проекции камеры.

Оглавление