Supercluster

A very fast Rust crate for geospatial point clustering.

This crate is deeply inspired by Mapbox's supercluster JS package and blog post.

Reference implementation

Features

load(points): Loads an array of GeoJSON Feature objects. Each feature's geometry must be a GeoJSON Point.
get_clusters(bbox, zoom): For the given bbox array ([west_lng, south_lat, east_lng, north_lat]) and zoom, returns an array of clusters and points as GeoJSON Feature objects.
get_tile(z, x, y): For a given zoom and x/y coordinates, returns a 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.

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.

Safety

This crate uses #![forbid(unsafe_code)] to ensure everything is implemented in 100% safe Rust.

Documentation

For more in-depth details, please refer to the full documentation.

If you encounter any issues or have questions that are not addressed in the documentation, feel free to submit an issue.

Usage

Run the following Cargo command in your project directory:

cargo add supercluster

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");

  ...
}

Contributing

Build:

cargo build

Test:

cargo test

Run clippy:

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

Run lint:

cargo fmt

Generate documentation in HTML format:

cargo doc --open

AristideVB/supercluster-rust