Skip to main content
Version: 4.x

Hierarchical grid functions

These functions permit moving between resolutions in the H3 grid system. The functions produce parent cells (coarser), or child cells (finer).

cellToParent

H3Error cellToParent(H3Index cell, int parentRes, H3Index *parent);

Provides the parent (coarser) index containing cell.

Returns 0 (E_SUCCESS) on success.

cellToChildren

H3Error cellToChildren(H3Index cell, int childRes, H3Index *children);

Populates children with the indexes contained by cell at resolution childRes. children must be an array of at least size cellToChildrenSize(cell, childRes).

Returns 0 (E_SUCCESS) on success.

cellToChildrenSize

H3Error cellToChildrenSize(H3Index cell, int childRes, int64_t *out);

Provides the size of the children array needed for the given inputs to cellToChildren.

Returns 0 (E_SUCCESS) on success.

cellToCenterChild

H3Error cellToCenterChild(H3Index cell, int childRes, H3Index *child);

Provides the center child (finer) index contained by cell at resolution childRes.

Returns 0 (E_SUCCESS) on success.

cellToChildPos

H3Index cellToChildPos(H3Index child, int parentRes, int64_t *out);

Returns the position of the child cell within an ordered list of all children of the cell's parent at the specified resolution parentRes. The order of the ordered list is the same as that returned by cellToChildren. This is the complement of childPosToCell.

Returns 0 (E_SUCCESS) on success.

childPosToCell

H3Index childPosToCell(int64_t childPos, H3Index parent, int childRes, H3Index *child);

Returns the child cell at a given position within an ordered list of all children of parent at the specified resolution childRes. The order of the ordered list is the same as that returned by cellToChildren. This is the complement of cellToChildPos.

Returns 0 (E_SUCCESS) on success.

compactCells

H3Error compactCells(const H3Index *cellSet, H3Index *compactedSet, const int64_t numCells);

Compacts the set cellSet of indexes as best as possible, into the array compactedSet. compactedSet must be at least the size of cellSet in case the set cannot be compacted. Cells in cellSet must all share the same resolution.

Returns 0 (E_SUCCESS) on success.

uncompactCells

H3Error uncompactCells(const H3Index *compactedSet, const int64_t numCells, H3Index *cellSet, const int64_t maxCells, const int res);

Uncompacts the set compactedSet of indexes to the resolution res. h3Set must be at least of size uncompactCellsSize(compactedSet, numHexes, res).

Returns 0 (E_SUCCESS) on success.

uncompactCellsSize

H3Error uncompactCellsSize(const H3Index *compactedSet, const int64_t numCompacted, const int res, int64_t *out);

Places the size of the array needed by uncompactCells into out.

Returns 0 (E_SUCCESS) on success.