Skip to main content
Version: 4.x

Grid traversal functions

Grid traversal allows finding cells in the vicinity of an origin cell, and determining how to traverse the grid from one cell to another.

gridDistance​

Provides the grid distance between two cells, which is defined as the minimum number of "hops" needed across adjacent cells to get from one cell to the other.

Note that finding the grid distance may fail for a few reasons:

  • the cells are not comparable (different resolutions),
  • the cells are too far apart, or
  • the cells are separated by pentagonal distortion.

This is the same set of limitations as the local IJ coordinate space functions.

H3Error gridDistance(H3Index origin, H3Index h3, int64_t *distance);

Returns 0 (E_SUCCESS) on success, or an error if finding the distance failed.

gridRingUnsafe​

Produces the "hollow ring" of cells which are exactly grid distance k from the origin cell.

This function may fail if pentagonal distortion is encountered.

H3Error gridRingUnsafe(H3Index origin, int k, H3Index* out);

The caller should allocate memory for the maximum size of the ring, which is 6*k if k > 0 and 1 if k == 0.

Returns 0 (E_SUCCESS) if no pentagonal distortion was encountered.

gridDisk​

Produces the "filled-in disk" of cells which are at most grid distance k from the origin cell.

Output order is not guaranteed.

H3Error gridDisk(H3Index origin, int k, H3Index* out);

Elements of the output array may be left as zero, which can happen when crossing a pentagon.

Returns 0 (E_SUCCESS) on success.

maxGridDiskSize​

Maximum number of cells that can result from the gridDisk function for a given k.

H3Error maxGridDiskSize(int k, int64_t *out);

Returns 0 (E_SUCCESS) on success.

gridDiskDistances​

Produces the same set of cells as gridDisk, but along with each cell's grid distance from the origin cell.

Output order is not guaranteed.

H3Error gridDiskDistances(H3Index origin, int k, H3Index* out, int* distances);

Elements of the output array may be left as zero, which can happen when crossing a pentagon.

Returns 0 (E_SUCCESS) on success.

gridDiskUnsafe​

Produces cells within grid distance k of the origin cell, just like gridDisk. However, the function may return an error code if pentagonal distorition is encountered. In this case, the output in the out array is undefined.

Users can fall back to calling the slower but more robust gridDiskDistances.

H3Error gridDiskUnsafe(H3Index origin, int k, H3Index* out);

Output is placed in the provided array in order of increasing distance from the origin. The provided array must be of size maxGridDiskSize(k).

Returns 0 (E_SUCCESS) if no pentagonal distortion is encountered.

gridDiskDistancesUnsafe​

gridDiskDistancesUnsafe produces indexes within k distance of the origin index. Output behavior is undefined when one of the indexes returned by this function is a pentagon or is in the pentagon distortion area.

Output is placed in the provided array in order of increasing distance from the origin. The distances in hexagons is placed in the distances array at the same offset. The provided array must be of size maxGridDiskSize(k).

H3Error gridDiskDistancesUnsafe(H3Index origin, int k, H3Index* out, int* distances);

Returns 0 (E_SUCCESS) if no pentagonal distortion is encountered.

gridDiskDistancesSafe​

gridDiskDistancesSafe produces indexes within k distance of the origin index.

Output is placed in the provided array in order of increasing distance from the origin. The distances in hexagons is placed in the distances array at the same offset. The provided array must be of size maxGridDiskSize(k).

H3Error gridDiskDistancesSafe(H3Index origin, int k, H3Index* out, int* distances);

Returns 0 (E_SUCCESS) on success.

gridDisksUnsafe​

gridDisksUnsafe takes an array of input cells and a max k and returns an array of cells sorted first by the original cell indices and then by the grid ring (0 to max), with no guaranteed sorting within each grid ring group.

H3Error gridDisksUnsafe(H3Index* h3Set, int length, int k, H3Index* out);

Returns 0 (E_SUCCESS) if no pentagonal distortion was encountered.

gridPathCells​

Given two H3 cells, return a minimal-length contiguous path of cells between them (inclusive of the endpoint cells).

This function may fail if the cells are very far apart, or if the cells are on opposite sides of a pentagon.

Notes:

  • The output of this function should not be considered stable across library versions. The only guarantees are that the path length will be gridDistance(start, end) + 1 and that every cell in the path will be a neighbor of the preceding cell.

  • Paths exist in the H3 grid of cells, and may not align closely with either Cartesian lines or great arcs.

H3Error gridPathCells(H3Index start, H3Index end, H3Index* out);

Returns 0 (E_SUCCESS) if no pentagonal distortion was encountered.

gridPathCellsSize​

Number of cells in a grid path from the start cell to the end cell, to be used for allocating memory.

H3Error gridPathCellsSize(H3Index start, H3Index end, int64_t* size);

Returns 0 (E_SUCCESS) on success, or an error if the path cannot be computed.

cellToLocalIj​

Produces local IJ coordinates for an H3 cell anchored by an origin.

mode is reserved for future expansion and must be set to 0.

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

H3Error cellToLocalIj(H3Index origin, H3Index h3, uint32_t mode, CoordIJ *out);

Returns 0 (E_SUCCESS) on success.

localIjToCell​

Produces an H3 cell from local IJ coordinates anchored by an origin.

mode is reserved for future expansion and must be set to 0.

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

H3Error localIjToCell(H3Index origin, const CoordIJ *ij, uint32_t mode, H3Index *out);

Returns 0 (E_SUCCESS) on success.