Cluster max zoom

Концепция cluster max zoom

Параметр clusterMaxZoom определяет максимальный уровень масштабирования карты, на котором выполняется кластеризация точек в GeoJSON-источнике. При достижении или превышении этого значения кластеризация отключается, и вместо агрегированных кластеров отображаются отдельные точки.

В контексте Mapbox GL JS кластеризация реализуется на уровне источника данных (GeoJSONSource) и тесно связана с алгоритмом разбиения точек на группы. Основная цель — уменьшение визуальной перегрузки и оптимизация производительности при работе с большим количеством объектов.

Механизм работы кластеризации

Кластеризация включается через параметр cluster: true в источнике GeoJSON. Внутри используется алгоритм, основанный на пространственной индексации (в частности, Supercluster, используемый в экосистеме Mapbox).

Основные параметры:

  • cluster: true — включает кластеризацию
  • clusterRadius — радиус объединения точек в пикселях
  • clusterMaxZoom — максимальный zoom, на котором создаются кластеры

Пример конфигурации источника:

map.addSource('points', {
  type: 'geojson',
  data: 'points.geojson',
  cluster: true,
  clusterRadius: 50,
  clusterMaxZoom: 14
});

Поведение clusterMaxZoom

При достижении значения clusterMaxZoom происходит следующее:

  • кластерные точки перестают объединяться;
  • все объекты из источника отображаются как отдельные сущности;
  • кластерные свойства (point_count, cluster_id) больше не генерируются для новых уровней масштабирования;
  • визуальные слои, основанные на cluster: true, перестают обновлять агрегацию.

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

Взаимодействие с алгоритмом кластеризации

Кластеризация в Mapbox GL JS основана на многократном разбиении данных по уровням zoom. На каждом уровне создаётся набор кластеров, которые могут быть рекурсивно разбиты на более мелкие кластеры.

clusterMaxZoom задаёт верхнюю границу этой иерархии.

Упрощённо процесс выглядит так:

  • zoom 0–5: крупные кластеры (региональные)
  • zoom 6–10: средние кластеры (городские)
  • zoom 11–14: мелкие кластеры (районные)
  • zoom ≥ clusterMaxZoom: отдельные точки

Отличие clusterMaxZoom от clusterRadius

Эти параметры часто путаются, но они управляют разными аспектами:

clusterMaxZoom

  • ограничивает глубину кластеризации
  • влияет на уровень детализации
  • определяет момент перехода к “сырым” данным

clusterRadius

  • определяет радиус объединения точек
  • влияет на плотность кластеров
  • работает на всех zoom уровнях до clusterMaxZoom

Таким образом:

  • clusterRadius регулирует как сильно объединять
  • clusterMaxZoom регулирует когда перестать объединять

Практическое поведение на карте

При увеличении масштаба карта проходит несколько стадий отображения:

  1. Низкий zoom

    • видны крупные кластеры
    • количество объектов сильно сжато

  2. Средний zoom

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

  3. Высокий zoom (но ниже clusterMaxZoom)

    • кластеры становятся минимальными
    • сохраняется агрегация

  4. zoom ≥ clusterMaxZoom

    • отображаются только индивидуальные точки
    • кластерные свойства исчезают

Использование в слоях (layers)

Типичная реализация включает три слоя:

  • слой кластеров
  • слой числа объектов внутри кластера
  • слой одиночных точек
map.addLayer({
  id: 'clusters',
  type: 'circle',
  source: 'points',
  filter: ['has', 'point_count'],
  paint: {
    'circle-color': '#51bbd6',
    'circle-radius': 18
  }
});

map.addLayer({
  id: 'cluster-count',
  type: 'symbol',
  source: 'points',
  filter: ['has', 'point_count'],
  layout: {
    'text-field': '{point_count_abbreviated}'
  }
});

map.addLayer({
  id: 'unclustered-point',
  type: 'circle',
  source: 'points',
  filter: ['!', ['has', 'point_count']],
  paint: {
    'circle-color': '#f28cb1',
    'circle-radius': 6
  }
});

На zoom >= clusterMaxZoom слой clusters перестаёт получать данные, удовлетворяющие фильтру point_count.

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

clusterMaxZoom напрямую влияет на баланс нагрузки:

  • слишком высокий clusterMaxZoom

    • больше вычислений на клиенте
    • увеличенная нагрузка на рендеринг
    • потенциальная перегрузка DOM/WebGL при большом числе точек

  • слишком низкий clusterMaxZoom

    • раннее исчезновение кластеров
    • визуальная перегрузка на высоких zoom уровнях
    • ухудшение читаемости карты

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

Edge cases и особенности поведения

1. Переход через clusterMaxZoom

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

  • кластеры исчезают
  • появляются отдельные точки
  • может возникать “скачок плотности”

2. Неоднородные данные

Если точки распределены неравномерно:

  • в одних регионах кластеры исчезают быстрее
  • в других сохраняются до максимального zoom

3. Динамическое обновление данных

При обновлении источника (setData) перерасчёт кластеров происходит заново, и clusterMaxZoom применяется повторно ко всей структуре.

Связь с фильтрацией и стилями

clusterMaxZoom не является визуальным фильтром в стиле слоя — это параметр источника. Однако его поведение может косвенно сочетаться с фильтрами:

  • ['has', 'point_count'] — определяет кластер
  • ['!', ['has', 'point_count']] — одиночная точка

После достижения clusterMaxZoom второй фильтр становится единственным активным.

Архитектурная роль в GeoJSONSource

Внутри GeoJSONSource параметр clusterMaxZoom влияет на:

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

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

Практические паттерны настройки

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

Плотные городские данные

  • clusterRadius: 30–40
  • clusterMaxZoom: 13–15

Региональные данные

  • clusterRadius: 50–80
  • clusterMaxZoom: 10–12

Глобальные наборы точек

  • clusterRadius: 60–100
  • clusterMaxZoom: 8–11

Поведение при отсутствии clusterMaxZoom

Если параметр не задан:

  • используется значение по умолчанию (обычно около 18)
  • кластеризация продолжается почти до максимального zoom
  • одиночные точки появляются только при очень высоком увеличении

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

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

В интерфейсах карт, построенных на Mapbox GL JS, clusterMaxZoom часто используется для:

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

При этом логика UI часто опирается на событие zoomend, где проверяется текущий zoom относительно clusterMaxZoom для переключения режимов отображения.

Оглавление