Class S2Cap

  • All Implemented Interfaces:
    S2Region, java.io.Serializable

    @GwtCompatible(serializable=true)
    public final class S2Cap
    extends java.lang.Object
    implements S2Region, java.io.Serializable
    S2Cap represents a disc-shaped region defined by a center and radius. Technically this shape is called a "spherical cap" (rather than disc) because it is not planar; the cap represents a portion of the sphere that has been cut off by a plane. The boundary of the cap is the circle defined by the intersection of the sphere and the plane. For containment purposes, the cap is a closed set, i.e. it contains its boundary.

    For the most part, you can use a spherical cap wherever you would use a disc in planar geometry. The radius of the cap is measured along the surface of the sphere (rather than the straight-line distance through the interior). Thus a cap of radius Pi/2 is a hemisphere, and a cap of radius Pi covers the entire sphere.

    A cap can also be defined by its center point and height. The height is simply the distance from the center point to the cutoff plane. There is also support for "empty" and "full" caps, which contain no points and all points respectively.

    See Also:
    Serialized Form
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private S2Cap​(S2Point axis, S1ChordAngle radius)  
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      S2Cap addCap​(S2Cap other)
      Increase the cap radius if necessary to include the given cap.
      S2Cap addPoint​(S2Point p)
      Increase the cap radius if necessary to include the given point.
      S1Angle angle()
      Returns the cap radius as an S1Angle.
      (package private) boolean approxEquals​(S2Cap other)  
      (package private) boolean approxEquals​(S2Cap other, double maxError)
      Returns true if the radian angle between axes of this and 'other' is at most 'maxError', and the chord distance radius between this and 'other' is at most 'maxError'.
      double area()  
      S2Point axis()  
      S2Cap complement()
      Return the complement of the interior of the cap.
      boolean contains​(S2Cap other)
      Return true if and only if this cap contains the given other cap (in a set containment sense, e.g.
      boolean contains​(S2Cell cell)
      If this method returns true, the region completely contains the given cell.
      boolean contains​(S2Point p)
      Returns true if and only if the given point is contained by the region.
      (package private) static S2Cap decode​(LittleEndianInput is)
      Returns a new S2Cap decoded from the given little endian input stream.
      static S2Cap decode​(java.io.InputStream is)
      Returns a new S2Cap decoded from the given input stream.
      static S2Cap empty()
      Return an empty cap, i.e.
      (package private) void encode​(LittleEndianOutput os)
      Writes this cap to the given little endian output stream.
      void encode​(java.io.OutputStream os)
      Writes this cap to the given output stream.
      boolean equals​(java.lang.Object that)
      Return true if two caps are identical.
      static S2Cap fromAxisAngle​(S2Point axis, S1Angle angle)
      Create a cap given its axis and the cap opening angle, i.e.
      static S2Cap fromAxisArea​(S2Point axis, double area)
      Create a cap given its axis and its area in steradians.
      static S2Cap fromAxisChord​(S2Point center, S1ChordAngle radius)
      Creates a cap where the radius is expressed as an S1ChordAngle.
      static S2Cap fromAxisHeight​(S2Point axis, double height)
      Create a cap given its axis and the cap height, i.e.
      static S2Cap full()
      Return a full cap, i.e.
      S2Cap getCapBound()
      Return a bounding spherical cap.
      S2LatLngRect getRectBound()
      Return a bounding latitude-longitude rectangle.
      int hashCode()  
      double height()
      Returns the height of the cap, i.e.
      boolean interiorContains​(S2Point p)
      Return true if and only if the given point is contained in the interior of the region (i.e.
      boolean interiorIntersects​(S2Cap other)
      Return true if and only if the interior of this cap intersects the given other cap.
      boolean intersects​(S2Cell cell, S2Point[] vertices)
      Return true if the cap intersects 'cell', given that the cap vertices have already been checked.
      boolean isEmpty()
      Return true if the cap is empty, i.e.
      boolean isFull()
      Return true if the cap is full, i.e.
      boolean isValid()
      Returns true if the axis is unit length, and the angle is less than Pi.
      boolean mayIntersect​(S2Cell cell)
      If this method returns false, the region does not intersect the given cell.
      S1ChordAngle radius()  
      java.lang.String toString()  
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Method Detail

      • fromAxisHeight

        public static S2Cap fromAxisHeight​(S2Point axis,
                                           double height)
        Create a cap given its axis and the cap height, i.e. the maximum projected distance along the cap axis from the cap center. 'axis' should be a unit-length vector.
      • fromAxisAngle

        public static S2Cap fromAxisAngle​(S2Point axis,
                                          S1Angle angle)
        Create a cap given its axis and the cap opening angle, i.e. maximum angle between the axis and a point on the cap. 'axis' should be a unit-length vector, and 'angle' should be between 0 and 180 degrees.
      • fromAxisArea

        public static S2Cap fromAxisArea​(S2Point axis,
                                         double area)
        Create a cap given its axis and its area in steradians. 'axis' should be a unit-length vector, and 'area' should be between 0 and 4 * M_PI.
      • empty

        public static S2Cap empty()
        Return an empty cap, i.e. a cap that contains no points.
      • full

        public static S2Cap full()
        Return a full cap, i.e. a cap that contains all points.
      • height

        public double height()
        Returns the height of the cap, i.e. the distance from the center point to the cutoff plane.
      • area

        public double area()
      • angle

        public S1Angle angle()
        Returns the cap radius as an S1Angle. Since the cap angle is stored internally as an S1ChordAngle, this method requires a trigonometric operation and may yield a slightly different result than the value passed to fromAxisAngle(S2Point, S1Angle).
      • isValid

        public boolean isValid()
        Returns true if the axis is unit length, and the angle is less than Pi.

        Negative angles or heights are valid, and represent empty caps.

      • isEmpty

        public boolean isEmpty()
        Return true if the cap is empty, i.e. it contains no points.
      • isFull

        public boolean isFull()
        Return true if the cap is full, i.e. it contains all points.
      • complement

        @CheckReturnValue
        public S2Cap complement()
        Return the complement of the interior of the cap. A cap and its complement have the same boundary but do not share any interior points. The complement operator is not a bijection, since the complement of a singleton cap (containing a single point) is the same as the complement of an empty cap.
      • contains

        public boolean contains​(S2Cap other)
        Return true if and only if this cap contains the given other cap (in a set containment sense, e.g. every cap contains the empty cap).
      • interiorIntersects

        public boolean interiorIntersects​(S2Cap other)
        Return true if and only if the interior of this cap intersects the given other cap. (This relationship is not symmetric, since only the interior of this cap is used.)
      • interiorContains

        public boolean interiorContains​(S2Point p)
        Return true if and only if the given point is contained in the interior of the region (i.e. the region excluding its boundary). 'p' should be a unit-length vector.
      • addPoint

        @CheckReturnValue
        public S2Cap addPoint​(S2Point p)
        Increase the cap radius if necessary to include the given point. If the cap is empty the axis is set to the given point, but otherwise it is left unchanged.
        Parameters:
        p - must be unit length
      • addCap

        @CheckReturnValue
        public S2Cap addCap​(S2Cap other)
        Increase the cap radius if necessary to include the given cap. If the current cap is empty, it is set to the given other cap.
      • getCapBound

        public S2Cap getCapBound()
        Description copied from interface: S2Region
        Return a bounding spherical cap.
        Specified by:
        getCapBound in interface S2Region
      • contains

        public boolean contains​(S2Cell cell)
        Description copied from interface: S2Region
        If this method returns true, the region completely contains the given cell. Otherwise, either the region does not contain the cell or the containment relationship could not be determined.
        Specified by:
        contains in interface S2Region
      • mayIntersect

        public boolean mayIntersect​(S2Cell cell)
        Description copied from interface: S2Region
        If this method returns false, the region does not intersect the given cell. Otherwise, either region intersects the cell, or the intersection relationship could not be determined.
        Specified by:
        mayIntersect in interface S2Region
      • intersects

        public boolean intersects​(S2Cell cell,
                                  S2Point[] vertices)
        Return true if the cap intersects 'cell', given that the cap vertices have already been checked.
      • contains

        public boolean contains​(S2Point p)
        Description copied from interface: S2Region
        Returns true if and only if the given point is contained by the region. p is generally required to be unit length, although some subtypes may relax this restriction.
        Specified by:
        contains in interface S2Region
      • equals

        public boolean equals​(java.lang.Object that)
        Return true if two caps are identical.
        Overrides:
        equals in class java.lang.Object
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • approxEquals

        boolean approxEquals​(S2Cap other,
                             double maxError)
        Returns true if the radian angle between axes of this and 'other' is at most 'maxError', and the chord distance radius between this and 'other' is at most 'maxError'.
      • approxEquals

        boolean approxEquals​(S2Cap other)
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • encode

        public void encode​(java.io.OutputStream os)
                    throws java.io.IOException
        Writes this cap to the given output stream.
        Throws:
        java.io.IOException
      • encode

        void encode​(LittleEndianOutput os)
             throws java.io.IOException
        Writes this cap to the given little endian output stream.
        Throws:
        java.io.IOException
      • decode

        public static S2Cap decode​(java.io.InputStream is)
                            throws java.io.IOException
        Returns a new S2Cap decoded from the given input stream.
        Throws:
        java.io.IOException
      • decode

        static S2Cap decode​(LittleEndianInput is)
                     throws java.io.IOException
        Returns a new S2Cap decoded from the given little endian input stream.
        Throws:
        java.io.IOException