Supercluster

A high-performance Rust crate for geospatial and non-geospatial point clustering.

This crate was initially inspired by Mapbox's supercluster blog post.

Reference implementation

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

To use the supercluster crate in your project, add it to your Cargo.toml:

[dependencies]
supercluster = "x.x.x"

Below is an example of how to create and run a supercluster using the crate. This example demonstrates how to build supercluster options, create a new supercluster, and get a tile. For more detailed information and advanced usage, please refer to the full documentation.

use geojson::FeatureCollection;
use supercluster::{ CoordinateSystem, Options, Supercluster, SuperclusterError };

fn main() -> Result<(), SuperclusterError> {
    // Set the configuration settings
    let options = Supercluster::builder()
        .radius(40.0)
        .extent(512.0)
        .min_points(2)
        .max_zoom(16)
        .coordinate_system(CoordinateSystem::LatLng)
        .build();

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

    // Load a FeatureCollection Object into the Supercluster instance
    // [GeoJSON Format Specification § 5](https://tools.ietf.org/html/rfc7946#section-5)
    let feature_collection = vec![];
    let index = cluster.load(feature_collection);

    // Get a tile
    let tile = index.get_tile(0, 0.0, 0.0)?;

    Ok(())
}

Features

• load(points): Loads a FeatureCollection Object. Each feature should be a Feature Object.

• 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 Feature Object objects.

• get_tile(z, x, y): For a given zoom and x/y coordinates, returns a FeatureCollection Object.

• 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.

Safety

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

Contributing

Contributions from the community are always welcome! Here are some ways you can contribute:

Reporting Bugs

If you encounter any bugs, please submit an issue with detailed information about the problem and steps to reproduce it.

Feature Requests

If you have ideas for new features, feel free to submit an issue with a detailed description of the feature and its potential use cases.

Build

To build the project, run:

cargo build

Test

To run the tests, use:

cargo test

Lint

Run clippy to lint the code:

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

Format

Run rustfmt to format the code:

cargo fmt

Documentation

Generate documentation in HTML format:

cargo doc --open

Sponsors