Class S2PolygonBuilder.Options

java.lang.Object
com.google.common.geometry.S2PolygonBuilder.Options
Enclosing class:
S2PolygonBuilder

public static final class S2PolygonBuilder.Options extends Object
Options for initializing a S2PolygonBuilder. Choose one of the predefined options, or use a S2PolygonBuilder.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);
 
  • Field Details

    • 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 Details

  • Method Details

    • builder

      public static S2PolygonBuilder.Options.Builder builder()
      Static factory method for returning a new options S2PolygonBuilder.Options.Builder with default settings, which is equivalent to DIRECTED_XOR.
    • toBuilder

      Returns a new S2PolygonBuilder.Options.Builder with the same settings as the current options. Use this to create a new S2PolygonBuilder.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, use S2PolygonBuilder.Options.Builder.setUndirectedEdges(boolean) to set this attribute to true when building the options.
    • getXorEdges

      public boolean getXorEdges()
      If xorEdges 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 (via S2PolygonBuilder.Options.Builder.setXorEdges(boolean)):

      1. 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.
      2. 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. See S2PolygonBuilder.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 be Encode()d using less space. See S2EncodePointsCompressed in C++.

      Default value: false

    • getEdgeSpliceFraction

      public double getEdgeSpliceFraction()
      Returns the edge splice fraction, which defaults to 0.866 (approximately sqrt(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 from mergeDistance and edgeSpliceFraction.

      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. See S2PolygonBuilder.Options.Builder.setRobustnessRadius(com.google.common.geometry.S1Angle).

    • getSnapLevel

      public int getSnapLevel()
      If snapToCellCenters 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 if snapToCellCenters is false.