Skip to content

Commit

Permalink
chore: update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@slavik-pastushenko
slavik-pastushenko committed Dec 7, 2023
1 parent 4ecb619 commit a79968a
Show file tree
Hide file tree
Showing 2 changed files with 63 additions and 4 deletions.
48 changes: 44 additions & 4 deletions src/kdbush.rs
View file
Expand Up @@ -27,6 +27,10 @@ impl KDBush {
///
/// - `size_hint`: An estimate of the number of points that will be added to the index.
/// - `node_size`: The maximum number of points in a leaf node of the KD-tree.
///
/// # Returns
///
/// A new `KDBush` instance with the given configuration.
pub fn new(size_hint: usize, node_size: usize) -> Self {
KDBush {
node_size,
Expand Down Expand Up @@ -74,6 +78,7 @@ impl KDBush {
/// - `max_y`: The maximum Y-coordinate (latitude) of the bounding box.
///
/// # Returns
///
/// A vector of point indices that fall within the specified bounding box.
pub fn range(&self, min_x: f64, min_y: f64, max_x: f64, max_y: f64) -> Vec<usize> {
let mut stack = vec![(0, self.ids.len() - 1, 0)];
Expand Down Expand Up @@ -125,6 +130,7 @@ impl KDBush {
/// - `radius`: The radius around the query point.
///
/// # Returns
///
/// A vector of point indices that fall within the specified radius from the query point.
pub fn within(&self, qx: f64, qy: f64, radius: f64) -> Vec<usize> {
let mut stack = vec![(0, self.ids.len() - 1, 0)];
Expand Down Expand Up @@ -271,7 +277,16 @@ impl KDBush {
}
}

/// Return the maximum of two values
/// Return the maximum of two values.
///
/// # Arguments
///
/// - `a`: The first value.
/// - `b`: The second value.
///
/// # Returns
///
/// The maximum of the two values.
fn get_max(a: usize, b: usize) -> usize {
if a > b {
a
Expand All @@ -280,7 +295,16 @@ impl KDBush {
}
}

/// Return the minimum of two values
/// Return the minimum of two values.
///
/// # Arguments
///
/// - `a`: The first value.
/// - `b`: The second value.
///
/// # Returns
///
/// The minimum of the two values.
fn get_min(a: usize, b: usize) -> usize {
if a < b {
a
Expand All @@ -289,15 +313,31 @@ impl KDBush {
}
}

/// Swap the elements at two specified indices in the KD-tree data structures
/// Swap the elements at two specified indices in the KD-tree data structures.
///
/// # Arguments
///
/// - `i`: The index of the first element.
/// - `j`: The index of the second element.
fn swap_item(&mut self, i: usize, j: usize) {
self.ids.swap(i, j);

self.coords.swap(2 * i, 2 * j);
self.coords.swap(2 * i + 1, 2 * j + 1);
}

/// Compute the square of the Euclidean distance between two points in a 2D space
/// Compute the square of the Euclidean distance between two points in a 2D space.
///
/// # Arguments
///
/// - `ax`: The x-coordinate of the first point.
/// - `ay`: The y-coordinate of the first point.
/// - `bx`: The x-coordinate of the second point.
/// - `by`: The y-coordinate of the second point.
///
/// # Returns
///
/// The square of the Euclidean distance between the two points.
fn sq_dist(ax: f64, ay: f64, bx: f64, by: f64) -> f64 {
let dx = ax - bx;
let dy = ay - by;
Expand Down
19 changes: 19 additions & 0 deletions src/lib.rs
View file
Expand Up @@ -124,6 +124,7 @@ impl Supercluster {
/// - `options`: The configuration options for Supercluster.
///
/// # Returns
///
/// A new `Supercluster` instance with the given configuration.
pub fn new(options: Options) -> Self {
let capacity = options.max_zoom + 1;
Expand All @@ -147,6 +148,7 @@ impl Supercluster {
/// - `points`: A vector of GeoJSON features representing input points to be clustered.
///
/// # Returns
///
/// A mutable reference to the updated `Supercluster` instance.
pub fn load(&mut self, points: Vec<Feature>) -> &mut Self {
let min_zoom = self.options.min_zoom;
Expand Down Expand Up @@ -207,6 +209,7 @@ impl Supercluster {
/// - `zoom`: The zoom level at which to retrieve clusters.
///
/// # Returns
///
/// A vector of GeoJSON features representing the clusters within the specified bounding box and zoom level.
pub fn get_clusters(&self, bbox: [f64; 4], zoom: u8) -> Vec<Feature> {
let mut min_lng = ((((bbox[0] + 180.0) % 360.0) + 360.0) % 360.0) - 180.0;
Expand Down Expand Up @@ -257,6 +260,7 @@ impl Supercluster {
/// - `cluster_id`: The unique identifier of the cluster.
///
/// # Returns
///
/// A `Result` containing a vector of GeoJSON features representing the children of the specified cluster if successful,
/// or an error message if the cluster is not found.
pub fn get_children(&self, cluster_id: usize) -> Result<Vec<Feature>, &'static str> {
Expand Down Expand Up @@ -316,6 +320,7 @@ impl Supercluster {
/// - `offset`: The offset to start retrieving leaf features.
///
/// # Returns
///
/// A vector of GeoJSON features representing the individual leaf features within the cluster.
pub fn get_leaves(&self, cluster_id: usize, limit: usize, offset: usize) -> Vec<Feature> {
let mut leaves = vec![];
Expand All @@ -334,6 +339,7 @@ impl Supercluster {
/// - `y`: The Y coordinate of the tile.
///
/// # Returns
///
/// An optional `Tile` containing a vector of GeoJSON features within the specified tile, or `None` if there are no features.
pub fn get_tile(&self, z: u8, x: f64, y: f64) -> Option<Tile> {
let tree = &self.trees[self.limit_zoom(z)];
Expand Down Expand Up @@ -374,6 +380,7 @@ impl Supercluster {
/// - `cluster_id`: The unique identifier of the cluster.
///
/// # Returns
///
/// The zoom level at which the cluster expands.
pub fn get_cluster_expansion_zoom(&self, mut cluster_id: usize) -> usize {
let mut expansion_zoom = self.get_origin_zoom(cluster_id) - 1;
Expand Down Expand Up @@ -412,6 +419,7 @@ impl Supercluster {
/// - `skipped`: The current count of skipped leaves, used for tracking the progress.
///
/// # Returns
///
/// The updated count of skipped leaves after processing the current cluster.
fn append_leaves(
&self,
Expand Down Expand Up @@ -462,6 +470,7 @@ impl Supercluster {
/// - `data`: A vector of flat numeric arrays representing point data for the KD-tree.
///
/// # Returns
///
/// A `KDBush` instance with the specified data.
fn create_tree(&mut self, data: Vec<f64>) -> KDBush {
let mut tree = KDBush::new(data.len() / self.stride, self.options.node_size);
Expand Down Expand Up @@ -545,6 +554,7 @@ impl Supercluster {
/// - `zoom`: The initial zoom level.
///
/// # Returns
///
/// The effective zoom level considering the configured minimum and maximum zoom levels.
fn limit_zoom(&self, zoom: u8) -> usize {
zoom.max(self.options.min_zoom)
Expand All @@ -559,6 +569,7 @@ impl Supercluster {
/// - `zoom`: The zoom level at which clustering is performed.
///
/// # Returns
///
/// A tuple of two vectors: the first one contains updated data arrays for the current zoom level,
/// and the second one contains data arrays for the next zoom level.
fn cluster(&self, tree: &KDBush, zoom: u8) -> (Vec<f64>, Vec<f64>) {
Expand Down Expand Up @@ -663,6 +674,7 @@ impl Supercluster {
/// - `cluster_id`: The unique identifier of the cluster.
///
/// # Returns
///
/// The index of the point from which the cluster originated.
fn get_origin_id(&self, cluster_id: usize) -> usize {
(cluster_id - self.points.len()) >> 5
Expand All @@ -675,6 +687,7 @@ impl Supercluster {
/// - `cluster_id`: The unique identifier of the cluster.
///
/// # Returns
///
/// The zoom level of the point from which the cluster originated.
fn get_origin_zoom(&self, cluster_id: usize) -> usize {
(cluster_id - self.points.len()) % 32
Expand All @@ -690,6 +703,7 @@ impl Supercluster {
/// - `cluster_props`: A reference to a vector of cluster properties.
///
/// # Returns
///
/// A GeoJSON feature representing a cluster.
fn get_cluster_json(data: &[f64], i: usize, cluster_props: &[Properties]) -> Feature {
Feature {
Expand All @@ -712,6 +726,7 @@ fn get_cluster_json(data: &[f64], i: usize, cluster_props: &[Properties]) -> Fea
/// - `cluster_props`: A reference to a vector of cluster properties.
///
/// # Returns
///
/// Properties for the cluster based on the clustered point data.
fn get_cluster_properties(data: &[f64], i: usize, cluster_props: &[Properties]) -> Properties {
let count = data[i + OFFSET_NUM];
Expand Down Expand Up @@ -744,6 +759,7 @@ fn get_cluster_properties(data: &[f64], i: usize, cluster_props: &[Properties])
/// - `lng`: The longitude value to be converted.
///
/// # Returns
///
/// The converted value in the [0..1] range.
fn lng_x(lng: f64) -> f64 {
lng / 360.0 + 0.5
Expand All @@ -756,6 +772,7 @@ fn lng_x(lng: f64) -> f64 {
/// - `lat`: The latitude value to be converted.
///
/// # Returns
///
/// The converted value in the [0..1] range.
fn lat_y(lat: f64) -> f64 {
let sin = lat.to_radians().sin();
Expand All @@ -777,6 +794,7 @@ fn lat_y(lat: f64) -> f64 {
/// - `x`: The spherical mercator value to be converted.
///
/// # Returns
///
/// The converted longitude value.
fn x_lng(x: f64) -> f64 {
(x - 0.5) * 360.0
Expand All @@ -789,6 +807,7 @@ fn x_lng(x: f64) -> f64 {
/// - `y`: The spherical mercator value to be converted.
///
/// # Returns
///
/// The converted latitude value.
fn y_lat(y: f64) -> f64 {
let y2 = ((180.0 - y * 360.0) * PI) / 180.0;
Expand Down

0 comments on commit a79968a

Please sign in to comment.