Add K Nearest Neighbor search into STR-Tree #75

jiayuasu · 2017-02-17T18:24:45Z

Add K Nearest Neighbor search into STR-Tree and corresponding unite test case

Signed-off-by: Jia Yu jiayu2@asu.edu

…t case Signed-off-by: Jia Yu <jiayu2@asu.edu>

jnh5y

From a legal/licensing review, two files need license headers.

jnh5y · 2017-02-17T19:02:07Z

...s/core/src/main/java/org/locationtech/jts/index/strtree/BoundablePairDistanceComparator.java

@@ -0,0 +1,53 @@
+package org.locationtech.jts.index.strtree;


New files require a license header.

The form of the header is...

/*

Copyright (c) 2016 Vivid Solutions.

All rights reserved. This program and the accompanying materials

are made available under the terms of the Eclipse Public License v1.0

and Eclipse Distribution License v. 1.0 which accompanies this distribution.

The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html

and the Eclipse Distribution License is available at

http://www.eclipse.org/org/documents/edl-v10.php.
*/

You can list yourself as having copyright.

jnh5y · 2017-02-17T19:02:43Z

modules/core/src/test/java/org/locationtech/jts/index/GeometryDistanceComparator.java

@@ -0,0 +1,58 @@
+package org.locationtech.jts.index;


Ditto about the license headers for this file.

Signed-off-by: Jia Yu <jiayu2@asu.edu>

dr-jts · 2017-02-17T20:41:52Z

modules/core/src/main/java/org/locationtech/jts/index/strtree/STRtree.java

+   * to provide an efficient search. This method implements the KNN algorithm described in the following paper:
+   * Roussopoulos, Nick, Stephen Kelley, and Frédéric Vincent. "Nearest neighbor queries." ACM sigmod record. Vol. 24. No. 2. ACM, 1995.
+   * <p>
+   * The query <tt>object</tt> does <b>not</b> have to be 


Should this say item rather than object?

Well, the query object actually is a Java Object class although it is used as "Item" in ItemBoundable. I am following the same name convention of the original NearestNeighbor() function.

Have a look at http://stackoverflow.com/questions/1667212/how-to-add-reference-to-a-method-parameter-in-javadoc

It should probably say {@code item}, or else maybe {@ link Object} (although I think the former is more specific)

@dr-jts Sure. I understand your point. I will use {@code item} style. I will push them now.

dr-jts · 2017-02-17T20:46:27Z

modules/core/src/main/java/org/locationtech/jts/index/strtree/STRtree.java

+   * @param k the K nearest items in kNearestNeighbour
+   * @return the K nearest items in this tree
+   */
+  public Object[] kNearestNeighbour(Envelope env, Object item, ItemDistance itemDist,int k)


It might be better to call this nearestNeighbour (using overloading), or else nearestNeighbourK (so that the methods are adjacent in the Javadoc)

@jiayuasu What do you think about this suggestion?

@dr-jts I agree with you. I think using overloading is better and easy for understanding. I will make it same with "nearestNeighbour" with an additional parameter "int k".

Signed-off-by: Jia Yu <jiayu2@asu.edu>

dr-jts · 2017-02-17T22:11:38Z

modules/core/src/main/java/org/locationtech/jts/index/strtree/STRtree.java


+    Object[] result = new Object[kNearestNeighbors.size()];


Can this use the Collection.toArray() method?

@dr-jts No, it cannot. The K Nearest Neighbor Priority Queue needs to contain top K ItemBoundable (item+its bounding envelope). We have two options (1) Use the existing way (2) Maintain an additional list of top k nearest neighbors' bounding envelopes all the time. The (1) is OK because normally the K is much smaller than the original dataset. The (2) is time-consuming because we need to update the additional list all the time along with KNN Priority Queue.

Oh, right, I missed that. In that case might be nice to pull this code out into a private static method.

Sure. I will make it into a separate private static method.

dr-jts · 2017-02-17T22:13:19Z

modules/core/src/main/java/org/locationtech/jts/index/strtree/STRtree.java

@@ -373,5 +402,91 @@ public Object nearestNeighbour(Envelope env, Object item, ItemDistance itemDist)
          ((ItemBoundable) minPair.getBoundable(1)).getItem()
      };
  }
+  private Object[] nearestNeighbour(BoundablePair initBndPair, double maxDistance, int k) 


Is it possible that the original NN(1) method can just delegate to this one with k = 1 ? That would be fewer code pathways to maintain. Unless it is slower?

@dr-jts Yes, you are right. If k = 1, the KNN method has the same result and same performance with the original NN(1) method because the maintained KNN Queue just becomes 1NN. However, their APIs are a little bit different. The return of the original NN(1) method is a different array in the following format:[Nearest item, Query Point]. The new NN(K) method returns an array [Nearest item1, item2, item3,...., item k] without including Query Point.

Right, good point!

You know, in that case these method probably really should have different names (since the return data is different). So how about calling the new method nearestNeighbourK ?

@dr-jts Oh, sorry. I missed this: the original NN(1) has an additional API wrapper to return the item only.

public Object nearestNeighbour(Envelope env, Object item, ItemDistance itemDist) { Boundable bnd = new ItemBoundable(env, item); BoundablePair bp = new BoundablePair(this.getRoot(), bnd, itemDist); return nearestNeighbour(bp)[0]; }

So, the NN(1) and the NN(K) have the same return format from the user's perspective. Do you think I still need to use "nearestNeighbourK"?

I guess not. Although @bjornharrtell is going to complain I think! (because JSTS has problems with overloading...)

Great. Let's stick with the overloaded method name then.

OK. So what should I do for this PR now?

I think the code is good. Give us a bit of time to finalize the acceptance.

If you like you could add a function to the TestBuilder to expose the kNN functionality. I added a NN function just now (see last commit to master)

@dr-jts I exposed the kNN functionality following your NN function. Hope it is OK. 😁

Signed-off-by: Jia Yu <jiayu2@asu.edu>

Add STRtree NN function (#76)

Signed-off-by: Jia Yu <jiayu2@asu.edu>

dr-jts · 2017-02-20T17:49:18Z

modules/app/src/main/java/org/locationtech/jtstest/function/SpatialIndexFunctions.java

@@ -117,6 +117,14 @@ public static Geometry strTreeNN(Geometry geoms, Geometry geom)
    return (Geometry) result;
  }

+  public static Geometry[] strTreeNNk(Geometry geoms, Geometry geom)


You can add int k as a parameter to this method, and it will be exposed in the TestBuilder UI

@dr-jts I just try to add "int k" as a parameter. But it seems TestBuilder UI doesn't take more than 2 parameters. It only has two input areas. Not sure about this now.

You can add more parameters. An input box is provided on the Geometry Functions tab.

See this example:

https://github.com/locationtech/jts/blob/master/modules/app/src/main/java/org/locationtech/jtstest/function/CreateShapeFunctions.java#L73

dr-jts · 2017-02-20T17:50:54Z

modules/app/src/main/java/org/locationtech/jtstest/function/SpatialIndexFunctions.java

+    STRtree index = buildSTRtree(geoms);
+    int k = 10;
+    Object[] result = index.nearestNeighbour(geom.getEnvelopeInternal(), geom, new GeometryItemDistance(), k);
+    return (Geometry[]) result;


Not sure TestBuilder handles Geometry[] results. I'll have to check this, or perhaps you can run it and see.

It should be enhanced to automatically convert them to GeometryCollections, but that's not in place yet.

@dr-jts I converted them to GeometryCollection manually because the TestBuilder doesn't take Geometry[].

Signed-off-by: Jia Yu <jiayu2@asu.edu>

dr-jts · 2017-02-20T18:55:03Z

modules/app/src/main/java/org/locationtech/jtstest/function/SpatialIndexFunctions.java

-    return (Geometry[]) result;
+    int k = 2;
+    Object[] knnObjects = index.nearestNeighbour(geom.getEnvelopeInternal(), geom, new GeometryItemDistance(), k);
+    Geometry[] knnGeoms = new Geometry[k];


Follow the pattern here: https://github.com/locationtech/jts/blob/master/modules/app/src/main/java/org/locationtech/jtstest/function/SpatialIndexFunctions.java#L96

@dr-jts OK. It fixed now, 😁

Signed-off-by: Jia Yu <jiayu2@asu.edu>

Add K Nearest Neighbor search into STR-Tree and add corresponding tes…

ba0d8d9

…t case Signed-off-by: Jia Yu <jiayu2@asu.edu>

jnh5y requested changes Feb 17, 2017

View reviewed changes

jiayuasu added 2 commits February 17, 2017 13:13

Add Page Header for new files

32897f7

Update Page Header for two new files

9d7d0ec

Signed-off-by: Jia Yu <jiayu2@asu.edu>

jnh5y approved these changes Feb 17, 2017

View reviewed changes

dr-jts reviewed Feb 17, 2017

View reviewed changes

dr-jts added api type-improvement jts-core labels Feb 17, 2017

Change API usage and modify JavaDoc

2206ff0

Signed-off-by: Jia Yu <jiayu2@asu.edu>

dr-jts reviewed Feb 17, 2017

View reviewed changes

jiayuasu added 3 commits February 17, 2017 16:12

Use a private static method to retrieve KNN items

713cf3e

Signed-off-by: Jia Yu <jiayu2@asu.edu>

Merge pull request #1 from locationtech/master

73b8893

Add STRtree NN function (#76)

Expose KNN to the TestBuilder

01d4b19

Signed-off-by: Jia Yu <jiayu2@asu.edu>

dr-jts reviewed Feb 20, 2017

View reviewed changes

Convert KNN output to GeometryCollection

9811a7c

Signed-off-by: Jia Yu <jiayu2@asu.edu>

dr-jts reviewed Feb 20, 2017

View reviewed changes

Add K as a parameter

22190a1

Signed-off-by: Jia Yu <jiayu2@asu.edu>

dr-jts merged commit 0fce5fc into locationtech:master Feb 21, 2017

bjornharrtell mentioned this pull request Feb 5, 2018

JSTS using Java Generics bjornharrtell/jsts#330

Closed

dr-jts mentioned this pull request Jan 9, 2019

discuss JTSPlus addition #364

Open

brendan-ward mentioned this pull request Mar 15, 2020

PROPOSAL: add STRtree::nearest functions pygeos/pygeos#110

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add K Nearest Neighbor search into STR-Tree #75

Add K Nearest Neighbor search into STR-Tree #75

jiayuasu commented Feb 17, 2017

jnh5y left a comment

jnh5y Feb 17, 2017

jnh5y Feb 17, 2017

dr-jts Feb 17, 2017

jiayuasu Feb 17, 2017

dr-jts Feb 17, 2017

jiayuasu Feb 17, 2017

dr-jts Feb 17, 2017

dr-jts Feb 17, 2017

jiayuasu Feb 17, 2017

dr-jts Feb 17, 2017

jiayuasu Feb 17, 2017

dr-jts Feb 17, 2017

jiayuasu Feb 17, 2017

dr-jts Feb 17, 2017

jiayuasu Feb 17, 2017

dr-jts Feb 17, 2017

jiayuasu Feb 17, 2017

dr-jts Feb 17, 2017

dr-jts Feb 18, 2017

jiayuasu Feb 18, 2017

dr-jts Feb 18, 2017

dr-jts Feb 18, 2017

jiayuasu Feb 18, 2017

dr-jts Feb 20, 2017

jiayuasu Feb 20, 2017

dr-jts Feb 20, 2017 •

edited

Loading

dr-jts Feb 20, 2017

jiayuasu Feb 20, 2017

dr-jts Feb 20, 2017

jiayuasu Feb 20, 2017

Add K Nearest Neighbor search into STR-Tree #75

Add K Nearest Neighbor search into STR-Tree #75

Conversation

jiayuasu commented Feb 17, 2017

jnh5y left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dr-jts Feb 20, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dr-jts Feb 20, 2017 •

edited

Loading