Class S2Cap

java.lang.Object
com.google.common.geometry.S2Cap
All Implemented Interfaces:
S2Region, Serializable

@GwtCompatible(serializable=true) public final class S2Cap extends Object implements S2Region, 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:
  • Field Details

  • Constructor Details

  • Method Details

    • fromAxisChord

      public static S2Cap fromAxisChord(S2Point center, S1ChordAngle radius)
      Creates a cap where the radius is expressed as an S1ChordAngle. This constructor is more efficient than fromAxisAngle(S2Point, S1Angle).
    • 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.
    • axis

      public S2Point axis()
    • radius

      public S1ChordAngle radius()
    • 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
    • getRectBound

      public S2LatLngRect getRectBound()
      Description copied from interface: S2Region
      Return a bounding latitude-longitude rectangle.
      Specified by:
      getRectBound 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(Object that)
      Return true if two caps are identical.
      Overrides:
      equals in class Object
    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class 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 String toString()
      Overrides:
      toString in class Object
    • encode

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

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

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

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