Crate supercluster

Supercluster

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

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. This crate was initially inspired by Mapbox’s supercluster blog post.

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 supercluster::{ CoordinateSystem, 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);

    // Create a FeatureCollection Object
    // [GeoJSON Format Specification § 5](https://tools.ietf.org/html/rfc7946#section-5)
    let features = Supercluster::feature_builder()
        .add_point(vec![0.0, 0.0])
        .build();

    // Load a FeatureCollection Object into the Supercluster instance
    let index = cluster.load(features)?;

    if let Err(err) = index.get_tile(0, 0.0, 0.0) {
       println!("Error: {}", err);
    }

    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

🎈 Thanks for your help improving the project! We are so happy to have you!

We have a contributing guide to help you get involved in the project.

Sponsors

Re-exports

pub use builder::*;

pub use error::*;

pub use kdbush::*;

pub use range::*;

pub use supercluster::*;

Modules

builder

Supercluster builder module. This module contains the builder pattern for the supercluster configuration settings.

error

Supercluster error module. This module contains the error types for the supercluster crate.

kdbush

KDBush module. This module contains the KDBush implementation for the supercluster crate.

range

Range module. This module contains the range implementation for the supercluster crate.

supercluster

Supercluster module. This module contains the supercluster implementation for the supercluster crate.