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

Safety

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

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

Sponsors