Class S2PolygonBuilder.Options
- java.lang.Object
-
- com.google.common.geometry.S2PolygonBuilder.Options
-
- Enclosing class:
- S2PolygonBuilder
public static final class S2PolygonBuilder.Options extends java.lang.Object
Options for initializing aS2PolygonBuilder
. Choose one of the predefined options, or use aS2PolygonBuilder.Options.Builder
to construct a new one.Examples:
S2PolygonBuilder polygonBuilder = new S2PolygonBuilder( S2PolygonBuilder.Options.UNDIRECTED_XOR); S2PolygonBuilder.Options options = S2PolygonBuilder.Options.DIRECTED_XOR.toBuilder() .setMergeDistance(vertexMergeRadius) .build(); S2PolygonBuilder polygonBuilder = new S2PolygonBuilder(options); S2PolygonBuilder.Options options = S2PolygonBuilder.Options.builder() .setUndirectedEdges(false) .setXorEdges(true) .setMergeDistance(vertexMergeRadius) .build(); S2PolygonBuilder polygonBuilder = new S2PolygonBuilder(options);
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
S2PolygonBuilder.Options.Builder
Builder class forS2PolygonBuilder.Options
.
-
Field Summary
Fields Modifier and Type Field Description static S2PolygonBuilder.Options
DIRECTED_UNION
Finally, select this option when the desired output is a collection of loops rather than a polygon, but your input edges are directed and you do not want reverse edges to be added implicitly as above.static S2PolygonBuilder.Options
DIRECTED_XOR
These are the options that should be used for assembling well-behaved input data into polygons.private double
edgeSpliceFraction
private S1Angle
mergeDistance
private boolean
snapToCellCenters
static S2PolygonBuilder.Options
UNDIRECTED_UNION
These are the options that should be used for assembling edges where the desired output is a collection of loops rather than a polygon, and edges may occur more than once.static S2PolygonBuilder.Options
UNDIRECTED_XOR
These are the options that should be used for assembling polygons that do not follow the conventions above, e.g., where edge directions may vary within a single loop, or shells and holes are not oppositely oriented.private boolean
undirectedEdges
private boolean
validate
private boolean
xorEdges
-
Constructor Summary
Constructors Modifier Constructor Description private
Options(S2PolygonBuilder.Options.Builder builder)
Private constructor called by theS2PolygonBuilder.Options.Builder
.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static S2PolygonBuilder.Options.Builder
builder()
Static factory method for returning a new optionsS2PolygonBuilder.Options.Builder
with default settings, which is equivalent toDIRECTED_XOR
.double
getEdgeSpliceFraction()
Returns the edge splice fraction, which defaults to 0.866 (approximatelysqrt(3)/2
).S1Angle
getMergeDistance()
If set to a positive value, all vertex pairs that are separated by less than this distance will be merged together.S1Angle
getRobustnessRadius()
Returns robustness radius computed frommergeDistance
andedgeSpliceFraction
.int
getSnapLevel()
IfsnapToCellCenters
is true, returns the minimum level at which snapping a point to the center of a cell at that level will move the point by no more than the robustness radius.boolean
getSnapToCellCenters()
If true, the built polygon will have its vertices snapped to the centers of s2 cells at the smallest level number such that no vertex will move by more than the robustness radius.boolean
getUndirectedEdges()
If this returns false, the input is assumed to consist of edges that can be assembled into oriented loops without reversing any of the edges.boolean
getValidate()
If true,S2Loop.isValid()
is called on all loops and polygons before constructing them.boolean
getXorEdges()
IfxorEdges
is true, any duplicate edge pairs are removed.S2PolygonBuilder.Options.Builder
toBuilder()
Returns a newS2PolygonBuilder.Options.Builder
with the same settings as the current options.
-
-
-
Field Detail
-
DIRECTED_XOR
public static final S2PolygonBuilder.Options DIRECTED_XOR
These are the options that should be used for assembling well-behaved input data into polygons. All edges should be directed such that "shells" and "holes" have opposite orientations (typically CCW shells and clockwise holes), unless it is known that shells and holes do not share any edges.
-
UNDIRECTED_XOR
public static final S2PolygonBuilder.Options UNDIRECTED_XOR
These are the options that should be used for assembling polygons that do not follow the conventions above, e.g., where edge directions may vary within a single loop, or shells and holes are not oppositely oriented.
-
UNDIRECTED_UNION
public static final S2PolygonBuilder.Options UNDIRECTED_UNION
These are the options that should be used for assembling edges where the desired output is a collection of loops rather than a polygon, and edges may occur more than once. Edges are treated as undirected and are not XORed together, in particular, adding edge A->B also adds B->A.
-
DIRECTED_UNION
public static final S2PolygonBuilder.Options DIRECTED_UNION
Finally, select this option when the desired output is a collection of loops rather than a polygon, but your input edges are directed and you do not want reverse edges to be added implicitly as above.
-
undirectedEdges
private final boolean undirectedEdges
-
xorEdges
private final boolean xorEdges
-
validate
private final boolean validate
-
mergeDistance
private final S1Angle mergeDistance
-
snapToCellCenters
private final boolean snapToCellCenters
-
edgeSpliceFraction
private final double edgeSpliceFraction
-
-
Constructor Detail
-
Options
private Options(S2PolygonBuilder.Options.Builder builder)
Private constructor called by theS2PolygonBuilder.Options.Builder
.
-
-
Method Detail
-
builder
public static S2PolygonBuilder.Options.Builder builder()
Static factory method for returning a new optionsS2PolygonBuilder.Options.Builder
with default settings, which is equivalent toDIRECTED_XOR
.
-
toBuilder
public S2PolygonBuilder.Options.Builder toBuilder()
Returns a newS2PolygonBuilder.Options.Builder
with the same settings as the current options. Use this to create a newS2PolygonBuilder.Options
based on the current options.
-
getUndirectedEdges
public boolean getUndirectedEdges()
If this returns false, the input is assumed to consist of edges that can be assembled into oriented loops without reversing any of the edges. Otherwise, useS2PolygonBuilder.Options.Builder.setUndirectedEdges(boolean)
to set this attribute to true when building the options.
-
getXorEdges
public boolean getXorEdges()
IfxorEdges
is true, any duplicate edge pairs are removed. This is useful for computing the union of a collection of polygons whose interiors are disjoint but whose boundaries may share some common edges (e.g., computing the union of South Africa, Lesotho, and Swaziland).Note that for directed edges, a "duplicate edge pair" consists of an edge and its corresponding reverse edge. This means that either (a) "shells" and "holes" must have opposite orientations, or (b) shells and holes do not share edges.
There are only two reasons to turn off
xorEdges
(viaS2PolygonBuilder.Options.Builder.setXorEdges(boolean)
):S2PolygonBuilder.assemblePolygon(com.google.common.geometry.S2Polygon, java.util.List<com.google.common.geometry.S2Edge>)
will be called, and you want to assert that there are no duplicate edge pairs in the input.S2PolygonBuilder.assembleLoops(java.util.List<com.google.common.geometry.S2Loop>, java.util.List<com.google.common.geometry.S2Edge>)
will be called, and you want to keep abutting loops separate in the output, rather than merging their regions together (e.g., assembling loops for Kansas City, KS and Kansas City, MO simultaneously).
-
getValidate
public boolean getValidate()
If true,S2Loop.isValid()
is called on all loops and polygons before constructing them. If any loop is invalid (e.g., self-intersecting), it is rejected and returned as a set of "unused edges". Any remaining valid loops are kept. If the entire polygon is invalid (e.g., two loops intersect), then all edges are rejected and returned as unused edges. SeeS2PolygonBuilder.Options.Builder.setValidate(boolean)
.Default value: false
-
getMergeDistance
public S1Angle getMergeDistance()
If set to a positive value, all vertex pairs that are separated by less than this distance will be merged together. Note that vertices can move arbitrarily far if there is a long chain of vertices separated by less than this distance.Setting this to a positive value is useful for assembling polygons out of input data where vertices and/or edges may not be perfectly aligned. See
S2PolygonBuilder.Options.Builder.setMergeDistance(com.google.common.geometry.S1Angle)
.Default value: 0
-
getSnapToCellCenters
public boolean getSnapToCellCenters()
If true, the built polygon will have its vertices snapped to the centers of s2 cells at the smallest level number such that no vertex will move by more than the robustness radius. If the robustness radius is smaller than half the leaf cell diameter, no snapping will occur. This is useful because snapped polygons can beEncode()
d using less space. SeeS2EncodePointsCompressed
in C++.Default value: false
-
getEdgeSpliceFraction
public double getEdgeSpliceFraction()
Returns the edge splice fraction, which defaults to 0.866 (approximatelysqrt(3)/2
).The edge splice radius is automatically set to this fraction of the vertex merge radius. If the edge splice radius is positive, then all vertices that are closer than this distance to an edge are spliced into that edge. Note that edges can move arbitrarily far if there is a long chain of vertices in just the right places.
You can turn off edge splicing by setting this value to zero; see
S2PolygonBuilder.Options.Builder.setEdgeSpliceFraction(double)
. This will save some time if you don't need this feature, or you don't want vertices to be spliced into nearby edges for some reason.Note that the edge splice fraction must be less than
sqrt(3)/2
in order to avoid infinite loops in the merge algorithm. The default value is very close to this maximum and therefore results in the maximum amount of edge splicing for a given vertex merge radius.The only reason to reduce the edge splice fraction is if you want to limit changes in edge direction due to splicing. The direction of an edge can change by up to
asin(edgeSpliceFraction)
due to each splice. Thus, by default, edges are allowed to change direction by up to 60 degrees per splice. However, note that most direction changes are much smaller than this: the worst case occurs only if the vertex being spliced is just outside the vertex merge radius from one of the edge endpoints.
-
getRobustnessRadius
public S1Angle getRobustnessRadius()
Returns robustness radius computed frommergeDistance
andedgeSpliceFraction
.The lossless way to serialize a polygon takes 24 bytes per vertex (3 doubles). If you want a representation with fewer bits, you need to snap your vertices to a grid. If a vertex is very close to an edge, the snapping operation can lead to self-intersection. The
edgeSpliceFraction
cannot be zero to have a robustness guarantee. SeeS2PolygonBuilder.Options.Builder.setRobustnessRadius(com.google.common.geometry.S1Angle)
.
-
getSnapLevel
public int getSnapLevel()
IfsnapToCellCenters
is true, returns the minimum level at which snapping a point to the center of a cell at that level will move the point by no more than the robustness radius. Returns -1 if there is no such level, or ifsnapToCellCenters
is false.
-
-