19 stable releases
1.0.19 | Oct 21, 2024 |
---|---|
1.0.17 | Jul 22, 2024 |
1.0.16 | Feb 6, 2024 |
1.0.15 | Dec 7, 2023 |
1.0.14 | Nov 27, 2023 |
#26 in Geospatial
276 downloads per month
56KB
1K
SLoC
Supercluster
A very fast Rust crate for geospatial point clustering.
This crate is inspired by Mapbox's supercluster blog post.
Reference implementation
Features
-
load(points)
: Loads a FeatureCollection Object. Each feature should be a Feature Object. -
get_clusters(bbox, zoom)
: For the givenbbox
array ([west_lng, south_lat, east_lng, north_lat]
) andzoom
, 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 itscluster_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'scluster_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
use geojson::FeatureCollection;
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 a FeatureCollection Object into the Supercluster instance
// [GeoJSON Format Specification § 5](https://tools.ietf.org/html/rfc7946#section-5)
let feature_collection = FeatureCollection {
bbox: None,
// [GeoJSON Format Specification § 3.2](https://datatracker.ietf.org/doc/html/rfc7946#section-3.2)
features: vec![],
foreign_members: None,
};
let index = cluster.load(feature_collection);
// Retrieve a FeatureCollection Object 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 --no-deps -- -D warnings
Run rustfmt:
cargo fmt
Generate documentation in HTML format:
cargo doc --open
Sponsors
Dependencies
~1.6–2.7MB
~55K SLoC