Package com.google.common.geometry

Class S2CellId

  • All Implemented Interfaces:
    Comparable<S2CellId>
    public final class S2CellId
extends Object
implements Comparable<S2CellId>
    An S2CellId is a 64-bit unsigned integer that uniquely identifies a cell in the S2 cell decomposition. It has the following format: 
     id = [face][face_pos]
    face: a 3-bit number (range 0..5) encoding the cube face. face_pos: a 61-bit number encoding the position of the center of this cell along the Hilbert curve over this face (see the Wiki pages for details). Sequentially increasing cell ids follow a continuous space-filling curve over the entire sphere. They have the following properties: - The id of a cell at level k consists of a 3-bit face number followed by k bit pairs that recursively select one of the four children of each cell. The next bit is always 1, and all other bits are 0. Therefore, the level of a cell is determined by the position of its lowest-numbered bit that is turned on (for a cell at level k, this position is 2 * (MAX_LEVEL - k).) - The id of a parent cell is at the midpoint of the range of ids spanned by its children (or by its descendants at any level). Leaf cells are often used to represent points on the unit sphere, and this class provides methods for converting directly between these two representations. For cells that represent 2D regions rather than discrete point, it is better to use the S2Cell class.

    • Constructor Detail

      • S2CellId

        public S2CellId​(long id)

      • S2CellId

        public S2CellId()

    • Method Detail

      • none

        public static S2CellId none()
        The default constructor returns an invalid cell id.

      • sentinel

        public static S2CellId sentinel()
        Returns an invalid cell id guaranteed to be larger than any valid cell id. Useful for creating indexes.

      • fromFacePosLevel

        public static S2CellId fromFacePosLevel​(int face,
                                        long pos,
                                        int level)
        Return a cell given its face (range 0..5), 61-bit Hilbert curve position within that face, and level (range 0..MAX_LEVEL). 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 give names to the arguments.

      • fromPoint

        public static S2CellId fromPoint​(S2Point p)
        Return the leaf cell containing the given point (a direction vector, not necessarily unit length).

      • fromLatLng

        public static S2CellId fromLatLng​(S2LatLng ll)
        Return the leaf cell containing the given S2LatLng.

      • toPoint

        public S2Point toPoint()

      • toPointRaw

        public S2Point toPointRaw()
        Return the direction vector corresponding to the center of the given cell. The vector returned by ToPointRaw is not necessarily unit length.

      • toLatLng

        public S2LatLng toLatLng()
        Return the S2LatLng corresponding to the center of the given cell.

      • id

        public long id()
        The 64-bit unique identifier for this cell.

      • isValid

        public boolean isValid()
        Return true if id() represents a valid cell.

      • face

        public int face()
        Which cube face this cell belongs to, in the range 0..5.

      • pos

        public long pos()
        The position of the cell center along the Hilbert curve over this face, in the range 0..(2**kPosBits-1).

      • level

        public int level()
        Return the subdivision level of the cell (range 0..MAX_LEVEL).

      • isLeaf

        public boolean isLeaf()
        Return true if this is a leaf cell (more efficient than checking whether level() == MAX_LEVEL).

      • isFace

        public boolean isFace()
        Return true if this is a top-level face cell (more efficient than checking whether level() == 0).

      • childPosition

        public int childPosition​(int level)
        Return the child position (0..3) of this cell's ancestor at the given level, relative to its parent. The argument should be in the range 1..MAX_LEVEL. For example, child_position(1) returns the position of this cell's level-1 ancestor within its top-level face cell.

      • contains

        public boolean contains​(S2CellId other)
        Return true if the given cell is contained within this one.

      • intersects

        public boolean intersects​(S2CellId other)
        Return true if the given cell intersects this one.

      • parent

        public S2CellId parent​(int level)
        Return the cell at the previous level or at the given level (which must be less than or equal to the current level).

      • childBegin

        public S2CellId childBegin()

      • childBegin

        public S2CellId childBegin​(int level)

      • childEnd

        public S2CellId childEnd​(int level)

      • next

        public S2CellId next()
        Return the next cell at the same level along the Hilbert curve. Works correctly when advancing from one face to the next, but does *not* wrap around from the last face to the first or vice versa.

      • prev

        public S2CellId prev()
        Return the previous cell at the same level along the Hilbert curve. Works correctly when advancing from one face to the next, but does *not* wrap around from the last face to the first or vice versa.

      • nextWrap

        public S2CellId nextWrap()
        Like next(), but wraps around from the last face to the first and vice versa. Should *not* be used for iteration in conjunction with child_begin(), child_end(), Begin(), or End().

      • prevWrap

        public S2CellId prevWrap()
        Like prev(), but wraps around from the last face to the first and vice versa. Should *not* be used for iteration in conjunction with child_begin(), child_end(), Begin(), or End().

      • begin

        public static S2CellId begin​(int level)

      • end

        public static S2CellId end​(int level)

      • fromToken

        public static S2CellId fromToken​(String token)
        Decodes the cell id from a compact text string suitable for display or indexing. Cells at lower levels (i.e. larger cells) are encoded into fewer characters. The maximum token length is 16.
        Parameters:
        token - the token to decode
        Returns:
        the S2CellId for that token
        Throws:
        NumberFormatException - if the token is not formatted correctly

      • toToken

        public String toToken()
        Encodes the cell id to compact text strings suitable for display or indexing. Cells at lower levels (i.e. larger cells) are encoded into fewer characters. The maximum token length is 16. Simple implementation: convert the id to hex and strip trailing zeros. We could use base-32 or base-64, but assuming the cells used for indexing regions are at least 100 meters across (level 16 or less), the savings would be at most 3 bytes (9 bytes hex vs. 6 bytes base-64).
        Returns:
        the encoded cell id

      • getEdgeNeighbors

        public void getEdgeNeighbors​(S2CellId[] neighbors)
        Return the four cells that are adjacent across the cell's four edges. Neighbors are returned in the order defined by S2Cell::GetEdge. All neighbors are guaranteed to be distinct.

      • getVertexNeighbors

        public void getVertexNeighbors​(int level,
                               List<S2CellId> output)
        Return the neighbors of closest vertex to this cell at the given level, by appending them to "output". Normally there are four neighbors, but the closest vertex may only have three neighbors if it is one of the 8 cube vertices. Requires: level < this.evel(), so that we can determine which vertex is closest (in particular, level == MAX_LEVEL is not allowed).

      • getAllNeighbors

        public void getAllNeighbors​(int nbrLevel,
                            List<S2CellId> output)
        Append all neighbors of this cell at the given level to "output". Two cells X and Y are neighbors if their boundaries intersect but their interiors do not. In particular, two cells that intersect at a single point are neighbors. Requires: nbr_level >= this->level(). Note that for cells adjacent to a face vertex, the same neighbor may be appended more than once.

      • fromFaceIJ

        public static S2CellId fromFaceIJ​(int face,
                                  int i,
                                  int j)
        Return a leaf cell given its cube face (range 0..5) and i- and j-coordinates (see s2.h).

      • toFaceIJOrientation

        public int toFaceIJOrientation​(MutableInteger pi,
                               MutableInteger pj,
                               MutableInteger orientation)
        Return the (face, i, j) coordinates for the leaf cell corresponding to this cell id. Since cells are represented by the Hilbert curve position at the center of the cell, the returned (i,j) for non-leaf cells will be a leaf cell adjacent to the cell center. If "orientation" is non-NULL, also return the Hilbert curve orientation for the current cell.

      • lowestOnBit

        public long lowestOnBit()
        Return the lowest-numbered bit that is on for cells at the given level.

      • lowestOnBitForLevel

        public static long lowestOnBitForLevel​(int level)
        Return the lowest-numbered bit that is on for this cell id, which is equal to (uint64(1) << (2 * (MAX_LEVEL - level))). So for example, a.lsb() <= b.lsb() if and only if a.level() >= b.level(), but the first test is more efficient.

      • fromFaceIJSame

        public static S2CellId fromFaceIJSame​(int face,
                                      int i,
                                      int j,
                                      boolean sameFace)
        Public helper function that calls FromFaceIJ if sameFace is true, or FromFaceIJWrap if sameFace is false.

      • unsignedLongLessThan

        public static boolean unsignedLongLessThan​(long x1,
                                           long x2)
        Returns true if x1 < x2, when both values are treated as unsigned.

      • unsignedLongGreaterThan

        public static boolean unsignedLongGreaterThan​(long x1,
                                              long x2)
        Returns true if x1 > x2, when both values are treated as unsigned.

      • lessThan

        public boolean lessThan​(S2CellId x)

      • greaterThan

        public boolean greaterThan​(S2CellId x)

      • lessOrEquals

        public boolean lessOrEquals​(S2CellId x)

      • greaterOrEquals

        public boolean greaterOrEquals​(S2CellId x)

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object