Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mapbox/supercluster
A very fast geospatial point clustering library for browsers and Node.
https://github.com/mapbox/supercluster
algorithm clustering computational-geometry javascript maps
Last synced: 20 days ago
JSON representation
A very fast geospatial point clustering library for browsers and Node.
- Host: GitHub
- URL: https://github.com/mapbox/supercluster
- Owner: mapbox
- License: isc
- Created: 2015-12-12T02:13:07.000Z (almost 9 years ago)
- Default Branch: main
- Last Pushed: 2024-03-18T15:22:32.000Z (8 months ago)
- Last Synced: 2024-05-17T17:33:32.665Z (6 months ago)
- Topics: algorithm, clustering, computational-geometry, javascript, maps
- Language: JavaScript
- Homepage:
- Size: 301 KB
- Stars: 2,034
- Watchers: 139
- Forks: 296
- Open Issues: 37
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- made-in-ukraine - SuperCluster
README
# supercluster [](https://github.com/mourner/projects) [](https://github.com/mapbox/supercluster/actions/workflows/node.yml)
A very fast JavaScript library for geospatial point clustering for browsers and Node.
```js
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:
Supercluster was built to power clustering in [Mapbox GL JS](https://www.mapbox.com/mapbox-gljs). Read about how it works [on the Mapbox blog](https://blog.mapbox.com/clustering-millions-of-points-on-a-map-with-supercluster-272046ec5c97).
## Install
Install using NPM (`npm install supercluster`) or Yarn (`yarn add supercluster`), then:
```js
// 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:
```html
```
## Methods
#### `load(points)`
Loads an array of [GeoJSON Feature](https://tools.ietf.org/html/rfc7946#section-3.2) objects. Each feature's `geometry` must be a [GeoJSON Point](https://tools.ietf.org/html/rfc7946#section-3.1.2). 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](https://tools.ietf.org/html/rfc7946#section-3.2) objects.
#### `getTile(z, x, y)`
For a given zoom and x/y coordinates, returns a [geojson-vt](https://github.com/mapbox/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
| Option | Default | Description |
|------------|---------|-------------------------------------------------------------------|
| minZoom | 0 | Minimum zoom level at which clusters are generated. |
| maxZoom | 16 | Maximum zoom level at which clusters are generated. |
| minPoints | 2 | Minimum number of points to form a cluster. |
| radius | 40 | Cluster radius, in pixels. |
| extent | 512 | (Tiles) Tile extent. Radius is calculated relative to this value. |
| nodeSize | 64 | Size of the KD-tree leaf node. Affects performance. |
| log | false | Whether timing info should be logged. |
| generateId | false | Whether 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:
```js
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
```