Class S2Builder.SnapFunction
A SnapFunction restricts the locations of the output vertices. For example, there are predefined snap functions that require vertices to be located at S2CellId centers or at E5/E6/E7 coordinates. The SnapFunction can also specify a minimum spacing between vertices (the "snap radius").
class SnapFunction
;
A SnapFunction defines the following methods:
1. The SnapPoint() method, which snaps a point P to a nearby point (the "candidate snap site"). Any point may be returned, including P itself (this is the "identity snap function").
2. "snap_radius", the maximum distance that vertices can move when snapped. The snap_radius must be at least as large as the maximum distance between P and SnapPoint(P) for any point P.
3. "max_edge_deviation", the maximum distance that edges can move when snapped. It is slightly larger than "snap_radius" because when a geodesic edge is snapped, the center of the edge moves further than its endpoints. This value is computed automatically by S2Builder.
4. "min_vertex_separation", the guaranteed minimum distance between vertices in the output. This is generally a fraction of "snap_radius" where the fraction depends on the snap function.
5. A "min_edge_vertex_separation", the guaranteed minimum distance between edges and non-incident vertices in the output. This is generally a fraction of "snap_radius" where the fraction depends on the snap function.
It is important to note that SnapPoint() does not define the actual mapping from input vertices to output vertices, since the points it returns (the candidate snap sites) are further filtered to ensure that they are separated by at least the snap radius. For example, if you specify E7 coordinates (2cm resolution) and a snap radius of 10m, then a subset of points returned by SnapPoint will be chosen (the "snap sites"), and each input vertex will be mapped to the closest site. Therefore you cannot assume that P is necessarily snapped to SnapPoint(P).
S2Builder makes the following guarantees:
1. Every vertex is at a location returned by SnapPoint().
2. Vertices are within "snap_radius" of the corresponding input vertex.
3. Edges are within "max_edge_deviation" of the corresponding input edge (a distance slightly larger than "snap_radius").
4. Vertices are separated by at least "min_vertex_separation" (a fraction of "snap_radius" that depends on the snap function).
5. Edges and non-incident vertices are separated by at least "min_edge_vertex_separation" (a fraction of "snap_radius").
6. Vertex and edge locations do not change unless one of the conditions above is not already met (idempotency / stability).
7. The topology of the input geometry is preserved (up to the creation of degeneracies). This means that there exists a continuous deformation from the input to the output such that no vertex crosses an edge.
Methods
| Name | Description |
|---|---|
kMaxSnapRadius
()
|
The maximum snap radius is just large enough to support snapping to S2CellId level 0. It is equivalent to 7800km on the Earth's surface. |
maxEdgeDeviation
()
|
The maximum distance that the center of an edge can move when snapped. This is slightly larger than "snap_radius" because when a geodesic edge is snapped, the center of the edge moves further than its endpoints. |
minEdgeVertexSeparation
()
|
The guaranteed minimum spacing between edges and non-incident vertices in the output. This is generally some fraction of "snap_radius". |
minVertexSeparation
()
|
The guaranteed minimum distance between vertices in the output. This is generally some fraction of "snap_radius". |
snapPoint
(point)
|
Returns a candidate snap site for the given point. The final vertex locations are a subset of the snap sites returned by this function (spaced at least "min_vertex_separation" apart). |
snapRadius
()
|
The maximum distance that vertices can move when snapped. |