Symbol-z-order и symbol-sort-key

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

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

  • symbol-z-order
  • symbol-sort-key

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

Концепция symbol-z-order

Параметр symbol-z-order определяет стратегию упорядочивания символов внутри слоя. Он влияет на то, как Mapbox группирует и сортирует символы до применения индивидуальных правил сортировки.

Поддерживаются два основных режима:

viewport-y

В этом режиме порядок символов зависит от их положения на экране по оси Y.

  • символы, расположенные ниже по карте (ближе к нижней части экрана), рисуются поверх верхних;
  • создаётся эффект естественного «перекрытия» как в перспективе;
  • сортировка происходит динамически при каждом изменении камеры.

Поведение особенно заметно при наклоне карты (pitch > 0), где визуальная иерархия становится более выраженной.

source

В этом режиме порядок определяется исходными данными.

  • символы рисуются в порядке поступления features из source;
  • отсутствует пространственная логика перекрытия;
  • поведение более предсказуемо и стабильно между масштабами и поворотами карты.

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

Ограничения symbol-z-order

Параметр symbol-z-order влияет только на глобальный порядок группировки, но не позволяет управлять отдельными объектами внутри группы с высокой точностью. При сложных наборах данных этого недостаточно, особенно при работе с подписями и перекрывающимися иконками.

Для детального управления используется symbol-sort-key.

symbol-sort-key как инструмент точной сортировки

symbol-sort-key задаётся на уровне каждого feature и определяет приоритет отображения внутри одного слоя symbol.

Принцип работы:

  • чем выше значение symbol-sort-key, тем выше приоритет отрисовки;
  • значения сравниваются между всеми объектами слоя;
  • сортировка применяется после группировки, заданной symbol-z-order.

Базовая логика приоритета

higher symbol-sort-key → rendered on top
lower symbol-sort-key → rendered below

Пример использования symbol-sort-key

map.addLayer({
  id: 'cities',
  type: 'symbol',
  source: 'points',
  layout: {
    'text-field': ['get', 'name'],
    'symbol-sort-key': ['get', 'priority']
  }
});

В этом случае каждый объект должен содержать поле priority:

{
  "type": "Feature",
  "properties": {
    "name": "Almaty",
    "priority": 10
  },
  "geometry": {
    "type": "Point",
    "coordinates": [76.8897, 43.2389]
  }
}

Объекты с большим значением priority будут визуально перекрывать остальные.

Взаимодействие symbol-z-order и symbol-sort-key

Оба параметра работают совместно, но на разных уровнях:

  1. symbol-z-order определяет базовую стратегию группировки:

    • по экранной позиции (viewport-y)
    • или по источнику (source)

  2. symbol-sort-key определяет точный порядок внутри группы

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

1. группировка (symbol-z-order)
2. сортировка внутри группы (symbol-sort-key)

Сценарии viewport-y и проблемы плотных кластеров

При использовании viewport-y возникают характерные эффекты:

  • плотные группы символов начинают «перекрывать» друг друга;
  • нижние элементы визуально вытесняют верхние;
  • подписи могут терять читаемость при наклонённой камере.

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

Использование source для стабильного порядка

Режим source устраняет пространственную зависимость и обеспечивает:

  • стабильную отрисовку между zoom уровнями;
  • предсказуемое поведение при фильтрации;
  • сохранение порядка данных из GeoJSON или vector tiles.

Однако отсутствие пространственной логики делает его менее подходящим для картографических сцен с высокой плотностью объектов.

Комбинирование с layout-выражениями

symbol-sort-key поддерживает expression API Mapbox GL JS, что позволяет вычислять приоритет динамически:

'symbol-sort-key': [
  'case',
  ['==', ['get', 'type'], 'capital'], 100,
  ['==', ['get', 'type'], 'city'], 50,
  1
]

Такой подход позволяет:

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

Влияние на текстовые иконки

При работе с text-field и icon-image порядок отрисовки влияет на:

  • перекрытие подписей;
  • приоритет видимости в плотных областях;
  • конфликт между иконками и текстом.

Особенно важно учитывать:

  • текстовые элементы имеют собственные правила столкновений (text-allow-overlap, text-ignore-placement);
  • symbol-sort-key применяется до стадии collision detection.

Сортировка в условиях collision detection

Mapbox GL JS использует этап разрешения столкновений, где часть символов может быть скрыта.

Порядок влияния следующий:

  1. вычисление symbol-z-order
  2. применение symbol-sort-key
  3. проверка конфликтов (collision detection)
  4. финальный рендеринг

Следствие: объект с высоким symbol-sort-key всё равно может быть скрыт, если нарушает правила столкновений.

Практика управления слоями символов

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

  • viewport-y подходит для сцен с визуальной глубиной;
  • source подходит для строгой детерминированности;
  • symbol-sort-key необходим для бизнес-логики приоритетов;
  • комбинирование обоих механизмов даёт управляемую иерархию.

Поведение при анимации камеры

При изменении параметров камеры (pitch, bearing, zoom) происходит перерасчёт порядка:

  • при viewport-y перестройка выполняется постоянно;
  • при source порядок остаётся неизменным;
  • symbol-sort-key пересчитывается при изменении свойств данных или выражений.

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

Особенности работы с vector tiles

При использовании векторных тайлов:

  • порядок source зависит от порядка тайлов и их внутреннего содержимого;
  • symbol-sort-key применяется локально внутри каждого тайла;
  • глобальная сортировка между тайлами ограничена архитектурой рендерера.

Это создаёт эффект частичной локальности сортировки при масштабировании карты.

Типичные ошибки при настройке порядка символов

  • попытка заменить symbol-sort-key глобальной сортировкой данных на сервере;
  • использование viewport-y в плотных городских слоях без контроля коллизий;
  • отсутствие стабильных значений приоритета в properties;
  • смешивание логических уровней приоритета и визуальных эффектов.

Эти ошибки приводят к непредсказуемому наложению подписей и ухудшению читаемости карты.

Оглавление