h3o Documentation

If you are migrating from the original H3 library, use this mapping to find the equivalent functionality in h3o:

Indexing

Index Inspection

Grid Traversal

Hierarchical Grid

Region & Edges

Vertex & Misc

The NEIGHBORS table defines the adjacency relationship between icosahedron faces. For any given face, the table provides 4 FaceOrientIJK entries representing its neighbors in different quadrants:

• IJ (index 1): The ij quadrant neighbor.
• KI (index 2): The ki quadrant neighbor.
• JK (index 3): The jk quadrant neighbor.

Note: The first entry (index 0) in the array for each face is the face itself (the 'central face').

Each FaceOrientIJK contains:

• face: The neighbor's Face.
• translate: A CoordIJK representing the resolution 0 translation relative to the primary face.
• ccw_rot60: The number of 60-degree counter-clockwise rotations relative to the primary face.

// Example of accessing neighbors
let current_face_idx = 0;
let neighbors = h3o::NEIGHBORS[current_face_idx];

// Access the 'ij' quadrant neighbor
let ij_neighbor = neighbors[h3o::IJ];
println!("Neighbor face: {:?}, translation: {:?}", ij_neighbor.face, ij_neighbor.translate);

A VertexIndex represents a single topological vertex in the H3 grid system, which is shared by three cells. Unlike a CellIndex, a VertexIndex identifies a specific point in space by encoding both an "owner" cell and a specific vertex number on that cell.

Bit Layout

The 64-bit index is laid out as follows:

• U (bit 63): Unused, always 0.
• M (bits 59-62): Index mode (set to 4 for Vertex mode).
• V (bits 56-58): Vertex number on the owner cell [0, 5].
• O (bits 0-55): Owner cell index.

Common Operations

• Get the vertex number: Use .vertex() to retrieve the Vertex on the owner cell.
• Get the owner cell: Use .owner() to retrieve the CellIndex that owns this vertex.
• Get coordinates: Convert a VertexIndex into a LatLng to get its geographic coordinates.
• Parsing: You can create a VertexIndex from a hex string using FromStr or from a u64 using TryFrom.

// Create from a hex u64
let index = h3o::VertexIndex::try_from(0x2222597fffffffff)?;

// Access the owner cell
let owner = index.owner();

// Access the specific vertex number
let vertex = index.vertex();

// Get geographic coordinates
let coords: h3o::LatLng = index.into();

The ContainmentMode determines the logic used to decide if an H3 cell is considered part of the input geometry. This affects both the completeness of the coverage and whether cells overlap between adjacent polygons.

The Tiler struct allows you to convert geographic shapes (Polygons) into a set of H3 cells. You can configure the tiler using a TilerBuilder to specify the H3 Resolution and the ContainmentMode (how a cell is determined to be 'inside' a shape).

To use it:

1. Create a TilerBuilder with a specific Resolution.
2. Set a ContainmentMode.
3. Build the Tiler.
4. Add one or more Polygon objects using .add() or .add_batch().
5. Use .into_coverage() to get an iterator of CellIndex or .into_annotated_coverage() to get AnnotatedCell objects which include containment metadata.

use geo::{LineString, Polygon};
use h3o::{geom::{ContainmentMode, TilerBuilder}, Resolution};

let polygon = Polygon::new(
    LineString::from(vec![(0., 0.), (1., 1.), (1., 0.), (0., 0.)]),
    vec![],
);

let mut tiler = TilerBuilder::new(Resolution::Six)
    .containment_mode(ContainmentMode::Covers)
    .build();

tiler.add(polygon)?;

// Get just the cell indices
let cells = tiler.into_coverage().collect::<Vec<_>>();

// Or get cells with containment info
let annotated_cells = tiler.into_annotated_coverage().collect::<Vec<_>>();