Struct s2::cellid::CellID

pub struct CellID(pub u64);

CellID uniquely identifies a cell in the S2 cell decomposition. The most significant 3 bits encode the face number (0-5). The remaining 61 bits encode the position of the center of this cell along the Hilbert curve on that face. The zero value and the value (1<<64)-1 are invalid cell IDs. The first compares less than any valid cell ID, the second as greater than any valid cell ID.

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 * (maxLevel - 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 type provides methods for converting directly between these two representations. For cells that represent 2D regions rather than discrete point, it is better to use Cells.

Methods

impl CellID

pub fn from_face_pos_level(face: u64, pos: u64, level: u64) -> Self

from_pos_level returns a cell given its face in the range [0,5], the 61-bit Hilbert curve position pos within that face, and the level in the range [0,maxLevel]. The position in the cell ID will be truncated to correspond to the Hilbert curve position at the center of the returned cell.

pub fn from_face(face: u64) -> Self

from_face returns the cell corresponding to a given S2 cube face.

pub fn from_face_ij(f: u8, i: i32, j: i32) -> Self

pub fn from_token(s: &str) -> CellID

from_token returns a cell given a hex-encoded string of its uint64 ID.

pub fn to_token(&self) -> String

to_token returns a hex-encoded string of the uint64 cell id, with leading zeros included but trailing zeros stripped.

pub fn is_valid(&self) -> bool

is_valid reports whether ci represents a valid cell.

pub fn face(&self) -> u8

face returns the cube face for this cell ID, in the range [0,5].

pub fn pos(&self) -> u64

pos returns the position along the Hilbert curve of this cell ID, in the range [0,2^posBits-1].

pub fn level(&self) -> u64

level returns the subdivision level of this cell ID, in the range [0, maxLevel].

pub fn is_leaf(&self) -> bool

is_leaf returns whether this cell ID is at the deepest level; that is, the level at which the cells are smallest.

pub fn child_position(&self, level: u64) -> u64

child_position returns 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..kMaxLevel. For example, ChildPosition(1) returns the position of this cell's level-1 ancestor within its top-level face cell.

pub fn parent(&self, level: u64) -> Self

parent returns the cell at the given level, which must be no greater than the current level.

pub fn immediate_parent(&self) -> Self

immediate_parent is cheaper than Parent, but assumes !ci.isFace().

pub fn is_face(&self) -> bool

is_face returns whether this is a top-level (face) cell.

pub fn lsb(&self) -> u64

lsb returns the least significant bit that is set.

pub fn children(&self) -> [CellID; 4]

children returns the four immediate children of this cell. If ci is a leaf cell, it returns four identical cells that are not the children.

pub fn face_ij_orientation(&self) -> (u8, i32, i32, u8)

face_ij_orientation uses the global lookupIJ table to unfiddle the bits of ci.

pub fn edge_neighbors(&self) -> [CellID; 4]

edge_neighbors returns the four cells that are adjacent across the cell's four edges. Edges 0, 1, 2, 3 are in the down, right, up, left directions in the face space. All neighbors are guaranteed to be distinct.

pub fn vertex_neighbors(&self, level: u64) -> Vec<CellID>

vertex_neighbors returns the neighboring cellIDs with vertex closest to this cell at the given level. (Normally there are four neighbors, but the closest vertex may only have three neighbors if it is one of the 8 cube vertices.)

pub fn all_neighbors(&self, level: u64) -> Vec<CellID>

all_neighbors returns all neighbors of this cell at the given level. 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. Note that for cells adjacent to a face vertex, the same neighbor may be returned more than once. There could be up to eight neighbors including the diagonal ones that share the vertex.

This requires level >= ci.Level().

pub fn range_min(&self) -> Self

range_min returns the minimum CellID that is contained within this cell.

pub fn range_max(&self) -> Self

range_max returns the maximum CellID that is contained within this cell.

pub fn contains(&self, other: &CellID) -> bool

contains returns true iff the CellID contains oci.

pub fn intersects(&self, other: &CellID) -> bool

intersects returns true iff the CellID intersects oci.

pub fn raw_point(&self) -> Vector

pub fn child_begin(&self) -> Self

child_begin returns the first child in a traversal of the children of this cell, in Hilbert curve order.

pub fn child_begin_at_level(&self, level: u64) -> Self

child_begin_at_level returns the first cell in a traversal of children a given level deeper than this cell, in Hilbert curve order. The given level must be no smaller than the cell's level. See ChildBegin for example use.

pub fn child_end(&self) -> Self

child_end returns the first cell after a traversal of the children of this cell in Hilbert curve order. The returned cell may be invalid.

pub fn child_end_at_level(&self, level: u64) -> Self

child_end_at_level returns the first cell after the last child in a traversal of children a given level deeper than this cell, in Hilbert curve order. The given level must be no smaller than the cell's level. The returned cell may be invalid.

pub fn next(&self) -> Self

next returns the next cell along the Hilbert curve. This is expected to be used with child_begin and child_end, or child_begin_at_level and child_end_at_level.

pub fn prev(&self) -> Self

prev returns the previous cell along the Hilbert curve.

pub fn next_wrap(&self) -> Self

next_wrap returns the next cell along the Hilbert curve, wrapping from last to first as necessary. This should not be used with ChildBegin and ChildEnd.

pub fn prev_wrap(&self) -> Self

prev_wrap returns the previous cell along the Hilbert curve, wrapping around from first to last as necessary. This should not be used with ChildBegin and ChildEnd.

pub fn advance_wrap(&self, steps: i64) -> Self

advance_wrap advances or retreats the indicated number of steps along the Hilbert curve at the current level and returns the new position. The position wraps between the first and last faces as necessary.

pub fn distance_from_begin(&self) -> i64

distance_from_begin returns the number of steps that this cell is from the first node in the S2 heirarchy at our level. (i.e., FromFace(0).ChildBeginAtLevel(ci.Level())). The return value is always non-negative.

pub fn common_ancestor_level(&self, other: &Self) -> Option<u64>

common_ancestor_level returns the level of the common ancestor of the two S2 CellIDs.

pub fn advance(&self, steps: i64) -> Self

advance advances or retreats the indicated number of steps along the Hilbert curve at the current level, and returns the new position. The position is never advanced past End() or before Begin().

pub fn bound_st(&self) -> Rect

bound_st returns the bound of this CellID in (s,t)-space.

pub fn center_uv(&self) -> Point

center_uv returns the center of this CellID in (u,v)-space. 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.

pub fn bound_uv(&self) -> Rect

bound_uv returns the bound of this CellID in (u,v)-space.

pub fn max_tile(&self, limit: &Self) -> Self

max_tile returns the largest cell with the same range_min such that range_max < limit.range_min. It returns limit if no such cell exists. This method can be used to generate a small set of CellIDs that covers a given range (a tiling). This example shows how to generate a tiling for a semi-open range of leaf cells [start, limit):

for id := start.MaxTile(limit); id != limit; id = id.Next().MaxTile(limit)) { ... }

Note that in general the cells in the tiling will be of different sizes; they gradually get larger (near the middle of the range) and then gradually get smaller as limit is approached.

pub fn center_face_siti(&self) -> (u8, i32, i32)

center_face_siti returns the (face, si, ti) coordinates of the center of the cell. Note that although (si,ti) coordinates span the range [0,231] in general, the cell center coordinates are always in the range [1,231-1] and therefore can be represented using a signed 32-bit integer.

impl CellID

Important traits for Iter

impl Iterator for Iter type Item = CellID;

pub fn child_iter(&self) -> Iter

Important traits for Iter

impl Iterator for Iter type Item = CellID;

pub fn child_iter_at_level(&self, level: u64) -> Iter

Trait Implementations

impl Ord for CellID

fn cmp(&self, other: &CellID) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl Clone for CellID

fn clone(&self) -> CellID

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Eq for CellID

impl<'a> From<&'a CellID> for Cell

fn from(id: &'a CellID) -> Self

Performs the conversion.

impl From<CellID> for Cell

fn from(id: CellID) -> Self

Performs the conversion.

impl<'a> From<&'a Cell> for CellID

fn from(c: &'a Cell) -> Self

Performs the conversion.

impl From<Cell> for CellID

fn from(c: Cell) -> Self

Performs the conversion.

impl From<CellID> for Point

fn from(id: CellID) -> Self

returns the center of the s2 cell on the sphere as a Point. The maximum directional error in Point (compared to the exact mathematical result) is 1.5 * dblEpsilon radians, and the maximum length error is 2 * dblEpsilon (the same as Normalize).

impl<'a> From<&'a CellID> for Point

fn from(id: &'a CellID) -> Self

cellIDFromPoint returns a leaf cell containing point p. Usually there is exactly one such cell, but for points along the edge of a cell, any adjacent cell may be (deterministically) chosen. This is because s2.CellIDs are considered to be closed sets. The returned cell will always contain the given point, i.e.

Cell::from(&p).contains_point(&p)

is always true.

impl From<CellID> for LatLng

fn from(id: CellID) -> Self

returns the center of the s2 cell on the sphere as a LatLng.

impl<'a> From<&'a CellID> for LatLng

fn from(id: &'a CellID) -> Self

Performs the conversion.

impl From<LatLng> for CellID

fn from(ll: LatLng) -> Self

Performs the conversion.

impl<'a> From<&'a LatLng> for CellID

fn from(ll: &'a LatLng) -> Self

Performs the conversion.

impl<'a> From<&'a Point> for CellID

fn from(p: &'a Point) -> Self

Performs the conversion.

impl From<Point> for CellID

fn from(p: Point) -> Self

Performs the conversion.

impl Copy for CellID

impl PartialEq<CellID> for CellID

fn eq(&self, other: &CellID) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &CellID) -> bool

This method tests for !=.

impl PartialOrd<CellID> for CellID

fn partial_cmp(&self, other: &CellID) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &CellID) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &CellID) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &CellID) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &CellID) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Hash for CellID

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl Debug for CellID

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.