Convert Figma logo to code with AI

mapbox logosupercluster

A very fast geospatial point clustering library for browsers and Node.

2,237
300
2,237
39
View on GitHubView on NPM

Top Related Projects

uber's avatar

h3

5,396

Hexagonal hierarchical geospatial indexing system

Turfjs's avatar

turf

9,805

A modular geospatial engine written in JavaScript and TypeScript

Leaflet's avatar

Leaflet.markercluster

4,091

Marker Clustering plugin for Leaflet

Quick Overview

Supercluster is a fast, lightweight JavaScript library for geospatial point clustering. It's designed for smooth clustering of large datasets on maps, with efficient algorithms for both clustering and unclustering as users zoom in and out.

Pros

  • Extremely fast performance, capable of clustering millions of points in milliseconds
  • Memory-efficient implementation, suitable for use in memory-constrained environments
  • Supports real-time clustering and unclustering as users interact with maps
  • Cross-platform compatibility, works in both browser and Node.js environments

Cons

  • Limited to point data, not suitable for clustering line or polygon features
  • Requires manual integration with mapping libraries, no built-in map rendering
  • May require additional processing for complex data attributes
  • Documentation could be more comprehensive for advanced use cases

Code Examples

Creating a new index and adding points:

const index = new Supercluster({
    radius: 40,
    maxZoom: 16
});

const points = [
    {type: 'Feature', geometry: {type: 'Point', coordinates: [-122.4, 37.8]}, properties: {name: 'San Francisco'}},
    {type: 'Feature', geometry: {type: 'Point', coordinates: [-74.0, 40.7]}, properties: {name: 'New York'}}
];

index.load(points);

Getting clusters for a specific bounding box and zoom level:

const bbox = [-180, -85, 180, 85];
const zoom = 2;

const clusters = index.getClusters(bbox, zoom);
console.log(clusters);

Expanding a cluster:

const clusterId = 123;
const zoom = 2;

const children = index.getChildren(clusterId);
const leaves = index.getLeaves(clusterId, 10, 5);

Getting Started

To use Supercluster in your project:

  1. Install the package:

    npm install supercluster

  2. Import and use in your JavaScript code:

    import Supercluster from 'supercluster';

const index = new Supercluster({radius: 40, maxZoom: 16});
index.load(points);
const clusters = index.getClusters([-180, -85, 180, 85], 2);

  3. Integrate with your mapping library of choice to display the clusters on a map.

Competitor Comparisons

uber logo

h3

5,396

Hexagonal hierarchical geospatial indexing system

Pros of H3

  • Hierarchical hexagonal grid system for global spatial indexing
  • Supports multiple resolutions and precise area calculations
  • Offers bindings for various programming languages

Cons of H3

  • More complex to implement and use compared to Supercluster
  • May have higher computational overhead for certain operations
  • Limited to hexagonal grid shapes, which may not suit all use cases

Code Comparison

H3:

H3Index h3_index = geoToH3(&geo, resolution);
H3Error error = h3ToGeo(h3_index, &geo);
int is_valid = h3IsValid(h3_index);

Supercluster:

const index = new Supercluster({ radius: 40, maxZoom: 16 });
index.load(points);
const clusters = index.getClusters([-180, -85, 180, 85], 2);

H3 uses a C-based API with specific functions for converting between geographic coordinates and H3 indexes, while Supercluster employs a JavaScript-based approach with a more straightforward API for clustering points. H3's code demonstrates low-level operations, whereas Supercluster's code shows high-level clustering functionality.

Turfjs logo

turf

9,805

A modular geospatial engine written in JavaScript and TypeScript

Pros of Turf

  • Offers a wide range of geospatial analysis functions beyond just clustering
  • Supports various geometric operations like buffering, intersections, and unions
  • Can be used for both client-side and server-side processing

Cons of Turf

  • May have slower performance for large datasets compared to Supercluster
  • Requires more setup and configuration for specific use cases
  • Larger library size, which can impact load times in browser environments

Code Comparison

Supercluster:

const index = new Supercluster().load(points);
const clusters = index.getClusters([-180, -85, 180, 85], 2);

Turf:

const points = turf.randomPoint(100, {bbox: [-180, -90, 180, 90]});
const clustered = turf.clustersKmeans(points, {numberOfClusters: 7});

Both libraries offer clustering functionality, but Supercluster is more specialized for this task, while Turf provides a broader set of geospatial tools. Supercluster's API is simpler for basic clustering, whereas Turf requires more setup but offers greater flexibility for complex geospatial operations.

Leaflet logo

Leaflet.markercluster

4,091

Marker Clustering plugin for Leaflet

Pros of Leaflet.markercluster

  • Seamless integration with Leaflet maps
  • Built-in support for custom icons and popups
  • Extensive customization options for cluster appearance and behavior

Cons of Leaflet.markercluster

  • Performance may degrade with very large datasets
  • Limited to use within Leaflet ecosystem
  • Requires more setup and configuration compared to Supercluster

Code Comparison

Leaflet.markercluster:

var markers = L.markerClusterGroup();
markers.addLayer(L.marker([51.5, -0.09]));
markers.addLayer(L.marker([51.51, -0.1]));
map.addLayer(markers);

Supercluster:

var index = new Supercluster({radius: 40, maxZoom: 16});
index.load(points);
var clusters = index.getClusters([-180, -85, 180, 85], map.getZoom());

Leaflet.markercluster is specifically designed for Leaflet maps, offering tight integration and a wide range of customization options. It's ideal for projects already using Leaflet and requiring detailed control over cluster appearance and behavior.

Supercluster, on the other hand, is a more lightweight and flexible solution that can be used with various mapping libraries. It offers better performance for large datasets but requires additional work to integrate with specific map implementations.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

supercluster Simply Awesome Node

A very fast JavaScript library for geospatial point clustering for browsers and Node.

const index = new Supercluster({radius: 40, maxZoom: 16});
index.load(points);

const clusters = index.getClusters([-180, -85, 180, 85], 2);

Clustering 6 million points in Leaflet:

clustering demo on an interactive Leaflet map

Supercluster was built to power clustering in Mapbox GL JS. Read about how it works on the Mapbox blog.

Install

Install using NPM (npm install supercluster) or Yarn (yarn add supercluster), then:

// import as a ES module in Node
import Supercluster from 'supercluster';

// import from a CDN in the browser:
import Supercluster from 'https://esm.run/supercluster';

Or use it with an ordinary script tag in the browser:

<script src="https://unpkg.com/supercluster@8.0.0/dist/supercluster.min.js"></script>

Methods

load(points)

Loads an array of GeoJSON Feature objects. Each feature's geometry must be a GeoJSON Point. Once loaded, index is immutable.

getClusters(bbox, zoom)

For the given bbox array ([westLng, southLat, eastLng, northLat]) and integer zoom, returns an array of clusters and points as GeoJSON Feature objects.

getTile(z, x, y)

For a given zoom and x/y coordinates, returns a geojson-vt-compatible JSON tile object with cluster/point features.

getChildren(clusterId)

Returns the children of a cluster (on the next zoom level) given its id (cluster_id value from feature properties).

getLeaves(clusterId, limit = 10, offset = 0)

Returns all the points of a cluster (given its cluster_id), with pagination support: limit is the number of points to return (set to Infinity for all points), and offset is the amount of points to skip (for pagination).

getClusterExpansionZoom(clusterId)

Returns the zoom on which the cluster expands into several children (useful for "click to zoom" feature) given the cluster's cluster_id.

Options

OptionDefaultDescription
minZoom0Minimum zoom level at which clusters are generated.
maxZoom16Maximum zoom level at which clusters are generated.
minPoints2Minimum number of points to form a cluster.
radius40Cluster radius, in pixels.
extent512(Tiles) Tile extent. Radius is calculated relative to this value.
nodeSize64Size of the KD-tree leaf node. Affects performance.
logfalseWhether timing info should be logged.
generateIdfalseWhether to generate ids for input features in vector tiles.

Property map/reduce options

In addition to the options above, Supercluster supports property aggregation with the following two options:

  • map: a function that returns cluster properties corresponding to a single point.
  • reduce: a reduce function that merges properties of two clusters into one.

Example of setting up a sum cluster property that accumulates the sum of myValue property values:

const index = new Supercluster({
    map: (props) => ({sum: props.myValue}),
    reduce: (accumulated, props) => { accumulated.sum += props.sum; }
});

The map/reduce options must satisfy these conditions to work correctly:

  • map must return a new object, not existing properties of a point, otherwise it will get overwritten.
  • reduce must not mutate the second argument (props).

TypeScript

Install @types/supercluster for the TypeScript type definitions:

npm install @types/supercluster --save-dev

Developing Supercluster

npm install       # install dependencies
npm run build     # generate dist/supercluster.js and dist/supercluster.min.js
npm test          # run tests

NPM DownloadsLast 30 Days