Cluster radius

Механизм кластеризации в Mapbox GL JS основан на объединении точек в группы (clusters) в зависимости от их взаимного расстояния на экране. Ключевым параметром, определяющим поведение этого процесса, выступает clusterRadius. Он задаёт радиус в пикселях, внутри которого точки считаются принадлежащими одному кластеру.

Принцип работы кластеризации

При включении кластеризации в источнике данных GeoJSON движок выполняет агрегацию точек на стороне клиента. Каждая точка анализируется в пределах текущего viewport и группируется с соседними точками, если расстояние между ними меньше заданного радиуса.

Основная конфигурация источника данных:

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

Здесь clusterRadius: 50 означает, что все точки, находящиеся ближе 50 пикселей друг к другу на текущем масштабе, объединяются в один кластер.

Единицы измерения и особенности интерпретации

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

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

Таким образом, кластеризация является экранно-ориентированной, а не геодезически точной.

Влияние clusterRadius на плотность кластеров

Изменение радиуса напрямую влияет на визуальную структуру данных:

  • Малые значения (10–30 px) Формируют большое количество мелких кластеров. Подходят для детализированных карт с высокой точностью распределения точек.

  • Средние значения (30–60 px) Баланс между детализацией и читаемостью. Часто используются как дефолтное решение.

  • Большие значения (60–100+ px) Сильно агрегируют данные, уменьшая количество кластеров. Подходят для глобальных обзоров и сильно плотных датасетов.

Связь clusterRadius и clusterMaxZoom

Кластеризация управляется не только радиусом, но и максимальным уровнем масштаба:

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

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

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

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

При высоком clusterRadius и низком clusterMaxZoom кластеры будут крупными, но быстро распадаться при увеличении масштаба.

Алгоритмическая модель кластеризации

Mapbox GL JS использует пространственное разбиение данных и оптимизированные структуры поиска соседей. Внутри реализована приближённая кластеризация, основанная на сеточном разбиении (grid-based clustering).

Каждая точка попадает в ячейку сетки, размер которой зависит от clusterRadius. Затем соседние ячейки объединяются при необходимости.

Упрощённо процесс выглядит следующим образом:

  1. Перевод географических координат в пиксели текущего зума
  2. Разбиение плоскости на сетку с шагом clusterRadius
  3. Группировка точек внутри одной или соседних ячеек
  4. Рекурсивное объединение кластеров

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

clusterRadius влияет не только на визуальный результат, но и на вычислительную нагрузку.

Меньший радиус:

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

Больший радиус:

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

При больших датасетах (десятки тысяч точек) увеличение радиуса часто улучшает производительность, поскольку уменьшает количество отображаемых символов и слоёв.

Динамическое изменение clusterRadius

Радиус может изменяться в зависимости от уровня масштаба или внешних условий интерфейса.

Пример динамической логики:

function getClusterRadius(zoom) {
  if (zoom < 5) return 80;
  if (zoom < 8) return 60;
  if (zoom < 12) return 40;
  return 20;
}

map.on('zoom', () => {
  const zoom = map.getZoom();

  map.getSource('points').setClusterOptions({
    clusterRadius: getClusterRadius(zoom)
  });
});

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

Влияние распределения данных

Эффективность clusterRadius зависит от плотности исходных данных:

  • Равномерное распределение точек приводит к стабильным кластерам
  • Сильно скошенные распределения создают “сверхкластеры” в плотных областях
  • Географические аномалии (например, города) требуют меньшего радиуса для сохранения детализации

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

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

Кластеры в Mapbox GL JS отображаются через слои circle и symbol, где размер и стиль часто зависят от количества точек внутри кластера.

Пример слоя:

map.addLayer({
  id: 'clusters',
  type: 'circle',
  source: 'points',
  filter: ['has', 'point_count'],
  paint: {
    'circle-radius': [
      'step',
      ['get', 'point_count'],
      20,
      100,
      30,
      750,
      40
    ],
    'circle-color': '#51bbd6'
  }
});

Изменение clusterRadius влияет на распределение point_count, что в свою очередь изменяет визуальную структуру слоя.

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

Некорректный выбор радиуса приводит к типичным проблемам:

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

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

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

В типичных сценариях используются следующие диапазоны:

  • глобальные карты: 60–80 px
  • региональные карты: 40–60 px
  • городские данные: 20–40 px

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

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

Оглавление