Class S2Cell

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

    @GwtCompatible(serializable=true)
    public final class S2Cell
    extends java.lang.Object
    implements S2Region, java.io.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:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      (package private) S2CellId cellId  
      (package private) byte face  
      (package private) byte level  
      (package private) byte orientation  
      private static double POLE_MIN_LAT
      The 4 cells around the equator extend to +/-45 degrees latitude at the midpoints of their top and bottom edges.
      (package private) double uMax  
      (package private) double uMin  
      (package private) double vMax  
      (package private) double vMin  
    • Constructor Summary

      Constructors 
      Constructor Description
      S2Cell()
      Default constructor used only internally.
      S2Cell​(S2CellId id)
      An S2Cell always corresponds to a particular S2CellId.
      S2Cell​(S2LatLng ll)  
      S2Cell​(S2Point p)  
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      double approxArea()
      Return the approximate area of this cell in steradians.
      double averageArea()
      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.
      S2Region clone()  
      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.
      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​(java.lang.Object that)  
      double exactArea()
      Return the area in steradians of this cell as accurately as possible.
      int face()  
      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).
      S1ChordAngle getBoundaryDistance​(S2Point target)
      Returns the distance from the cell boundary to the given point.
      R2Rect getBoundUV()
      Returns the bounds of this cell in (u,v)-space.
      S2Cap getCapBound()
      Return a bounding spherical cap.
      S2Point getCenter()
      Return the direction vector corresponding to the center in (s,t)-space of the given cell.
      S2Point getCenterRaw()  
      R2Vector getCenterUV()
      Return the center of the cell in (u,v) coordinates (see S2Projections).
      S1ChordAngle getDistance​(S2Cell target)
      Returns the distance to the given cell.
      S1ChordAngle 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.
      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.
      S2Point getEdge​(int k)
      As getEdgeRaw(int), except the point is normalized to unit length.
      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).
      S1ChordAngle getMaxDistance​(S2Cell target)
      Returns the maximum distance from the cell, including interior, to the given target cell.
      S1ChordAngle getMaxDistance​(S2Point target)
      Returns the maximum distance from the cell (including its interior) to the given point.
      S1ChordAngle getMaxDistance​(S2Point a, S2Point b)
      Returns the maximum distance from the cell (including its interior) to the given edge AB.
      private S2Point getPoint​(int i, int j)  
      S2LatLngRect getRectBound()
      Return a bounding latitude-longitude rectangle.
      int getSizeIJ()
      As S2CellId.getSizeIJ(int), using the level of this cell.
      S2Point getVertex​(int k)
      As getVertexRaw(int), except the point is normalized to unit length.
      S2Point getVertexRaw​(int k)
      Returns the kth vertex of the cell (k = 0,1,2,3).
      int hashCode()  
      S2CellId id()  
      private void init​(S2CellId id)  
      boolean isLeaf()
      Returns true if this cell is a leaf-cell, i.e.
      byte level()  
      boolean mayIntersect​(S2Cell cell)
      If this method returns false, the region does not intersect the given cell.
      byte orientation()  
      (package private) void setBoundUV​(R2Rect bound)
      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.
      java.lang.String toString()  
      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 vertexChordDist2​(S2Point uvw, S2Cell.DoubleBinaryOperator reducer)  
      • Methods inherited from class java.lang.Object

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

      • face

        byte face
      • level

        byte level
      • orientation

        byte orientation
      • 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 Detail

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

      • 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.
      • 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.
      • 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.
      • 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 java.lang.Object
      • getCapBound

        public S2Cap getCapBound()
        Description copied from interface: S2Region
        Return a bounding spherical cap.
        Specified by:
        getCapBound 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
      • 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 java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • hashCode

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

        public boolean equals​(java.lang.Object that)
        Overrides:
        equals in class java.lang.Object