supercluster 1.0.2

A very fast Rust library for geospatial point clustering
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

# Supercluster

## Reference implementation

[![test](https://github.com/chargetrip/supercluster-rust/actions/workflows/test.yml/badge.svg)](https://github.com/chargetrip/supercluster-rust/actions/workflows/test.yml)
[![docs](https://docs.rs/supercluster-cli/badge.svg)](https://docs.rs/supercluster-cli)
[![crate](https://img.shields.io/crates/v/supercluster-cli.svg)](https://crates.io/crates/supercluster-cli)
![Crates.io (recent)](https://img.shields.io/crates/dr/supercluster-cli)
![GitHub](https://img.shields.io/github/license/chargetrip/supercluster-rust)

A very fast Rust library for geospatial point clustering.
This library is deeply inspired by Mapbox's supercluster [JS library](https://www.npmjs.com/package/supercluster) and [blog post](https://www.mapbox.com/blog/supercluster/).

## Features

![Features](https://cloud.githubusercontent.com/assets/25395/11857351/43407b46-a40c-11e5-8662-e99ab1cd2cb7.gif)

- `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).

- `get_clusters(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.
- `get_tile(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.
- `get_children(cluster_id)`: Returns the children of a cluster (on the next zoom level) given its id (`cluster_id` value from feature properties).
- `get_leaves(cluster_id, limit, offset)`: Returns all the points of a cluster (given its `cluster_id`), with pagination support.
- `get_cluster_expansion_zoom(cluster_id)`: Returns the zoom on which the cluster expands into several children (useful for "click to zoom" feature) given the cluster's `cluster_id`.

## Usage

Run the following Cargo command in your project directory:

```bash
cargo add supercluster
```

```rust
extern crate supercluster;

use supercluster::{ Supercluster, Options };

fn main() {
  let options = Options {
      max_zoom: 16,
      min_zoom: 0,
      min_points: 2,
      radius: 40.0,
      node_size: 64,
      extent: 512.0,
  };

  // Create a new instance with the specified configuration settings
  let mut cluster = Supercluster::new(options);

  // Load the input GeoJSON points into the Supercluster instance
  let points = Vec::new(); // your points
  let index = cluster.load(points);

  // Retrieve a vector of features within a tile at the given zoom level and tile coordinates
  let tile = index.get_tile(0, 0.0, 0.0).expect("cannot get a tile");

  ...
}
```

## Options

| Option     | Description                                                       |
|------------|-------------------------------------------------------------------|
| min_zoom   | Minimum zoom level at which clusters are generated.               |
| max_zoom   | Maximum zoom level at which clusters are generated.               |
| min_points | Minimum number of points to form a cluster.                       |
| radius     | Cluster radius, in pixels.                                        |
| extent     | (Tiles) Tile extent. Radius is calculated relative to this value. |
| node_size  | Size of the KD-tree leaf node. Affects performance.               |

## Contributing

- Build:

```bash
cargo build
```

- Test:

```bash
cargo test
```

- Run [clippy](https://github.com/rust-lang/rust-clippy):

```bash
cargo clippy --all-targets --all-features -- -D warnings
```

- Generate documentation in HTML format:

```bash
cargo doc --open
```

## Sponsors

[![Chargetrip logo](https://chargetrip-files.s3.eu-central-1.amazonaws.com/logo-1.png)](https://www.chargetrip.com)