Default constructor; requires initialize() to be called.
Convenience constructor that calls Init(). Options may be specified here or changed at any time using the mutable_options() accessor method.
Each "Result" object represents a closest point. Here are its main methods (see S2ClosestPointQueryBase::Result for details):
Returns the closest point to the target. If no point satisfies the search criteria, then a Result object with distance() == Infinity() and is_empty() == true is returned.
Returns the closest points to the given target that satisfy the given options. This method may be called multiple times.
This version can be more efficient when this method is called many times, since it does not require allocating a new vector on each call.
Returns the minimum distance to the target. If the index or target is empty, returns S1ChordAngle::Infinity().
Returns a reference to the underlying S2PointIndex.
Initializes the query. Options may be specified here or changed at any time using the mutable_options() accessor method.
Like IsDistanceLessOrEqual(), except that "limit" is increased by the maximum error in the distance calculation. This ensures that this function returns true whenever the true, exact distance is less than or equal to "limit".
Returns true if the distance to "target" is less than "limit".
Like IsDistanceLess(), but also returns true if the distance to "target" is exactly equal to "limit".
Returns the query options. Options can be modifed between queries.
Reinitializes the query. This method must be called whenever the underlying index is modified.
Given a set of points stored in an S2PointIndex, S2ClosestPointQuery provides methods that find the closest point(s) to a given query point or query edge. Example usage:
void Test(const vector<S2Point>& index_points, const vector<S2Point>& target_points) { // The template argument allows auxiliary data to be attached to each // point (in this case, the array index). S2PointIndex<int> index; for (const S2Point& point : index_points) { index.Add(point, i); } S2ClosestPointQuery<int> query(&index); query.mutable_options()->set_max_points(5); for (const S2Point& target_point : target_points) { S2ClosestPointQueryPointTarget target(target_point); for (const auto& result : query.FindClosestPoints(&target)) { // The Result class contains the following methods: // distance() is the distance to the target. // point() is the indexed point. // data() is the auxiliary data. DoSomething(target_point, result); } } }
You can find either the k closest points, or all points within a given radius, or both (i.e., the k closest points up to a given maximum radius). E.g. to find all the points within 5 kilometers, call
query.mutable_options()->set_max_distance( S2Earth::ToAngle(util::units::Kilometers(5)));
By default *all* points are returned, so you should always specify either max_points() or max_distance() or both. There is also a FindClosestPoint() convenience method that returns only the closest point.
You can restrict the results to an arbitrary S2Region, for example:
S2LatLngRect rect(...); query.set_region(&rect); // Does *not* take ownership.
To find the closest points to a query edge rather than a point, use:
S2ClosestPointQueryEdgeTarget target(v0, v1); query.FindClosestPoints(&target);
The implementation is designed to be fast for both small and large point sets.