Class S2Cell

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

@GwtCompatible(serializable=true) public final class S2Cell extends Object implements S2Region, Serializable
An S2Cell is an S2Region object that represents a cell. Unlike S2CellIds, it supports efficient containment and intersection tests. However, it is also a more expensive representation.
See Also:
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private static interface 
     
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    (package private) S2CellId
     
    (package private) byte
     
    (package private) byte
     
    (package private) byte
     
    private static final double
    The 4 cells around the equator extend to +/-45 degrees latitude at the midpoints of their top and bottom edges.
    (package private) double
     
    (package private) double
     
    (package private) double
     
    (package private) double
     
  • Constructor Summary

    Constructors
    Constructor
    Description
    Default constructor used only internally.
    An S2Cell always corresponds to a particular S2CellId.
     
     
  • Method Summary

    Modifier and Type
    Method
    Description
    double
    Return the approximate area of this cell in steradians.
    double
    Return the average area in steradians of cells at this level.
    static double
    averageArea(int level)
    Return the average area in steradians for cells at the given level.
    private static double
    chordDist2(S2Point uvw, double u, double v)
    Returns the squared chord distance from uvw to position uv.
     
    boolean
    If this method returns true, the region completely contains the given cell.
    boolean
    Returns true if and only if the given point is contained by the region.
    private static double
    edgeDistance(double dirIJ, double uv)
    Given the dot product of a point P with the normal of a u- or v-edge at the given coordinate value, returns the distance from P to that edge.
    boolean
    equals(Object that)
     
    double
    Return the area in steradians of this cell as accurately as possible.
    int
     
    static S2Cell
    fromFace(int face)
    Returns the cell corresponding to the given S2 cube face.
    static S2Cell
    fromFacePosLevel(int face, long pos, int level)
    Returns a cell given its face (range 0..5), Hilbert curve position within that face (an unsigned integer with S2CellId.POS_BITS bits), and level (range 0..kMaxLevel).
    Returns the distance from the cell boundary to the given point.
    Returns the bounds of this cell in (u,v)-space.
    Return a bounding spherical cap.
    Return the direction vector corresponding to the center in (s,t)-space of the given cell.
     
    Return the center of the cell in (u,v) coordinates (see S2Projections).
    Returns the distance to the given cell.
    getDistance(S2Point targetXyz)
    Returns the distance from the given point to the cell.
    private double
    getDistanceInternal(S2Point targetXyz, boolean toInterior)
    Returns the chord distance to targetXyz, with interior distance 0 iff toInterior is true.
    Returns the minimum distance from the cell to the given edge AB, or zero if the edge intersects the cell interior.
    getEdge(int k)
    As getEdgeRaw(int), except the point is normalized to unit length.
    getEdgeRaw(int k)
    Returns the inward-facing normal of the great circle passing through the edge from vertex k to vertex k+1 (mod 4).
    Returns the maximum distance from the cell, including interior, to the given target cell.
    Returns the maximum distance from the cell (including its interior) to the given point.
    Returns the maximum distance from the cell (including its interior) to the given edge AB.
    private S2Point
    getPoint(int i, int j)
     
    Return a bounding latitude-longitude rectangle.
    int
    As S2CellId.getSizeIJ(int), using the level of this cell.
    getVertex(int k)
    As getVertexRaw(int), except the point is normalized to unit length.
    getVertexRaw(int k)
    Returns the kth vertex of the cell (k = 0,1,2,3).
    int
     
    id()
     
    private void
     
    boolean
    Returns true if this cell is a leaf-cell, i.e.
    byte
     
    boolean
    If this method returns false, the region does not intersect the given cell.
    byte
     
    (package private) void
    Sets the bounds of this cell in (u,v)-space into 'bound'.
    boolean
    subdivide(S2Cell[] children)
    Returns true if this is not a leaf cell, in which case the array, which must contain at least four non-null cells in indices 0..3, will be set to the four children of this cell in traversal order.
     
    private boolean
    uEdgeIsClosest(S2Point p, boolean vEnd)
    Given a point p and either the lower or upper edge of the S2Cell (specified by setting vEnd to false or true respectively), returns true if p is closer to the interior of that edge than it is to either endpoint.
    private boolean
    vEdgeIsClosest(S2Point p, boolean uEnd)
    Given a point p and either the left or right edge of the S2Cell (specified by setting uEnd to false or true respectively), returns true if p is closer to the interior of that edge than it is to either endpoint.
    private double
     

    Methods inherited from class java.lang.Object

    finalize, getClass, notify, notifyAll, wait, wait, wait
  • Field Details

    • face

      byte face
    • level

      byte level
    • orientation

      byte orientation
    • cellId

      S2CellId cellId
    • uMin

      double uMin
    • uMax

      double uMax
    • vMin

      double vMin
    • vMax

      double vMax
    • POLE_MIN_LAT

      private static final double POLE_MIN_LAT
      The 4 cells around the equator extend to +/-45 degrees latitude at the midpoints of their top and bottom edges. The two cells covering the poles extend down to +/-35.26 degrees at their vertices. The maximum error in this calculation is 0.5 * DBL_EPSILON.
  • Constructor Details

    • S2Cell

      S2Cell()
      Default constructor used only internally.
    • S2Cell

      public S2Cell(S2CellId id)
      An S2Cell always corresponds to a particular S2CellId. The other constructors are just convenience methods.
    • S2Cell

      public S2Cell(S2Point p)
    • S2Cell

      public S2Cell(S2LatLng ll)
  • Method Details

    • fromFace

      public static S2Cell fromFace(int face)
      Returns the cell corresponding to the given S2 cube face.
    • fromFacePosLevel

      public static S2Cell fromFacePosLevel(int face, long pos, int level)
      Returns a cell given its face (range 0..5), Hilbert curve position within that face (an unsigned integer with S2CellId.POS_BITS bits), and level (range 0..kMaxLevel). The given position will be modified to correspond to the Hilbert curve position at the center of the returned cell. This is a static function rather than a constructor in order to indicate what the arguments represent.
    • id

      public S2CellId id()
    • face

      public int face()
    • level

      public byte level()
    • orientation

      public byte orientation()
    • isLeaf

      public boolean isLeaf()
      Returns true if this cell is a leaf-cell, i.e. it has no children.
    • getVertex

      public S2Point getVertex(int k)
      As getVertexRaw(int), except the point is normalized to unit length.
    • getVertexRaw

      public S2Point getVertexRaw(int k)
      Returns the kth vertex of the cell (k = 0,1,2,3). Vertices are returned in CCW order (lower left, lower right, upper right, upper left in the UV plane). The points are not necessarily unit length.
    • getEdge

      public S2Point getEdge(int k)
      As getEdgeRaw(int), except the point is normalized to unit length.
    • getEdgeRaw

      public S2Point getEdgeRaw(int k)
      Returns the inward-facing normal of the great circle passing through the edge from vertex k to vertex k+1 (mod 4). The normals returned by getEdgeRaw are not necessarily unit length.
    • getSizeIJ

      public int getSizeIJ()
      As S2CellId.getSizeIJ(int), using the level of this cell.
    • subdivide

      public boolean subdivide(S2Cell[] children)
      Returns true if this is not a leaf cell, in which case the array, which must contain at least four non-null cells in indices 0..3, will be set to the four children of this cell in traversal order. Otherwise, if this is a leaf cell, false is returned without touching the array.

      This method is equivalent to the following:

       for (pos=0, id=childBegin(); !id.equals(childEnd()); id = id.next(), ++pos) {
         children[i].init(id);
       }
       

      except that it is more than two times faster.

    • getCenter

      public S2Point getCenter()
      Return the direction vector corresponding to the center in (s,t)-space of the given cell. This is the point at which the cell is divided into four subcells; it is not necessarily the centroid of the cell in (u,v)-space or (x,y,z)-space. The point returned by GetCenterRaw is not necessarily unit length.
    • getCenterRaw

      public S2Point getCenterRaw()
    • getBoundUV

      public R2Rect getBoundUV()
      Returns the bounds of this cell in (u,v)-space.
    • setBoundUV

      void setBoundUV(R2Rect bound)
      Sets the bounds of this cell in (u,v)-space into 'bound'.

      Package private to avoid leaking object mutation outside the api.

    • getCenterUV

      public R2Vector getCenterUV()
      Return the center of the cell in (u,v) coordinates (see S2Projections). Note that the center of the cell is defined as the point at which it is recursively subdivided into four children; in general, it is not at the midpoint of the (u,v) rectangle covered by the cell
    • averageArea

      public static double averageArea(int level)
      Return the average area in steradians for cells at the given level.
    • averageArea

      public double averageArea()
      Return the average area in steradians of cells at this level. This is accurate to within a factor of 1.7 (for S2_QUADRATIC_PROJECTION) and is extremely cheap to compute.
    • approxArea

      public double approxArea()
      Return the approximate area of this cell in steradians. This method is accurate to within 3% percent for all cell sizes and accurate to within 0.1% for cells at level 5 or higher (i.e. 300km square or smaller). It is moderately cheap to compute.
    • exactArea

      public double exactArea()
      Return the area in steradians of this cell as accurately as possible. This method is more expensive but it is accurate to 6 digits of precision even for leaf cells (whose area is approximately 1e-18).
    • clone

      public S2Region clone()
      Overrides:
      clone in class Object
    • 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
    • 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
    • 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
    • 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
    • vertexChordDist2

      private double vertexChordDist2(S2Point uvw, S2Cell.DoubleBinaryOperator reducer)
    • chordDist2

      private static double chordDist2(S2Point uvw, double u, double v)
      Returns the squared chord distance from uvw to position uv.
    • uEdgeIsClosest

      private boolean uEdgeIsClosest(S2Point p, boolean vEnd)
      Given a point p and either the lower or upper edge of the S2Cell (specified by setting vEnd to false or true respectively), returns true if p is closer to the interior of that edge than it is to either endpoint.
    • vEdgeIsClosest

      private boolean vEdgeIsClosest(S2Point p, boolean uEnd)
      Given a point p and either the left or right edge of the S2Cell (specified by setting uEnd to false or true respectively), returns true if p is closer to the interior of that edge than it is to either endpoint.
    • edgeDistance

      private static double edgeDistance(double dirIJ, double uv)
      Given the dot product of a point P with the normal of a u- or v-edge at the given coordinate value, returns the distance from P to that edge.
    • getDistance

      public S1ChordAngle getDistance(S2Point targetXyz)
      Returns the distance from the given point to the cell. Returns zero if the point is inside the cell.
    • getDistance

      public S1ChordAngle getDistance(S2Cell target)
      Returns the distance to the given cell. Returns zero if one cell contains the other.
    • getDistanceInternal

      private double getDistanceInternal(S2Point targetXyz, boolean toInterior)
      Returns the chord distance to targetXyz, with interior distance 0 iff toInterior is true.
    • getMaxDistance

      public S1ChordAngle getMaxDistance(S2Point target)
      Returns the maximum distance from the cell (including its interior) to the given point.
    • getMaxDistance

      public S1ChordAngle getMaxDistance(S2Point a, S2Point b)
      Returns the maximum distance from the cell (including its interior) to the given edge AB.
    • getMaxDistance

      public S1ChordAngle getMaxDistance(S2Cell target)
      Returns the maximum distance from the cell, including interior, to the given target cell.
    • getDistanceToEdge

      public S1ChordAngle getDistanceToEdge(S2Point a, S2Point b)
      Returns the minimum distance from the cell to the given edge AB, or zero if the edge intersects the cell interior.
    • getBoundaryDistance

      public S1ChordAngle getBoundaryDistance(S2Point target)
      Returns the distance from the cell boundary to the given point.
    • init

      private void init(S2CellId id)
    • getPoint

      private S2Point getPoint(int i, int j)
    • toString

      public String toString()
      Overrides:
      toString in class Object
    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
    • equals

      public boolean equals(Object that)
      Overrides:
      equals in class Object