Struct S2CellId 

#[repr(C)]
pub struct S2CellId {
    pub id: u64,
}

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 * (K_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 struct 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 struct.

This struct is intended to be copied by value as desired. It uses the default copy constructor and assignment operator.

Usage

Methods that are available:

• S2CellId::new: Create a new S2CellId
• S2CellId::none: Returns an empty cell id.
• S2CellId::sentinel: Returns an invalid cell id guaranteed to be larger than any valid cell id. Useful for creating indexes.
• S2CellId::from_face: Return the cell corresponding to a given S2 cube face.
• S2CellId::from_lon_lat: Construct a leaf cell containing the given normalized S2LatLng.
• S2CellId::from_s2_point: Construct a leaf cell containing the given point “p”.
• S2CellId::from_face_uv: Construct a leaf cell given its face and (u,v) coordinates.
• S2CellId::from_face_st: Construct a leaf cell given its face and (s,t) coordinates.
• S2CellId::from_face_ij: Return a leaf cell given its cube face (range 0..5) and i- and j-coordinates (see s2coords.h).
• S2CellId::from_distance: Given a distance and optional zoom level, construct a cell ID at that distance
• S2CellId::to_face_ij: convert an id to the appropriate face-zoom-i-j of the cell ID
• S2CellId::to_face_ij_orientation: Return the (face, i, j) coordinates for the leaf cell corresponding to this cell id.
• S2CellId::get_edges: Returns the four edges of the cell.
• S2CellId::get_edges_raw: Returns the inward-facing normal of the great circle passing through the edge from vertex k to vertex k+1 (mod 4).
• S2CellId::get_vertices: Returns the four vertices of the cell.
• S2CellId::get_vertices_raw: Returns the k-th vertex of the cell (k = 0,1,2,3).
• S2CellId::get_bound_uv: Return the bounds of this cell in (u,v)-space.
• S2CellId::get_size_ij: Return the size of a cell at the given level.
• S2CellId::child_position: Return the child position (0..3) of this cell’s ancestor at the given level within its parent.
• S2CellId::from_string: Converts a string in the format returned by ToString() to an S2CellId.
• S2CellId::child: Return the immediate child of this cell at the given traversal order position (in the range 0 to 3).
• S2CellId::face: Which cube face this cell belongs to, in the range 0..5.
• S2CellId::pos: The position of the cell center along the Hilbert curve over this face, in the range 0..(2**K_POS_BITS-1).
• S2CellId::level: Return the subdivision level of the cell (range 0..K_MAX_LEVEL).
• S2CellId::is_valid: Return true if id represents a valid cell.
• S2CellId::is_leaf: Return true if this is a leaf cell (more efficient than checking whether level() == K_MAX_LEVEL).
• S2CellId::to_point_raw: Convert an S2CellID to an S2Point in normalized vector coordinates
• S2CellId::to_point: Convert an S2CellID to an S2Point in normalized vector coordinates
• S2CellId::to_st: Convert an S2CellID to an Face-S-T coordinate
• S2CellId::to_uv: Convert an S2CellID to an Face-U-V coordinate
• S2CellId::is_face: Given an S2CellID, check if it is a Face Cell.
• S2CellId::distance: Given an S2CellID, get the distance it spans (or length it covers)
• S2CellId::children: Given an S2CellID, get all the quad children tiles
• S2CellId::children_ij: Given an S2CellID, get the quad children tiles using a face-zoom-ij input
• S2CellId::parent: Given an S2CellID, get the parent quad tile
• S2CellId::range: Given an S2CellID, get the hilbert range it spans returns (min, max)
• S2CellId::contains: Check if the first S2CellID contains the second.
• S2CellId::contains_s2point: Check if an S2CellID contains an S2Point
• S2CellId::intersects: Check if an S2CellID intersects another. This includes edges touching.
• S2CellId::lsb: Return the lowest-numbered bit that is on for this cell id
• S2CellId::next: Get the next S2CellID in the hilbert space
• S2CellId::prev: Get the previous S2CellID in the hilbert space
• S2CellId::center_st: Given an S2CellID and level (zoom), get the center point of that cell in S-T space returns (face, s, t)
• S2CellId::bounds_st: Given an S2CellID and level (zoom), get the S-T bounding range of that cell returns (s_min, t_min, s_max, t_max)
• S2CellId::neighbors: Given an S2CellID, find the edge neighboring S2CellIDs returns neighbors: [up, right, down, left]
• S2CellId::neighbors_ij: Given a Face-I-J and a desired level (zoom), find the neighboring S2CellIDs return neighbors: [down, right, up, left]
• S2CellId::from_ij_same: Build an S2CellID given a Face-I-J, but ensure the face is the same if desired
• S2CellId::from_face_ij_wrap: Build an S2CellID given a Face-I-J, but ensure it’s a legal value, otherwise wrap before creation
• S2CellId::vertex_neighbors: Given an S2CellID, find it’s nearest neighbors associated with it
• S2CellId::low_bits: Return the low 32 bits of the cell id
• S2CellId::high_bits: Return the high 32 bits of the cell id

Fields

id: u64

the id contains the face, s, and t components

Implementations

impl S2CellId

pub fn new(id: u64) -> Self

Construct a cell id from the given 64-bit integer.

pub fn none() -> Self

Returns an empty cell id.

pub fn sentinel() -> Self

Returns an invalid cell id guaranteed to be larger than any valid cell id. Useful for creating indexes.

pub fn from_face(face: u8) -> S2CellId

Return the cell corresponding to a given S2 cube face.

pub fn from_lon_lat<M: Clone + Default>(ll: &LonLat<M>) -> S2CellId

Construct a leaf cell containing the given normalized S2LatLng.

pub fn from_s2_point(p: &S2Point) -> Self

Construct a leaf cell containing the given 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 S2CellIds are considered to be closed sets. The returned cell will always contain the given point, i.e.

S2Cell(S2CellId(p)).contains(p)

is always true. The point “p” does not need to be normalized.

If instead you want every point to be contained by exactly one S2Cell, you will need to convert the S2CellIds to S2Loops (which implement point containment this way).

pub fn from_face_uv(face: u8, u: f64, v: f64) -> Self

Construct a leaf cell given its face and (u,v) coordinates.

pub fn from_face_st(face: u8, s: f64, t: f64) -> Self

Construct a leaf cell given its face and (s,t) coordinates.

pub fn from_face_ij(face: u8, i: u32, j: u32, level: Option<u8>) -> S2CellId

Return a leaf cell given its cube face (range 0..5) and i- and j-coordinates (see s2coords.h).

pub fn from_distance(distance: u64, level: Option<u8>) -> S2CellId

Given a distance and optional zoom level, construct a cell ID at that distance

pub fn to_face_ij(&self) -> (u8, u8, u32, u32)

convert an id to the appropriate face-zoom-i-j of the cell ID

NOTE: This is an adjusted IJ to the zoom level

pub fn to_face_ij_orientation(&self, level: Option<u8>) -> (u8, u32, u32, u8)

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-nullptr, also return the Hilbert curve orientation for the current cell. Returns (face, i, j, orientation)

pub fn get_edges(&self) -> [S2Point; 4]

Returns the four edges of the cell. Edges are returned in CCW order (lower left, lower right, upper right, upper left in the UV plane).

pub fn get_edges_raw(&self) -> [S2Point; 4]

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 getEdgesRaw are not necessarily unit length.

pub fn get_vertices(&self) -> [S2Point; 4]

Returns the four vertices of the cell. Vertices are returned in CCW order (lower left, lower right, upper right, upper left in the UV plane). The points returned by getVerticesRaw are not normalized.

pub fn get_vertices_raw(&self) -> [S2Point; 4]

Returns the k-th 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 returned by getVerticesRaw are not normalized.

pub fn get_bound_uv(&self) -> BBox

Return the bounds of this cell in (u,v)-space.

pub fn get_size_ij(&self) -> u64

Return the size of a cell at the given level.

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

Return the child position (0..3) of this cell’s ancestor at the given level within its parent. For example, childPosition(1) returns the position of this cell’s level-1 ancestor within its top-level face cell. REQUIRES: 1 <= level <= this->level().

pub fn from_string(val: &str) -> S2CellId

Converts a string in the format returned by ToString() to an S2CellId. Returns S2CellId.None() if the string could not be parsed.

The method name includes “Debug” in order to avoid possible confusion with FromToken() above.

pub fn child(&self, position: u8) -> S2CellId

Return the immediate child of this cell at the given traversal order position (in the range 0 to 3). This cell must not be a leaf cell.

pub fn face(&self) -> u8

Which cube face this cell belongs to, in the range 0..5.

pub fn pos(&self) -> u64

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

pub fn level(&self) -> u8

Return the subdivision level of the cell (range 0..K_MAX_LEVEL).

pub fn is_valid(&self) -> bool

Return true if id represents a valid cell.

All methods require isValid() to be true unless otherwise specified (although not all methods enforce this).

pub fn is_leaf(&self) -> bool

Return true if this is a leaf cell (more efficient than checking whether level() == K_MAX_LEVEL).

pub fn to_point_raw(&self) -> S2Point

Convert an S2CellID to an S2Point in normalized vector coordinates

pub fn to_point(&self) -> S2Point

Convert an S2CellID to an S2Point in normalized vector coordinates

pub fn to_st(&self) -> (u8, f64, f64)

Convert an S2CellID to an Face-S-T coordinate Returns (face, s, t)

pub fn to_uv(&self) -> (u8, f64, f64)

Convert an S2CellID to an Face-U-V coordinate Returns (face, u, v)

pub fn is_face(&self) -> bool

Given an S2CellID, check if it is a Face Cell.

pub fn distance(&self, lev: Option<u8>) -> f64

Given an S2CellID, get the distance it spans (or length it covers)

pub fn children(&self, orientation: Option<u8>) -> [S2CellId; 4]

Given an S2CellID, get all the quad children tiles

pub fn children_ij(face: u8, level: u8, i: u32, j: u32) -> [S2CellId; 4]

Given an S2CellID, get the quad children tiles using a face-zoom-ij input

pub fn parent(&self, level: Option<u8>) -> S2CellId

Given an S2CellID, get the parent quad tile

pub fn range(&self) -> (Self, Self)

Given an S2CellID, get the hilbert range it spans returns (min, max)

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

Check if the first S2CellID contains the second.

pub fn contains_s2point(&self, p: &S2Point) -> bool

Check if an S2CellID contains an S2Point

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

Check if an S2CellID intersects another. This includes edges touching.

pub fn lsb(&self) -> u64

Return the lowest-numbered bit that is on for this cell id, which is equal to (uint64_t{1} << (2 * (kMaxLevel - level))). So for example, a.lsb() <= b.lsb() if and only if a.level() >= b.level(), but the first test is more efficient.

pub fn next(&self) -> S2CellId

Get the next S2CellID in the hilbert space

pub fn prev(&self) -> S2CellId

Get the previous S2CellID in the hilbert space

pub fn center_st(&self) -> (u8, f64, f64)

Given an S2CellID and level (zoom), get the center point of that cell in S-T space returns (face, s, t)

pub fn bounds_st(&self, level: Option<u8>) -> BBox

Given an S2CellID and level (zoom), get the S-T bounding range of that cell returns (s_min, t_min, s_max, t_max)

pub fn neighbors(&self) -> [S2CellId; 4]

Given an S2CellID, find the edge neighboring S2CellIDs returns neighbors: [up, right, down, left]

pub fn neighbors_ij(face: u8, i: u32, j: u32, level: u8) -> [S2CellId; 4]

Given a Face-I-J and a desired level (zoom), find the neighboring S2CellIDs return neighbors: [down, right, up, left]

pub fn from_ij_same(face: u8, i: i32, j: i32, same_face: bool) -> S2CellId

Build an S2CellID given a Face-I-J, but ensure the face is the same if desired

pub fn from_face_ij_wrap(face: u8, i: i32, j: i32) -> S2CellId

Build an S2CellID given a Face-I-J, but ensure it’s a legal value, otherwise wrap before creation

pub fn vertex_neighbors(&self, level: Option<u8>) -> Vec<S2CellId>

Given an S2CellID, find it’s nearest neighbors associated with it

pub fn low_bits(&self) -> u32

Return the low 32 bits of the cell id

pub fn high_bits(&self) -> u32

Return the high 32 bits of the cell id

pub fn is_out_of_bounds_wm(&self) -> bool

Check if the tile is not a real world tile that fits inside a WM quad tree Out of bounds tiles exist if the map has duplicateHorizontally set to true. This is useful for filling in the canvas on the x axis instead of leaving it blank.

Parameters

• id: a tile ID

Returns

true if the id is out of bounds for WM

Methods from Deref<Target = u64>

pub const MIN: u64 = 0u64

pub const MAX: u64 = 18_446_744_073_709_551_615u64

pub const BITS: u32 = 64u32

Trait Implementations

impl Clone for S2CellId

fn clone(&self) -> S2CellId

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for S2CellId

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

Formats the value using the given formatter.

impl Default for S2CellId

fn default() -> S2CellId

Returns the “default value” for a type.

impl Deref for S2CellId

type Target = u64

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'de> Deserialize<'de> for S2CellId

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for S2CellId

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

Creates a human readable debug string. Used for << and available for direct usage as well. The format is “f/dd..d” where “f” is a digit in the range [0-5] representing the S2CellId face, and “dd..d” is a string of digits in the range [0-3] representing each child’s position with respect to its parent. (Note that the latter string may be empty.)

For example “4/” represents S2CellId::from_face(4), and “3/02” represents S2CellId::from_face(3).child(0).child(2).

impl<M: Clone + Default> From<&LonLat<M>> for S2CellId

fn from(value: &LonLat<M>) -> Self

Converts to this type from the input type.

impl From<&S2Point> for S2CellId

fn from(value: &S2Point) -> Self

Converts to this type from the input type.

impl<M: Clone + Default> From<&VectorPoint<M>> for S2CellId

fn from(value: &VectorPoint<M>) -> Self

Converts to this type from the input type.

impl From<&str> for S2CellId

fn from(s: &str) -> Self

Converts to this type from the input type.

impl From<&u64> for S2CellId

fn from(value: &u64) -> Self

Converts to this type from the input type.

impl<M: Clone + Default> From<S2CellId> for LonLat<M>

fn from(c: S2CellId) -> Self

Converts to this type from the input type.

impl From<S2CellId> for S2Point

fn from(cellid: S2CellId) -> Self

Converts to this type from the input type.

impl From<S2CellId> for u64

fn from(val: S2CellId) -> Self

Converts to this type from the input type.

impl From<String> for S2CellId

fn from(s: String) -> Self

Converts to this type from the input type.

impl From<u64> for S2CellId

fn from(value: u64) -> Self

Converts to this type from the input type.

impl Hash for S2CellId

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, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for S2CellId

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

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

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

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for S2CellId

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for S2CellId

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

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl Serialize for S2CellId

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Copy for S2CellId

impl Eq for S2CellId

impl StructuralPartialEq for S2CellId

impl U64 for S2CellId