Added a query function to get minimum distance and the indices of clo… by plooney · Pull Request #149 · georust/geo-index

plooney · 2025-12-23T13:27:40Z

…sest points

I agree to follow the project's code of conduct.
I added an entry to the project's change log file if knowledge of this change could be valuable to users.
- Usually called CHANGES.md or CHANGELOG.md
- Prefix changelog entries for breaking changes with "BREAKING: "

…sest points

michaelkirk

I'm new to this crate, so don't consider my review as blocking. Probably @kylebarron or someone else more familiar should make the final call.

michaelkirk · 2025-12-29T17:27:13Z

+        let node_size = self.node_size();
+
+        // Use TinyVec to avoid heap allocations
+        let mut stack: TinyVec<[usize; 33]> = TinyVec::new();


Since all pushes/pops happen in 3's maybe it makes more sense to have:

let mut stack: TinVec<[(usize, usize, usize); 11]> = TinyVec::new(); stack.push((0, indices.len() - 1, 0));

Fair. I implemented pushing and popping in 3's to be a relatively literal port of the upstream JS code, such as in https://github.com/mourner/kdbush/blob/92b25eb356852b6cade256f147ada41b1a7e04d2/index.js#L162-L164

michaelkirk · 2025-12-29T17:27:47Z

+
+        // recursively search for items within radius in the kd-sorted arrays
+        while !stack.is_empty() {
+            let axis = stack.pop().unwrap_or(0);


This unwrap_or "should never happen", right?

If you adopt the 3-tuple approach above, I think this could become:

while let Some((axis, right, left)) = stack.pop() { ... }

And you could get rid of the unwrap_or

Looking around I bit, it looks like this was copy/pasted from another method. Actually, a quick scan shows this traversal logic is being used in at least 2 other places. Is it reasonable to abstract the traversal logic from the query logic at this point?

michaelkirk · 2025-12-29T17:32:40Z

+    /// - qy: y value of query point
+    ///
+    /// Returns distance squared and indices of found items
+    fn query(&self, qx: N, qy: N) -> (N, Vec<u32>) {


I have several superficial suggestions, but they are admittedly all subjective matters of taste.

1. naming: query is vague - nearest would be more specific without being overly verbose.

2. Returning distance squared: I see how this could be helpful for performance in some cases, but I'd guess it's surprising. (The current implementation actually seems to already return distance not distance squared so maybe you agree and this was just an out of date doc).

3. Tuple order: I'd expect most people to be more interested in the Vec<u32> than the distance, so I'd flip the order of the return tuple.

So, all together, I'm suggesting something like this:

/// Returns indices of found items and their distance from the query point. fn nearest(&self, qx: N, qy: N) -> (Vec<u32>, N) { (nearest_distance_squared.0, nearest_distance_squared.1.sqrt()) } /// Optional: if you think it's worth exposing the squared distance - give it a more obvious name: /// /// Returns indices of found items and their distance squared from the query point. fn nearest_distance_squared(&self, qx: N, qy: N) -> (Vec<u32>, N) { ... }

On the naming. I have been using KDTrees in Scipy and I have mimicked the naming there

https://scikit-learn.org/stable/modules/generated/sklearn.neighbors.KDTree.html#sklearn.neighbors.KDTree.query

michaelkirk · 2025-12-29T17:39:31Z

+    /// - qy: y value of query point
+    ///
+    /// Returns distance squared and indices of found items
+    fn query(&self, qx: N, qy: N) -> (N, Vec<u32>) {


Why is this u32? Aren't these array indices? I think if you use usize some of the unwrap's below can go away.

Ah, my bad. I see that indices are either u16 or u32, so converting to u32 should never fail. For future cleanup (not in this PR), maybe Indices should have some kind of infallible method like get_u32 so we don't have so many unwraps in the calling code.

Yeah, indices were defined as u32 to match the upstream JavaScript implementation in https://github.com/mourner/kdbush

michaelkirk · 2025-12-29T17:39:54Z

+                stack.push(1 - axis);
+            }
+        }
+        let d = min_val.sqrt().unwrap();


Why is it safe to unwrap here? When is this None?

It would be None if min_val is < 0.0. That should not be the case since it is squared distance.

kylebarron · 2026-01-07T01:31:09Z

I'd like to find time to review this, but I'm pretty swamped right now and just got selected to serve on a 3-week jury trial, so my time will likely be very limited for the rest of January.

plooney · 2026-01-07T09:29:30Z

@kylebarron No problem. I have some other work I need to progress and will come back to this when you have more time..

Kontinuation

We'd better add some tests for the newly added query function.

Kontinuation · 2026-01-22T17:20:38Z

+            // queue search in halves that intersect the query
+            let lte = if axis == 0 {
+                qx - min_val <= x
+            } else {
+                qy - min_val <= y
+            };
+            if lte {
+                stack.push(left);
+                stack.push(m - 1);
+                stack.push(1 - axis);
+            }
+
+            let gte = if axis == 0 {
+                qx + min_val >= x
+            } else {
+                qy + min_val >= y
+            };


If I understand it correctly, min_val is the minimum-so-far squared distance. Will it cause problems to add a coordinate with a squared distance? This may lead to incorrect pruning.

zhangfengcdt · 2026-01-22T18:34:14Z

+
+            // queue search in halves that intersect the query
+            let lte = if axis == 0 {
+                qx - min_val <= x


Should we use sqrt(min_val) for correct pruning? For distances < 1.0, this bug can cause the algorithm to miss valid results.

zhangfengcdt · 2026-01-22T18:35:01Z

+    /// - qx: x value of query point
+    /// - qy: y value of query point
+    ///
+    /// Returns distance squared and indices of found items


Looks like the actual return value is min_val.sqrt() (the actual distance)?

Yes the documentation I wrote is incorrect. Should be distance

Added a query function to get minimum distance and the indices of clo…

9646162

…sest points

michaelkirk reviewed Dec 29, 2025

View reviewed changes

Kontinuation reviewed Jan 22, 2026

View reviewed changes

zhangfengcdt reviewed Jan 22, 2026

View reviewed changes

Conversation

plooney commented Dec 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

michaelkirk left a comment

Choose a reason for hiding this comment

Uh oh!

michaelkirk Dec 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

michaelkirk Dec 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

michaelkirk Dec 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kylebarron commented Jan 7, 2026

Uh oh!

plooney commented Jan 7, 2026

Uh oh!

Kontinuation left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

plooney commented Dec 23, 2025 •

edited

Loading

michaelkirk Dec 29, 2025 •

edited

Loading

michaelkirk Dec 29, 2025 •

edited

Loading

michaelkirk Dec 29, 2025 •

edited

Loading