Icon-allow-overlap

В системе рендеринга символов в Mapbox GL JS ключевую роль играет механизм collision detection — алгоритм, отвечающий за предотвращение наложения иконок и текстовых подписей друг на друга. Параметр icon-allow-overlap является одним из центральных инструментов управления этим поведением в слое типа symbol.

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

Базовая модель коллизий символов

В symbol-слоях каждая иконка и текст рассматриваются как отдельные «кандидаты» на размещение на карте. При рендеринге движок выполняет следующие шаги:

  1. Вычисление экранных координат символа

  2. Определение bounding box (рамки занимаемой области)

  3. Проверка пересечений с уже размещёнными элементами

  4. Принятие решения:

    • разместить элемент
    • скрыть элемент

По умолчанию система стремится минимизировать наложения, сохраняя читаемость карты.

Поведение icon-allow-overlap

Параметр:

layout: {
  "icon-allow-overlap": true | false
}

Значение false (по умолчанию)

  • Иконка подчиняется системе коллизий
  • Может быть скрыта, если пересекается с другой иконкой или текстом
  • Приоритет зависит от icon-priority (если задан)

Результат: более «чистая» карта, но возможна потеря части маркеров.

Значение true

  • Иконка игнорирует проверки пересечений
  • Может накладываться на другие иконки и текст
  • Отображается даже в плотных областях

Результат: максимальная плотность данных, но риск визуального шума.

Взаимодействие с другими параметрами

icon-ignore-placement

"icon-ignore-placement": true
  • Позволяет игнорировать занятое пространство другими символами
  • Отличается от icon-allow-overlap тем, что влияет на поведение других объектов относительно данной иконки

icon-optional

"icon-optional": true

  • Иконка может быть скрыта, если не хватает места

  • В сочетании с icon-allow-overlap создаёт гибридное поведение:

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

text-allow-overlap

"text-allow-overlap": true
  • Аналогичный механизм для текстовых меток
  • Часто используется вместе с icon-allow-overlap для полного отключения коллизий в слое

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

При конфликте нескольких символов движок учитывает:

  • icon-priority
  • порядок слоёв (z-order)
  • видимость в текущем зуме
  • collision box size
  • настройки overlap

При icon-allow-overlap: true иконка:

  • фактически «выпадает» из системы конкуренции за место
  • но всё ещё участвует в отрисовке и кликах

Пример конфигурации слоя

map.addLayer({
  id: "points",
  type: "symbol",
  source: "places",
  layout: {
    "icon-image": "marker-15",
    "icon-size": 1,
    "icon-allow-overlap": true
  }
});

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

Сценарии использования

1. Картографическая визуализация высокой плотности

Используется при отображении:

  • GPS-треков
  • событий в реальном времени
  • точек сенсорных данных

Задача: показать максимум информации, даже ценой перегрузки.

2. Heatmap-like symbol layers

При замене heatmap на символы:

  • overlap включается для сохранения всех точек
  • важна не читаемость отдельных меток, а факт присутствия

3. Игровые и симуляционные карты

В системах с большим количеством объектов:

  • юниты
  • ресурсы
  • события

пересечения допустимы и часто ожидаемы.

4. Отладочные слои

При разработке:

  • отображение всех объектов без фильтрации
  • диагностика данных
  • проверка корректности источников

Влияние на производительность

Хотя icon-allow-overlap не напрямую увеличивает вычислительную сложность коллизий (так как проверка отключается для конкретных символов), он влияет на:

  • количество одновременно видимых объектов
  • нагрузку на GPU при рендеринге
  • частоту перерисовки при зуме

В плотных слоях может наблюдаться:

  • рост overdraw (перерисовка пикселей)
  • снижение читаемости при слабом контрасте

Поведение при зуме

Символы с включённым overlap:

  • не исчезают при увеличении плотности
  • сохраняют стабильное положение
  • не «отталкиваются» друг от друга

Это может приводить к эффекту:

  • визуального «сгущения» объектов на низких зумах
  • постепенного расслоения при увеличении масштаба

Взаимодействие с фильтрацией и стилями

icon-allow-overlap не заменяет фильтрацию:

filter: ["==", ["get", "type"], "restaurant"]

Фильтр определяет что рисовать, а overlap — как рисовать.

Также он не влияет на:

  • visibility слоя
  • opacity
  • color mapping
  • sprite selection

Поведение при динамическом обновлении данных

При использовании setData:

  • новые объекты проходят collision pipeline заново
  • overlap позволяет избежать «прыжков» видимости
  • при массовом обновлении сохраняется стабильность отображения

Связанные свойства symbol layer

В экосистеме символов Mapbox GL JS ключевые параметры часто работают в связке:

  • icon-allow-overlap
  • text-allow-overlap
  • icon-ignore-placement
  • text-ignore-placement
  • symbol-placement
  • icon-rotation-alignment
  • icon-padding

Каждое свойство влияет на отдельную часть логики размещения.

Типичные ошибки конфигурации

Полное отключение коллизий без необходимости

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

Результат:

  • перегруженная карта
  • снижение читаемости
  • потеря смысловой структуры

Игнорирование масштаба

Без учета minzoom и maxzoom overlap может привести к:

  • «каше» на низких зумах
  • пустым слоям на высоких

Смешивание приоритетов без icon-priority

При overlap важность объектов теряется, если не задана система приоритетов.

Поведение в контексте Mapbox Sprite

В Mapbox sprites иконки берутся из атласа изображений, и overlap не влияет на выбор изображения, но влияет на:

  • размещение
  • видимость
  • пересечения с другими sprite-элементами

Архитектурная роль в рендеринг-пайплайне

Внутри Mapbox GL JS pipeline:

  1. Tile parsing
  2. Feature evaluation
  3. Layout computation
  4. Collision detection
  5. Symbol placement
  6. Rendering (WebGL)

icon-allow-overlap модифицирует шаг 4–5, фактически сокращая или отключая проверку конфликтов для конкретных элементов.

Итоговая модель поведения параметра

  • Управляет допустимостью наложения иконок
  • Не влияет на геометрию данных
  • Работает на уровне визуального слоя
  • Является локальным переключателем collision logic
  • Используется в сочетании с приоритетами и зум-логикой
Оглавление