supercluster/lib.rs
1#![forbid(unsafe_code)]
2#![warn(missing_docs)]
3#![warn(clippy::missing_docs_in_private_items)]
4
5//! # Supercluster
6//!
7//! A high-performance Rust crate for geospatial and non-geospatial point clustering.
8//!
9//!
10//! ## Reference implementation
11//! [](https://github.com/chargetrip/supercluster-rs/actions/workflows/test.yml)
12//! [](https://docs.rs/supercluster)
13//! [](https://crates.io/crates/supercluster)
14//! 
15//! 
16//! [](https://codecov.io/gh/chargetrip/supercluster-rs)
17//!
18//! 
19//!
20//! ## Documentation
21//!
22//! If you encounter any issues or have questions that are not addressed in the documentation, feel free to [submit an issue](https://github.com/chargetrip/supercluster-rs/issues).
23//! This crate was initially inspired by Mapbox's supercluster [blog post](https://blog.mapbox.com/clustering-millions-of-points-on-a-map-with-supercluster-272046ec5c97).
24//!
25//! ## Usage
26//!
27//! To use the `supercluster` crate in your project, add it to your `Cargo.toml`:
28//!
29//! ```toml
30//! [dependencies]
31//! supercluster = "3.0.0"
32//! ```
33//!
34//! You can also include additional features, such as logging, by specifying them in your `Cargo.toml`:
35//!
36//! ```toml
37//! [dependencies]
38//! supercluster = { version = "3.0.0", features = ["log", "serde", "cluster_metadata"] }
39//! ```
40//!
41//! Below is an example of how to create and run a supercluster using the crate.
42//!
43//! This example demonstrates how to build supercluster options, create a new supercluster, and get a tile.
44//!
45//! ```rust
46//! use supercluster::{ CoordinateSystem, Supercluster, SuperclusterError };
47//!
48//! fn main() -> Result<(), SuperclusterError> {
49//! // Set the configuration settings
50//! let options = Supercluster::builder()
51//! .radius(40.0)
52//! .extent(512.0)
53//! .min_points(2)
54//! .max_zoom(16)
55//! .coordinate_system(CoordinateSystem::LatLng)
56//! .build();
57//!
58//! // Create a new instance with the specified configuration settings
59//! let mut cluster = Supercluster::new(options);
60//!
61//! // Create a a list of features
62//! let features = Supercluster::feature_builder()
63//! .add_point(vec![0.0, 0.0])
64//! .build();
65//!
66//! // Load a list of features into the supercluster
67//! let index = cluster.load(features)?;
68//!
69//! if let Err(err) = index.get_tile(0, 0.0, 0.0) {
70//! println!("Error: {}", err);
71//! }
72//!
73//! Ok(())
74//! }
75//! ```
76//!
77//! ## Benchmarks
78//!
79//! We use the `criterion` crate to benchmark the performance of the `supercluster` crate.
80//!
81//! Benchmarks help us understand the performance characteristics of supercluster and identify areas for optimization.
82//!
83//! We have several benchmark scenarios to test different aspects of supercluster:
84//!
85//! - **Getting a Tile**: Tests the performance of retrieving a tile from the `Supercluster`.
86//! - **Getting Clusters**: Tests the performance of retrieving clusters for a given bounding box and zoom level.
87//! - **Loading a Feature Collection**: Tests the performance of loading a `FeatureCollection` into the `Supercluster`.
88//!
89//! For more detailed benchmark scenarios, please refer to the [`benches`](https://github.com/chargetrip/supercluster-rs/tree/main/benches) directory in the repository.
90//!
91//! ## Safety
92//!
93//! This crate uses `#![forbid(unsafe_code)]` to ensure everything is implemented in 100% safe Rust.
94//!
95//! ## Contributing
96//!
97//! 🎈 Thanks for your help improving the project! We are so happy to have you!
98//!
99//! We have a [contributing guide](https://github.com/chargetrip/supercluster-rs/blob/main/CONTRIBUTING.md) to help you get involved in the project.
100//!
101//! ## Sponsors
102//!
103//! <a href="https://www.chargetrip.com" target="_blank">
104//! <img src="https://dka575ofm4ao0.cloudfront.net/pages-transactional_logos/retina/149188/Chargetrip_Combined_-_Black.png" width="240" alt="Chargetrip">
105//! </a>
106
107/// Supercluster builder module.
108/// This module contains the builder pattern for the supercluster configuration settings.
109pub mod builder;
110
111/// Supercluster error module.
112/// This module contains the error types for the supercluster crate.
113pub mod error;
114
115/// KDBush module.
116/// This module contains the KDBush implementation for the supercluster crate.
117pub mod kdbush;
118
119/// Range module.
120/// This module contains the range implementation for the supercluster crate.
121pub mod range;
122
123/// Supercluster module.
124/// This module contains the supercluster implementation for the supercluster crate.
125pub mod supercluster;
126
127pub use builder::*;
128pub use error::*;
129pub use kdbush::*;
130pub use range::*;
131pub use supercluster::*;