Class S2ShapeMeasures


  • @GwtCompatible
    final class S2ShapeMeasures
    extends java.lang.Object
    Defines various angle and area measures for S2Shape objects. Unlike the built-in S2Polygon and S2Polyline methods, these methods allow the underlying data to be represented arbitrarily.
    • Constructor Detail

      • S2ShapeMeasures

        private S2ShapeMeasures()
    • Method Detail

      • polylineLength

        static S1Angle polylineLength​(S2Shape shape,
                                      int chainId)
        Returns the length of the polyline, or S1Angle.ZERO if the polyline has fewer than two vertices.
      • perimeter

        public static S1Angle perimeter​(S2Shape shape)
        Returns the sum of all loop perimeters on the unit sphere for shapes of dimension 2, or S1Angle.ZERO otherwise. See length(S2Shape) for shapes of dimension 1.
      • loopPerimeter

        static S1Angle loopPerimeter​(S2Shape shape,
                                     int chainId)
        Returns the perimeter of the loop, or S1Angle.ZERO if the loop has 0 or 1 vertices.
      • area

        public static double area​(S2Shape shape)
        For shapes of dimension 2, returns the area of the shape on the unit sphere. The result is between 0 and 4*Pi steradians. Otherwise returns zero. This method has good relative accuracy for both very large and very small regions.
      • loopArea

        static double loopArea​(S2Shape shape,
                               int chainId)
        Returns the area of the loop interior, i.e. the region on the left side of the loop. The result is between 0 and 4*Pi steradians. The implementation ensures that nearly-degenerate clockwise loops have areas close to zero, while nearly-degenerate counter-clockwise loops have areas close to 4*Pi.
      • signedLoopArea

        private static double signedLoopArea​(S2Shape shape,
                                             int chainId)
        Returns the area of the loop interior, i.e. the region on the left side of the loop. The result is between 0 and 4*Pi steradians. The implementation ensures that nearly-degenerate clockwise loops have areas close to zero, while nearly-degenerate counter-clockwise loops have areas close to 4*Pi.
      • turningAngle

        static double turningAngle​(S2Shape shape,
                                   int chainId)
      • turningAngle

        static double turningAngle​(java.util.List<S2Point> loop)
        Returns the geodesic curvature of the loop, defined as the sum of the turn angles at each vertex (see S2.turnAngle(S2Point, S2Point, S2Point)). The result is positive if the loop is counter-clockwise, negative if the loop is clockwise, and zero if the loop is a great circle. The geodesic curvature is equal to 2*Pi minus the area of the loop.

        The following cases are handled specially:

        • Degenerate loops (consisting of an isolated vertex or composed entirely of sibling edge pairs) have a curvature of 2*Pi exactly.
        • The full loop (containing all points, and represented as a loop with no vertices) has a curvature of -2*Pi exactly.
        • All other loops have a non-zero curvature in the range (-2*Pi, 2*Pi). For any such loop, reversing the order of the vertices is guaranteed to negate the curvature. This property can be used to define a unique normalized orientation for every loop.
      • canonicalLoopOrder

        static S2ShapeMeasures.LoopOrder canonicalLoopOrder​(java.util.List<S2Point> loop)
        Returns an index "first" and a direction "dir" such that the vertex sequence (first, first + dir, ..., first + (n - 1) * dir) does not change when the loop vertex order is rotated or reversed. This allows the loop vertices to be traversed in a canonical order.
      • pruneDegeneracies

        static java.util.List<S2Point> pruneDegeneracies​(java.util.List<S2Point> input)
        Returns a new loop obtained by removing all degeneracies from "input". In particular, the result will not contain any adjacent duplicate vertices or sibling edge pairs, i.e. vertex sequences of the form (A, A) or (A, B, A).
      • polylineCentroid

        static S2Point polylineCentroid​(S2Shape shape,
                                        int chainId)
        Returns the true centroid of the polyline multiplied by the length of the polyline.

        Scaling by the polyline length makes it easy to compute the centroid of several polylines (by simply adding up their centroids).

        CAVEAT: Returns S2Point.ORIGIN for degenerate polylines (e.g., AA). [Note that this answer is correct; the result of this function is a line integral over the polyline, whose value is always zero if the polyline is degenerate].

      • vertices

        private static java.util.List<S2Point> vertices​(S2Shape shape,
                                                        int chainId)