A function that calculates the distance between two points. For the purposes of vp-trees, distance functions must 5 | * conform to the rules of a metric space, namely:
6 | * 7 | *distanceFunction; 18 | private final DistanceComparator
distanceComparator;
19 | private final PriorityQueue distanceFunction, final int capacity) {
35 | if (capacity < 1) {
36 | throw new IllegalArgumentException("Capacity must be positive.");
37 | }
38 |
39 | this.queryPoint = queryPoint;
40 | this.distanceFunction = distanceFunction;
41 | this.capacity = capacity;
42 |
43 | this.distanceComparator = new DistanceComparator<>(queryPoint, distanceFunction);
44 |
45 | this.priorityQueue =
46 | new PriorityQueue<>(this.capacity, java.util.Collections.reverseOrder(this.distanceComparator));
47 | }
48 |
49 | /**
50 | * Returns the query point for this collector.
51 | *
52 | * @return the query point for this collector
53 | */
54 | public P getQueryPoint() {
55 | return this.queryPoint;
56 | }
57 |
58 | /**
59 | * Offers a point to this collector. The point may or may not be added to the collection; points will only be added
60 | * if the collector is not already full, or if the collector is full, but the offered point is closer to the query
61 | * point than the most distant point already in the collection.
62 | *
63 | * @param point the point to offer to this collector
64 | */
65 | public void offerPoint(final E point) {
66 | final boolean pointAdded;
67 |
68 | if (this.priorityQueue.size() < this.capacity) {
69 | this.priorityQueue.add(point);
70 | pointAdded = true;
71 | } else {
72 | assert this.priorityQueue.size() > 0;
73 |
74 | final double distanceToNewPoint = this.distanceFunction.getDistance(this.queryPoint, point);
75 |
76 | if (distanceToNewPoint < this.distanceToFarthestPoint) {
77 | this.priorityQueue.poll();
78 | this.priorityQueue.add(point);
79 | pointAdded = true;
80 | } else {
81 | pointAdded = false;
82 | }
83 | }
84 |
85 | if (pointAdded) {
86 | this.distanceToFarthestPoint = this.distanceFunction.getDistance(this.queryPoint, this.priorityQueue.peek());
87 | }
88 | }
89 |
90 | /**
91 | * Returns the point retained by this collector that is the farthest from the query point.
92 | *
93 | * @return the point retained by this collector that is the farthest from the query point
94 | */
95 | public E getFarthestPoint() {
96 | return this.priorityQueue.peek();
97 | }
98 |
99 | /**
100 | * Returns a list of points retained by this collector, sorted by distance from the query point.
101 | *
102 | * @return a list of points retained by this collector, sorted by distance from the query point
103 | */
104 | public List the base type of points between which distances can be measured
21 | * @param Returns a list of the nearest neighbors to a given query point. The returned list is sorted by increasing
26 | * distance from the query point. This returned list will contain at most {@code maxResults} elements (and may contain fewer if
29 | * {@code maxResults} is larger than the number of points in the index). If multiple points have the same distance
30 | * from the query point, the order in which they appear in the returned list is undefined. By extension, if multiple
31 | * points have the same distance from the query point and those points would "straddle" the end of the
32 | * returned list, which points are included in the list and which are cut off is not prescribed. Returns a list of the nearest neighbors accepted by the given filter to a given query point. The returned list
44 | * is sorted by increasing distance from the query point. This returned list will contain at most {@code maxResults} elements (and may contain fewer if
47 | * {@code maxResults} is larger than the number of points in the index). If multiple points have the same distance
48 | * from the query point, the order in which they appear in the returned list is undefined. By extension, if multiple
49 | * points have the same distance from the query point and those points would "straddle" the end of the
50 | * returned list, which points are included in the list and which are cut off is not prescribed. distanceFunction);
27 | }
28 |
--------------------------------------------------------------------------------
/src/main/java/com/eatthepath/jvptree/VPTree.java:
--------------------------------------------------------------------------------
1 | package com.eatthepath.jvptree;
2 |
3 | import java.util.ArrayList;
4 | import java.util.Collection;
5 | import java.util.Collections;
6 | import java.util.Iterator;
7 | import java.util.List;
8 |
9 | import com.eatthepath.jvptree.util.SamplingMedianDistanceThresholdSelectionStrategy;
10 |
11 | /**
12 | * A vantage-point tree (or vp-tree) is a binary space partitioning collection of points in a metric space. The main
13 | * feature of vantage point trees is that they allow for k-nearest-neighbor searches in any metric space in
14 | * O(log(n)) time. Vantage point trees recursively partition points by choosing a "vantage point" and a distance threshold;
17 | * points are then partitioned into one collection that contains all of the points closer to the vantage point than the
18 | * chosen threshold and one collection that contains all of the points farther away than the chosen threshold. A {@linkplain DistanceFunction distance function} that satisfies the properties of a metric space must be provided
21 | * when constructing a vantage point tree. Callers may also specify a threshold selection strategy (a sampling median
22 | * strategy is used by default) and a node size to tune the ratio of nodes searched to points inspected per node.
23 | * Vantage point trees may be constructed with or without an initial collection of points, though specifying a
24 | * collection of points at construction time is the most efficient approach. the base type of points between which distances can be measured
29 | * @param distanceFunction;
34 | private final ThresholdSelectionStrategy