ShowCollisionBoxes

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

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

Система коллизий в рендеринге символов

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

  • текстовые подписи населённых пунктов
  • номера дорог
  • точки интереса (POI)
  • иконки слоёв symbol

Каждый элемент получает так называемый collision box — ограничивающий прямоугольник, описывающий область, которую элемент занимает на экране с учётом:

  • размера шрифта
  • text-padding
  • icon-padding
  • text-offset
  • icon-anchor
  • поворота карты
  • масштаба и перспективы

Основная цель collision detection

Collision detection предотвращает:

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

Если два элемента пересекаются, один из них скрывается в зависимости от приоритетов слоя.

Назначение ShowCollisionBoxes

Параметр showCollisionBoxes включает визуализацию этих внутренних прямоугольников.

Он используется исключительно в отладочных целях и позволяет:

  • увидеть реальные границы текста и иконок
  • анализировать причины исчезновения подписей
  • оценить плотность размещения слоёв
  • отладить text-allow-overlap и icon-allow-overlap
  • оптимизировать стиль карты

Включение режима ShowCollisionBoxes

В зависимости от версии API Mapbox GL JS активация может выглядеть следующим образом:

map.on('load', () => {
  map.showCollisionBoxes = true;
});

В некоторых конфигурациях используется объектный доступ к debug-флагам:

const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v11'
});

map.showCollisionBoxes = true;

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

map.showTileBoundaries = true;
map.showPadding = true;
map.showCollisionBoxes = true;

Визуальная интерпретация коллизионных прямоугольников

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

  • зелёные зоны — размещённые и видимые символы
  • красные зоны — элементы, отброшенные из-за пересечений
  • контурные блоки — потенциальные области конфликта
  • служебные слои — приоритетные collision layers

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

Взаимосвязь с layout-параметрами слоя symbol

Collision boxes формируются на основе свойств слоя:

text-field

Определяет содержимое текста, влияющее на размер bounding box.

text-size

Увеличивает или уменьшает область коллизии пропорционально размеру шрифта.

text-padding

Добавляет дополнительный буфер вокруг текста:

"text-padding": 2

icon-size и icon-padding

Работают аналогично тексту, но применяются к изображениям:

"icon-padding": 1.5

text-allow-overlap / icon-allow-overlap

Если включены, collision boxes перестают блокировать отображение:

"text-allow-overlap": false,
"icon-allow-overlap": false

Алгоритм формирования collision boxes

Система рендеринга выполняет несколько шагов:

  1. Проекция геометрии

    • координаты переводятся в пиксельное пространство

  2. Расчёт anchor point

    • определяется точка привязки текста/иконки

  3. Формирование bounding box

    • создаётся прямоугольник вокруг символа

  4. Проверка пересечений

    • сравнение с уже размещёнными объектами

  5. Принятие решения

    • отображать или скрыть элемент

Приоритеты и порядок размещения

Collision system учитывает приоритеты:

  • symbol-sort-key
  • порядок слоёв в стиле
  • zoom level
  • важность источника данных

Пример:

"symbol-sort-key": 10

Элементы с более высоким значением получают преимущество при размещении.

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

Анализ исчезающих подписей

Если подписи внезапно пропадают, включение collision boxes позволяет определить:

  • перекрытие другими слоями
  • слишком крупный padding
  • неверный anchor
  • слишком плотный zoom-level

Проверка плотности данных

В городских районах часто возникает перегрузка:

  • множество POI
  • пересечение названий улиц
  • конкуренция между слоями

Collision visualization показывает реальную картину, а не итоговый рендер.

Оптимизация стилей карты

При разработке стиля можно:

  • уменьшить text-padding
  • изменить text-size по zoom
  • перераспределить symbol-sort-key
  • включить кластеризацию источников данных

Взаимодействие с zoom-dependent rendering

Collision boxes динамически пересчитываются при:

  • изменении масштаба
  • вращении карты
  • наклоне (pitch)

На малом zoom уровне:

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

На большом zoom:

  • уменьшается плотность
  • увеличивается детализация

Типичные проблемы, выявляемые через ShowCollisionBoxes

Избыточный padding

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

  • чрезмерному скрытию меток
  • пустым участкам карты

Неправильные anchor settings

Ошибки в:

  • text-anchor
  • icon-anchor

могут смещать collision box относительно реального текста.

Конфликт слоёв

Если несколько symbol layers имеют одинаковый приоритет:

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

Связь с производительностью

Хотя showCollisionBoxes — отладочная функция, она отражает внутреннюю сложность:

  • увеличение числа символов увеличивает cost collision detection
  • сложные стили с множеством слоёв увеличивают нагрузку
  • агрессивные label rules могут ухудшать производительность

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

В базовых стилях:

  • меньше плотность collision boxes
  • более агрессивное скрытие второстепенных меток

В кастомных стилях:

  • collision boxes часто пересекаются
  • требуется ручная настройка приоритетов

Использование совместно с другими debug-флагами

Для полной диагностики часто включаются:

  • tile boundaries — границы тайлов
  • padding visualization — отступы canvas
  • collision boxes — символы и их области

Совместный анализ позволяет понять:

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