Struct h3o::CellIndex

pub struct CellIndex(/* private fields */);

Represents a cell (hexagon or pentagon) in the H3 grid system at a particular resolution.

The index is encoded on 64-bit with the following bit layout:

 ┏━┳━━━┳━━━━┳━━━━┳━━━━━━━┳━━━┳━━━┳━┈┈┈┈┈┈┈┈━┳━━━┳━━━┓
 ┃U┃ M ┃ U  ┃ R  ┃ B     ┃C₀ ┃C₁ ┃          ┃C₁₄┃C₁₅┃
 ┗━┻━━━┻━━━━┻━━━━┻━━━━━━━┻━━━┻━━━┻━┈┈┈┈┈┈┈┈━┻━━━┻━━━┛
64 63 59   56   52      45  42  39          6   3   0

Where:

• U are unused reserved bit, always set to 0 (bit 63 and bits 56-58).
• M is the index mode, always set to 1, coded on 4 bits (59-62).
• R is the cell resolution, in [0; 15], coded on 4 bits (52-55).
• B is the base cell, in [0; 121], coded on 7 bits (45-51)
• C are cells, coded on 3 bits each, with either a value in [0; 6] or the pattern 0b111 if unused.

References:

• H3 Index Representations
• H3 Index Bit Layout
• H3 Index Inspector

Implementations

impl CellIndex

pub const fn resolution(self) -> Resolution

Returns the resolution of the index.

Example

let index = h3o::CellIndex::try_from(0x8a1fb46622dffff)?;
assert_eq!(index.resolution(), h3o::Resolution::Ten);

pub const fn base_cell(self) -> BaseCell

Returns the base cell of the index.

Example

let index = h3o::CellIndex::try_from(0x8a1fb46622dffff)?;
assert_eq!(index.base_cell(), h3o::BaseCell::try_from(15)?);

pub fn area_rads2(self) -> f64

Computes the area of this H3 cell, in radians².

Example

let index = h3o::CellIndex::try_from(0x8a1fb46622dffff)?;
assert_eq!(index.area_rads2(), 3.3032558516982826e-10);

pub fn area_km2(self) -> f64

Computes the area of this H3 cell, in km².

Example

let index = h3o::CellIndex::try_from(0x8a1fb46622dffff)?;
assert_eq!(index.area_km2(), 0.013407827139722947);

pub fn area_m2(self) -> f64

Computes the area of this H3 cell, in m².

Example

let index = h3o::CellIndex::try_from(0x8a1fb46622dffff)?;
assert_eq!(index.area_m2(), 13407.827139722947);

pub fn icosahedron_faces(self) -> FaceSet

Finds all icosahedron faces intersected this cell index

Example

let index = h3o::CellIndex::try_from(0x8a1fb46622dffff)?;
let faces = index.icosahedron_faces().iter().collect::<Vec<_>>();

pub fn is_pentagon(self) -> bool

Returns true if this index represents a pentagonal cell.

Example

let index = h3o::CellIndex::try_from(0x8a1fb46622dffff)?;
assert!(!index.is_pentagon());

pub fn max_face_count(self) -> usize

Returns the maximum number of icosahedron faces the index may intersect.

Example

let index = h3o::CellIndex::try_from(0x8a1fb46622dffff)?;
assert_eq!(index.max_face_count(), 2);

pub fn direction_at(self, resolution: Resolution) -> Option<Direction>

Returns the cell at the given resolution in the index, if any.

Example

use h3o::{CellIndex, Direction, Resolution};

let index = CellIndex::try_from(0x8a1fb46622dffff)?;
assert_eq!(index.direction_at(Resolution::Five), Some(Direction::K));

pub fn parent(self, resolution: Resolution) -> Option<Self>

Returns the parent, at the specified resolution, of the cell.

Example

use h3o::{CellIndex, Resolution};

let index = CellIndex::try_from(0x8a1fb46622dffff)?;
assert_eq!(
    index.parent(Resolution::Five),
    CellIndex::try_from(0x851fb467fffffff).ok()
);

pub fn center_child(self, resolution: Resolution) -> Option<Self>

Returns the center child index at the specified resolution.

Example

use h3o::{CellIndex, Resolution};

let index = CellIndex::try_from(0x8a1fb46622dffff)?;
assert_eq!(
    index.center_child(Resolution::Fifteen),
    CellIndex::try_from(0x8f1fb46622d8000).ok()
);

pub fn children_count(self, resolution: Resolution) -> u64

Returns the exact number of children for a cell at a given resolution.

Example

use h3o::{CellIndex, Resolution};

let index = CellIndex::try_from(0x8a1fb46622dffff)?;
assert_eq!(index.children_count(Resolution::Fifteen), 16_807);

pub fn child_position(self, resolution: Resolution) -> Option<u64>

Returns the position of the cell within an ordered list of all children of the cell’s parent at the specified resolution.

Returns None if the cell’s resolution is coarser than the given resolution.

Example

use h3o::{CellIndex, Resolution};

let index = CellIndex::try_from(0x8a1fb46622dffff)?;
assert_eq!(index.child_position(Resolution::Eight), Some(24));
assert_eq!(index.child_position(Resolution::Twelve), None);

pub fn child_at(self, position: u64, resolution: Resolution) -> Option<Self>

Returns the child cell at a given position within an ordered list of all children at the specified resolution.

Returns None if no child can be found (coarser resolution, index out of bound, …).

Example

use h3o::{CellIndex, Resolution};

let index = CellIndex::try_from(0x881fb46623fffff)?;
assert_eq!(
    index.child_at(24, Resolution::Ten),
    CellIndex::try_from(0x8a1fb46622dffff).ok(),
);
assert_eq!(index.child_at(24, Resolution::Five), None);

pub fn children(self, resolution: Resolution) -> impl Iterator<Item = Self>

Return the children, at the specified resolution, of the cell index.

Example

use h3o::{CellIndex, Resolution};

let index = CellIndex::try_from(0x8a1fb46622dffff)?;
let children = index.children(Resolution::Eleven).collect::<Vec<_>>();

pub fn compact( indexes: impl IntoIterator<Item = Self> ) -> Result<impl Iterator<Item = Self>, CompactionError>

Compresses a set of unique cell indexes all at the same resolution.

The indexes are compressed by pruning full child branches to the parent level. This is also done for all parents recursively to get the minimum number of hex addresses that perfectly cover the defined space.

Errors

All cell indexes must be unique and have the same resolution, otherwise an CompactionError is returned.

Example

use h3o::CellIndex;

let cells = [
    0x081003ffffffffff,
    0x081023ffffffffff,
    0x081043ffffffffff,
    0x081063ffffffffff,
    0x081083ffffffffff,
    0x0810a3ffffffffff,
    0x0810c3ffffffffff,
]
.into_iter()
.map(|hex| CellIndex::try_from(hex))
.collect::<Result<Vec<_>, _>>()?;
let compacted_cells = CellIndex::compact(cells)?.collect::<Vec<_>>();

pub fn uncompact_size( compacted: impl IntoIterator<Item = Self>, resolution: Resolution ) -> u64

Computes the exact size of the uncompacted set of cells.

Example

use h3o::{CellIndex, Resolution};

let index = CellIndex::try_from(0x8a1fb46622dffff)?;
let size = CellIndex::uncompact_size(std::iter::once(index), Resolution::Eleven);

pub fn uncompact( compacted: impl IntoIterator<Item = Self>, resolution: Resolution ) -> impl Iterator<Item = Self>

Expands a compressed set of cells into a set of cells of the specified resolution.

Example

use h3o::{CellIndex, Resolution};

let index = CellIndex::try_from(0x8a1fb46622dffff)?;
let cells = CellIndex::uncompact(
    std::iter::once(index), Resolution::Eleven
).collect::<Vec<_>>();

pub fn boundary(self) -> Boundary

Computes the cell boundary, in spherical coordinates, of this index.

Example

let index = h3o::CellIndex::try_from(0x8a1fb46622dffff)?;
let boundary = index.boundary().iter().collect::<Vec<_>>();

pub fn base_cells() -> impl Iterator<Item = Self>

Returns all the base cell indexes.

Example

let cells = h3o::CellIndex::base_cells().collect::<Vec<_>>();

pub fn edge(self, destination: Self) -> Option<DirectedEdgeIndex>

Returns the edge between the current cell and the specified destination.

Example

use h3o::{CellIndex, Direction, DirectedEdgeIndex};

let src = CellIndex::try_from(0x8a1fb46622dffff)?;
let dst = CellIndex::try_from(0x8a1fb46622d7fff)?;
assert_eq!(src.edge(dst), DirectedEdgeIndex::try_from(0x16a1fb46622dffff).ok());

// Not a neighbor, thus no shared edge.
let dst = CellIndex::try_from(0x8a1fb4644937fff)?;
assert!(src.edge(dst).is_none());

pub fn edges(self) -> impl Iterator<Item = DirectedEdgeIndex>

Returns all of the directed edges from the current index.

Example

let index = h3o::CellIndex::try_from(0x8a1fb46622dffff)?;
let edges = index.edges().collect::<Vec<_>>();

pub fn vertex(self, vertex: Vertex) -> Option<VertexIndex>

Get the specified vertex of this cell.

Example

use h3o::{CellIndex, Vertex, VertexIndex};

let index = CellIndex::try_from(0x8a1fb46622dffff)?;
assert_eq!(
    index.vertex(Vertex::try_from(3)?),
    VertexIndex::try_from(0x25a1fb464492ffff).ok()
);

pub fn vertexes(self) -> impl Iterator<Item = VertexIndex>

Returns all vertexes for the current cell.

Example

let index = h3o::CellIndex::try_from(0x8a1fb46622dffff)?;
let vertexes = index.vertexes().collect::<Vec<_>>();

pub fn grid_disk<T>(self, k: u32) -> T

where T: FromIterator<Self>,

Produce cells within grid distance k of the cell.

This function is a convenience helper that tries Self::grid_disk_fast first and then fallback on Self::grid_disk_safe if the former fails.

Example

let index = h3o::CellIndex::try_from(0x8a1fb46622dffff)?;
let cells = index.grid_disk::<Vec<_>>(2);

pub fn grid_disk_safe(self, k: u32) -> impl Iterator<Item = Self>

Safe but slow version of Self::grid_disk_fast.

Example

let index = h3o::CellIndex::try_from(0x8a1fb46622dffff)?;
let cells = index.grid_disk_safe(2).collect::<Vec<_>>();

pub fn grid_disk_fast(self, k: u32) -> impl Iterator<Item = Option<Self>>

Produces indexes within grid distance k of the cell.

0-ring is defined as the current cell, 1-ring is defined as 0-ring and all neighboring indexes, and so on.

This function fails (i.e. returns a None item) when a pentagon (or a pentagon distortion) is encountered. When this happen, the previously returned cells should be treated as invalid and discarded.

Example

let index = h3o::CellIndex::try_from(0x8a1fb46622dffff)?;
let cells = index.grid_disk_fast(2).collect::<Option<Vec<_>>>()
    .unwrap_or_default();

pub fn grid_disk_distances<T>(self, k: u32) -> T

where T: FromIterator<(Self, u32)>,

Produce cells and their distances from the current cell, up to distance k.

This function is a convenience helper that tries Self::grid_disk_distances_fast first and then fallback on Self::grid_disk_distances_safe if the former fails.

Example

let index = h3o::CellIndex::try_from(0x8a1fb46622dffff)?;
let cells_and_dists = index.grid_disk_distances::<Vec<_>>(2);

pub fn grid_disk_distances_safe( self, k: u32 ) -> impl Iterator<Item = (Self, u32)>

Safe but slow version of Self::grid_disk_distances_fast.

Example

let index = h3o::CellIndex::try_from(0x8a1fb46622dffff)?;
let cells_and_dists = index.grid_disk_distances_safe(2).collect::<Vec<_>>();

pub fn grid_disk_distances_fast( self, k: u32 ) -> impl Iterator<Item = Option<(Self, u32)>>

Produce cells and their distances from the current cell, up to distance k.

0-ring is defined as the current cell, 1-ring is defined as 0-ring and all neighboring indexes, and so on.

This function fails (i.e. returns a None item) when a pentagon (or a pentagon distortion) is encountered. When this happen, the previously returned items should be treated as invalid.

Example

let index = h3o::CellIndex::try_from(0x8a1fb46622dffff)?;
let cells_and_dists = index.grid_disk_distances_fast(2)
    .collect::<Option<Vec<_>>>()
    .unwrap_or_default();

pub fn grid_disks_fast( indexes: impl IntoIterator<Item = Self>, k: u32 ) -> impl Iterator<Item = Option<Self>>

Takes an list of cell indexes and a max k-ring and returns a stream of cell indexes sorted first by the original cell index and then by the grid k-ring (0 to max).

This function fails (i.e. returns a None item) when a pentagon (or a pentagon distortion) is encountered. When this happen, the previously returned cells should be treated as invalid and discarded.

Example

use h3o::CellIndex;

let indexes = vec![
    CellIndex::try_from(0x8a1fb46622dffff)?,
    CellIndex::try_from(0x8a1fb46622d7fff)?,
];
let cells = CellIndex::grid_disks_fast(indexes, 2)
    .collect::<Option<Vec<_>>>()
    .unwrap_or_default();

pub fn grid_ring_fast(self, k: u32) -> impl Iterator<Item = Option<Self>>

Returns the “hollow” ring of hexagons at exactly grid distance k from the current cell.

In particular, k=0 returns just the current hexagon.

This function fails (i.e. returns a None item) when a pentagon (or a pentagon distortion) is encountered. When this happen, the previously returned cells should be treated as invalid and discarded.

Failure cases may be fixed in future versions.

Example

let index = h3o::CellIndex::try_from(0x8a1fb46622dffff)?;
let cells = index.grid_ring_fast(2).collect::<Option<Vec<_>>>()
    .unwrap_or_default();

pub fn grid_distance(self, to: Self) -> Result<i32, LocalIjError>

Produces the grid distance between the two indexes.

Errors

This function may fail to find the distance between two indexes, for example if they are very far apart. It may also fail when finding distances for indexes on opposite sides of a pentagon. In such case, LocalIjError::Pentagon or LocalIjError::HexGrid is returned.

LocalIjError::ResolutionMismatch if the source and destination indexes don’t have the same resolution.

Example

use h3o::CellIndex;

let src = CellIndex::try_from(0x8a1fb46622dffff)?;
let dst = CellIndex::try_from(0x8a1fb46622d7fff)?;
assert_eq!(src.grid_distance(dst)?, 1);

pub fn grid_path_cells_size(self, to: Self) -> Result<i32, LocalIjError>

Computes the number of indexes in a line from the current index to the end one.

To be used for pre-allocating memory for CellIndex::grid_path_cells.

Errors

See Self::grid_distance.

Example

use h3o::CellIndex;

let src = CellIndex::try_from(0x8a1fb46622dffff)?;
let dst = CellIndex::try_from(0x8a1fb46622d7fff)?;
assert_eq!(src.grid_path_cells_size(dst)?, 2);

pub fn grid_path_cells( self, to: Self ) -> Result<impl Iterator<Item = Result<Self, LocalIjError>>, LocalIjError>

Given two H3 indexes, return the line of indexes between them (inclusive).

Notes

• The specific output of this function should not be considered stable across library versions. The only guarantees the library provides are that the line length will be start.grid_distance(end) + 1 and that every index in the line will be a neighbor of the preceding index.
• Lines are drawn in grid space, and may not correspond exactly to either Cartesian lines or great arcs.

Errors

This function may fail to find the distance between two indexes, for example if they are very far apart. It may also fail when finding distances for indexes on opposite sides of a pentagon. In such case, LocalIjError::Pentagon or LocalIjError::HexGrid is returned.

LocalIjError::ResolutionMismatch if the source and destination indexes don’t have the same resolution.

Example

use h3o::CellIndex;

let src = CellIndex::try_from(0x8a1fb46622dffff)?;
let dst = CellIndex::try_from(0x8a1fb46622d7fff)?;
let cells = src.grid_path_cells(dst)?.collect::<Result<Vec<_>, _>>()?;

pub fn is_neighbor_with(self, index: Self) -> Result<bool, ResolutionMismatch>

Returns whether or not the provided cell index is a neighbor of the current one.

Errors

ResolutionMismatch if the two indexes don’t have the same resolution.

Example

use h3o::CellIndex;

let src = CellIndex::try_from(0x8a1fb46622dffff)?;
let dst = CellIndex::try_from(0x8a1fb46622d7fff)?;
assert!(src.is_neighbor_with(dst)?);

let dst = CellIndex::try_from(0x8a1fb4644937fff)?;
assert!(!src.is_neighbor_with(dst)?);

pub fn to_local_ij(self, origin: Self) -> Result<LocalIJ, LocalIjError>

Produces IJ coordinates for an index anchored by an origin.

The coordinate space used by this function may have deleted regions or warping due to pentagonal distortion.

Coordinates are only comparable if they come from the same origin index.

This function’s output is not guaranteed to be compatible across different versions of H3.

Arguments

• origin - An anchoring index for the IJ coordinate system.
• index - Index to find the coordinates of.

Errors

LocalIjError::ResolutionMismatch if the index and the origin don’t have the same resolution.

Failure may occur if the index is too far away from the origin or if the index is on the other side of a pentagon. In such case, LocalIjError::Pentagon or LocalIjError::HexGrid is returned.

Example

use h3o::CellIndex;

let anchor = CellIndex::try_from(0x823147fffffffff)?;
let index = CellIndex::try_from(0x8230e7fffffffff)?;
let localij = index.to_local_ij(anchor)?;

pub fn succ(self) -> Option<Self>

Returns the next cell, in term of ordering.

Returns None if self is the last cell at this resolution.

Example

use h3o::CellIndex;

let start = CellIndex::try_from(0x823147fffffffff)?;
let after = start.succ().expect("next cell index");

pub fn pred(self) -> Option<Self>

Returns the previous cell, in term of ordering.

Returns None if self is the frist cell at this resolution.

Example

use h3o::CellIndex;

let start = CellIndex::try_from(0x823147fffffffff)?;
let before = start.pred().expect("next cell index");

pub fn first(resolution: Resolution) -> Self

The first cell index at the given resolution.

Example

use h3o::{CellIndex, Resolution};

let first = CellIndex::first(Resolution::Nine);

pub fn last(resolution: Resolution) -> Self

The last cell index at the given resolution.

Example

use h3o::{CellIndex, Resolution};

let last = CellIndex::last(Resolution::Nine);

Trait Implementations

impl<'a> Arbitrary<'a> for CellIndex

fn arbitrary(data: &mut Unstructured<'a>) -> Result<Self>

Generate an arbitrary value of Self from the given unstructured data.

fn arbitrary_take_rest(u: Unstructured<'a>) -> Result<Self, Error>

Generate an arbitrary value of Self from the entirety of the given unstructured data.

fn size_hint(depth: usize) -> (usize, Option<usize>)

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself.

impl Binary for CellIndex

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

Formats the value using the given formatter.

impl Clone for CellIndex

fn clone(&self) -> CellIndex

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for CellIndex

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for CellIndex

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for CellIndex

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

Formats the value using the given formatter.

impl From<CellIndex> for LatLng

fn from(value: CellIndex) -> Self

Determines the spherical coordinates of the center point of an H3 index.

impl From<CellIndex> for u64

fn from(value: CellIndex) -> Self

Converts to this type from the input type.

impl FromStr for CellIndex

type Err = InvalidCellIndex

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for CellIndex

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 LowerHex for CellIndex

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

Formats the value using the given formatter.

impl Octal for CellIndex

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

Formats the value using the given formatter.

impl Ord for CellIndex

fn cmp(&self, other: &Self) -> 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 + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq for CellIndex

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

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

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

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

impl PartialOrd for CellIndex

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

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

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

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

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

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

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

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

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

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

impl Serialize for CellIndex

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl ToGeo for CellIndex

fn to_geom(self, use_degrees: bool) -> Result<Self::Output, Self::Error>

Creates a Polygon representing the boundary of the cell.

Errors

This method cannot fail.

Example

use h3o::{CellIndex, geom::ToGeo};

let index = CellIndex::try_from(0x089283470803ffff)?;
let boundary = index.to_geom(true).expect("cannot fail");

type Error = Infallible

The type returned in the event of an outlining error.

type Output = Polygon

Output geometry type.

fn to_geojson(self) -> Result<Geometry, Self::Error>

where Self: Sized,

Creates a GeoJSON geometry describing the outline(s).

impl TryFrom<LocalIJ> for CellIndex

type Error = LocalIjError

The type returned in the event of a conversion error.

fn try_from(value: LocalIJ) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<u64> for CellIndex

type Error = InvalidCellIndex

The type returned in the event of a conversion error.

fn try_from(value: u64) -> Result<Self, Self::Error>

Performs the conversion.

impl UpperHex for CellIndex

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

Formats the value using the given formatter.

impl Copy for CellIndex

impl Eq for CellIndex

impl StructuralPartialEq for CellIndex