При работе с большим количеством точек на карте кластеризация позволяет объединять близко расположенные объекты в группы и отображать их как единый кластер. По мере увеличения масштаба карты кластеры постепенно распадаются на более мелкие группы, а затем на отдельные точки.
Одним из важнейших параметров кластеризации в MapLibre GL JS является
clusterMaxZoom. Этот параметр определяет
максимальный уровень масштабирования, на котором движок продолжает
формировать кластеры.
Понимание принципов работы данного параметра позволяет добиться правильного поведения карты, улучшить производительность и повысить удобство взаимодействия с геоданными.
Параметр задаётся внутри источника GeoJSON:
map.addSource('earthquakes', {
type: 'geojson',
data: 'earthquakes.geojson',
cluster: true,
clusterMaxZoom: 12
});Значение clusterMaxZoom определяет последний уровень
масштаба, на котором выполняется объединение объектов в кластеры.
Например:
clusterMaxZoom: 12Означает следующее:
| Zoom | Поведение |
|---|---|
| 0–12 | Кластеризация активна |
| 13+ | Кластеры больше не создаются |
После превышения указанного уровня каждая точка начинает отображаться самостоятельно.
Если параметр не указан:
map.addSource('places', {
type: 'geojson',
data: data,
cluster: true
});MapLibre использует значение по умолчанию:
clusterMaxZoom: 14То есть кластеризация работает до масштаба 14 включительно.
Практически это означает, что на городском уровне карта может всё ещё отображать группы объектов, а при дальнейшем приближении показывать отдельные точки.
Предположим, карта поддерживает масштабирование до 20:
new maplibregl.Map({
container: 'map',
style: style,
zoom: 5,
maxZoom: 20
});Источник данных:
clusterMaxZoom: 10Тогда поведение будет следующим:
Zoom 5 → крупные кластеры
Zoom 8 → кластеры мельче
Zoom 10 → последние кластеры
Zoom 11 → отдельные точки
Zoom 20 → отдельные точкиВажно понимать, что после достижения порога кластеризация полностью отключается для текущего представления карты.
Рассмотрим источник с большим количеством объектов.
map.addSource('restaurants', {
type: 'geojson',
data: restaurants,
cluster: true,
clusterMaxZoom: 15,
clusterRadius: 50
});Параметры означают:
При увеличении масштаба:
Zoom 5 → большие группы ресторанов
Zoom 10 → средние группы
Zoom 15 → последние группы
Zoom 16 → отдельные рестораныИногда требуется быстро раскрывать кластеры.
Пример:
clusterMaxZoom: 8Такой подход полезен для:
Поведение:
Zoom 0–8 → кластеры
Zoom 9+ → отдельные точкиПреимущества:
Недостатки:
Для очень плотных наборов данных часто используют большие значения.
Например:
clusterMaxZoom: 18Такой вариант подходит для:
Поведение:
Zoom 0–18 → кластеризация
Zoom 19+ → отдельные точкиПреимущества:
Недостатки:
Часто возникает путаница между двумя параметрами:
maxZoomи
clusterMaxZoomЭто совершенно разные настройки.
Определяет максимальный масштаб карты.
maxZoom: 20Пользователь не сможет приблизить карту сильнее.
Определяет максимальный масштаб кластеризации.
clusterMaxZoom: 14После 14 уровня отображаются отдельные объекты.
Пример:
maxZoom: 22
clusterMaxZoom: 12Тогда:
0–12 → кластеры
13–22 → отдельные точкиПараметр максимального масштаба тесно связан с радиусом кластера.
Пример:
clusterRadius: 80,
clusterMaxZoom: 16Большой радиус создаёт крупные группы.
На масштабе 16 кластеры всё ещё будут содержать значительное количество объектов.
Другой пример:
clusterRadius: 20,
clusterMaxZoom: 16Кластеры начнут распадаться значительно раньше.
Поэтому настройка этих параметров обычно выполняется совместно.
До нескольких тысяч объектов:
clusterMaxZoom: 10или
clusterMaxZoom: 12Такси, кафе, магазины:
clusterMaxZoom: 14или
clusterMaxZoom: 15Сотни тысяч объектов:
clusterMaxZoom: 16или
clusterMaxZoom: 17Очень плотные данные:
clusterMaxZoom: 18или
clusterMaxZoom: 19MapLibre предоставляет информацию о кластере через специальные методы.
Например:
map.on('click', 'clusters', (e) => {
const features = map.queryRenderedFeatures(
e.point,
{ layers: ['clusters'] }
);
const clusterId =
features[0].properties.cluster_id;
const source =
map.getSource('sensors');
source.getClusterExpansionZoom(
clusterId,
(err, zoom) => {
if (err) return;
map.easeTo({
center: features[0].geometry.coordinates,
zoom: zoom
});
}
);
});Метод:
getClusterExpansionZoom()возвращает масштаб, на котором выбранный кластер распадётся на более мелкие кластеры либо на отдельные точки.
Этот механизм автоматически учитывает значение
clusterMaxZoom.
Сама кластеризация выполняется эффективно благодаря использованию алгоритмов пространственной индексации.
Однако выбор неправильного значения может влиять на производительность интерфейса.
Слишком низкое значение:
clusterMaxZoom: 6может привести к отображению десятков тысяч объектов одновременно.
Слишком высокое значение:
clusterMaxZoom: 20сохраняет производительность, но может ухудшать удобство анализа данных.
Поэтому необходимо находить баланс между:
Источник данных с объектами недвижимости:
map.addSource('properties', {
type: 'geojson',
data: properties,
cluster: true,
clusterRadius: 60,
clusterMaxZoom: 15
});Слои отображения:
map.addLayer({
id: 'clusters',
type: 'circle',
source: 'properties',
filter: ['has', 'point_count']
});
map.addLayer({
id: 'cluster-count',
type: 'symbol',
source: 'properties',
filter: ['has', 'point_count']
});
map.addLayer({
id: 'unclustered',
type: 'circle',
source: 'properties',
filter: ['!', ['has', 'point_count']]
});Результат работы:
Масштаб 5 → крупные группы объектов
Масштаб 10 → районы и кварталы
Масштаб 15 → небольшие локальные группы
Масштаб 16 → отдельные здания
Масштаб 20 → максимальная детализацияПодобная схема считается одной из наиболее распространённых для карт недвижимости, сервисов доставки, каталогов организаций и городских геоинформационных систем.
При настройке кластеризации полезно учитывать несколько правил:
clusterMaxZoom;14–16;10–12;clusterRadius;Грамотная настройка clusterMaxZoom позволяет добиться
плавного перехода от обзорной карты с компактными кластерами к
детальному представлению отдельных географических объектов без потери
производительности и удобства работы.