Supercluster опции

В библиотеке Mapbox GL JS кластеризация точек реализуется через алгоритм Supercluster, обеспечивающий эффективное объединение географических объектов в кластеры на разных уровнях масштабирования. Поведение кластеризации полностью определяется набором параметров, которые передаются при создании экземпляра Supercluster.

radius

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

  • Значение по умолчанию: 40
  • Единица измерения: пиксели

Увеличение radius приводит к более агрессивной кластеризации: больше точек объединяются в меньшие группы. Уменьшение, наоборот, делает кластеры более детализированными.

Практическое влияние:

  • малый radius (10–25): высокая детализация, много кластеров
  • средний radius (30–60): баланс между производительностью и читаемостью
  • большой radius (70+): сильное укрупнение данных

maxZoom

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

  • По умолчанию: 16

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

Ключевые особенности:

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

minZoom

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

  • По умолчанию: 0

Если установлен высокий minZoom, то на малых масштабах точки отображаются отдельно, без объединения.

Используется для:

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

extent

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

  • По умолчанию: 512

Алгоритм Supercluster делит карту на квадратные тайлы, внутри которых происходит группировка точек. Параметр extent определяет разрешение этой сетки.

Влияние:

  • меньший extent → быстрее вычисления, но грубее кластеризация
  • больший extent → более точная кластеризация, но выше нагрузка

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

nodeSize

nodeSize определяет размер узла дерева индекса в байтах.

  • По умолчанию: 64

Этот параметр влияет на структуру R-tree, используемую для хранения точек.

Эффекты изменения:

  • малые значения → меньше памяти, но медленнее поиск
  • большие значения → быстрее обработка, но выше потребление памяти

Рекомендуемые сценарии:

  • мобильные устройства: 32–64
  • серверная агрегация больших наборов данных: 64–128

map и reduce

map

Функция map вызывается для каждого объекта перед кластеризацией. Позволяет преобразовать свойства данных.

Сигнатура:

map: (props) => {
    return {
        category: props.type,
        value: props.value
    };
}

Используется для:

  • нормализации входных данных
  • выделения ключевых полей
  • подготовки данных к агрегации

reduce

Функция reduce выполняется при объединении точек в кластер и отвечает за агрегацию пользовательских свойств.

reduce: (accumulated, props) => {
    accumulated.count += props.count;
    accumulated.totalValue += props.value;
}

Особенности:

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

log

log — отладочный параметр.

  • Тип: boolean
  • По умолчанию: false

При включении выводит информацию о процессе построения кластеров. Используется для диагностики производительности и проверки корректности данных.

Практическая конфигурация Supercluster

Типичная конфигурация для интерактивных карт с большим количеством точек:

import Supercluster from 'supercluster';

const index = new Supercluster({
    radius: 40,
    maxZoom: 16,
    minZoom: 0,
    extent: 512,
    nodeSize: 64,
    map: props => ({
        category: props.category
    }),
    reduce: (acc, props) => {
        acc.count += 1;
    }
});

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

Кластеризация является вычислительно затратной операцией при больших объёмах данных, поэтому параметры напрямую влияют на:

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

Наиболее критичные параметры:

  • nodeSize (баланс памяти и скорости)
  • extent (точность vs производительность)
  • radius (количество кластеров и нагрузка на рендер)

Интеграция с Mapbox GL JS

При использовании кластеров в Mapbox GL JS Supercluster работает скрыто через GeoJSON source с параметром cluster: true.

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

map.addSource('points', {
    type: 'geojson',
    data: geojsonData,
    cluster: true,
    clusterRadius: 40,
    clusterMaxZoom: 16
});

Параметры clusterRadius и clusterMaxZoom являются прямым отражением radius и maxZoom Supercluster, но применяются на уровне API карты.

Особенности поведения при разных масштабах

Кластеризация строится заранее для всех уровней zoom, что позволяет:

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

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

Работа с пользовательскими данными в кластерах

При использовании map и reduce формируется структура кластера, которая затем доступна через свойства объекта:

  • cluster_id
  • point_count
  • пользовательские агрегированные поля

Пример расширенной агрегации:

reduce: (acc, props) => {
    acc.sum += props.price;
    acc.max = Math.max(acc.max, props.price);
}

Такая модель позволяет строить аналитические слои поверх географических данных без дополнительной обработки на стороне UI.

Оглавление