Clustering

Real "where our users are" data has thousands of points. Drawn raw they overlap into a smear and every one of them has to be hit-tested. Clustering fixes both.

createGlobe(canvas, { cluster: true, clusterRadius: 42, markers });

Loading globe…

How it works

Clustering happens in screen space, not geographic space. Each frame, markers are projected, dropped into a grid of clusterRadius pixels, and each occupied cell becomes one bubble at the weighted centroid of its members.

That has two useful consequences:

• It re-balances as you zoom. Zoom in and clusters split apart on their own, because the grid is measured in pixels.
• Off-screen markers do not inflate counts. Map mode culls to the viewport before clustering, so a cluster always describes what you can actually see.

What your callbacks receive

A cluster is a synthetic marker. Cells with a single member pass the original marker through untouched.

{
  cluster: true,
  count: number,     // sum of the members' `count` (or 1 each)
  markers: Marker[], // the originals
  lat: number,       // weighted centroid
  lon: number,
}

createGlobe(canvas, {
  cluster: true,
  onClick: (target) => {
    if (target.cluster) globe.fitTo(bounds(target.markers));
    else openProfile(target);
  },
  tooltip: (target, kind) =>
    kind === "cluster" ? `${target.count} people nearby` : target.city,
});

Choosing a radius

Radius	Feel
24-32	Dense, detailed. Good for zoomed-in regional maps
42 (default)	Balanced
60-80	Sparse and calm. Good for a hero graphic

Bubbles are capped at clusterRadius × 0.46 so neighbouring clusters never overlap, whatever the counts are.

Cost

Measured on a 560 × 216 map with the full country geometry:

Scenario	Per frame
Geometry only	~14 ms
5,000 markers, clustered	~25 ms

Comfortably inside the 30 fps budget. And because the render loop idles when nothing moves, a static clustered map costs nothing after the first paint.

When not to cluster

If you have fewer than a hundred markers and they are spread out, clustering only hides detail. Use heatmap instead when you want density rather than individual points.