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

Provides the unique ancestor (coarser) cell of the given cell for the provided resolution. If the input cell has resolution r, then parentRes = r - 1 would give the immediate parent, parentRes = r - 2 would give the grandparent, and so on.

C

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

Returns 0 (E_SUCCESS) on success.

Java

long cellToParent(long cell, int parentRes);
String cellToParentAddress(String cellAddress, int parentRes);

JavaScript (Live)

h3.cellToParent(cell, parentRes)

Live Editor

function example() { const cell = '85283473fffffff'; return h3.cellToParent(cell, 4); }

function example() {
  const cell = '85283473fffffff';
  return h3.cellToParent(cell, 4);
}

Result

Loading...

Python

h3.cell_to_parent(h, res=None)

If res = None, we set res = resolution(h) - 1. See the h3-py docs.

Shell

$ h3 cellToParent --help
h3: Returns the H3 index that is the parent (or higher) of the provided cell
H3 4.1.0

    cellToParent    Returns the H3 index that is the parent (or higher) of the provided cell
    -h, --help  Show this help message.
    -c, --cell <index>  Required. H3 Cell
    -r, --resolution <res>  Required. Resolution, 0-14 inclusive, excluding 15 as it can never be a parent
    -f, --format <FMT>  'json' for "CELL"\n, 'newline' for CELL\n (Default: json)

$ h3 cellToParent -c 85283473fffffff -r 4
"8428347ffffffff"

cellToChildren

Provides the children (descendant) cells of cell at resolution childRes.

C

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

children must be an array of at least size cellToChildrenSize(cell, childRes).

Returns 0 (E_SUCCESS) on success.

Java

List<Long> cellToChildren(long cell, int childRes);
List<String> cellToChildren(String cellAddress, int childRes);

JavaScript (Live)

h3.cellToChildren(cell, childRes)

Live Editor

function example() { const cell = '85283473fffffff'; return h3.cellToChildren(cell, 6); }

function example() {
  const cell = '85283473fffffff';
  return h3.cellToChildren(cell, 6);
}

Result

Loading...

Python

h3.cell_to_children(h, res=None)

If res = None, we set res = resolution(h) + 1. See the h3-py docs.

Shell

$ h3 cellToChildren --help
h3: Returns an array of H3 indexes that are the children (or lower) of the provided cell
H3 4.1.0

    cellToChildren  Returns an array of H3 indexes that are the children (or lower) of the provided cell
    -h, --help  Show this help message.
    -c, --cell <index>  Required. H3 Cell
    -r, --resolution <res>  Required. Resolution, 1-15 inclusive, excluding 0 as it can never be a child
    -f, --format <FMT>  'json' for ["CELL", ...], 'newline' for CELL\n... (Default: json)

$ h3 cellToChildren -c 85283473fffffff -r 6
[ "862834707ffffff", "86283470fffffff", "862834717ffffff", "86283471fffffff", "862834727ffffff", "86283472fffffff", "862834737ffffff" ]

cellToChildrenSize

Provides the number of children at a given resolution of the given cell.

C

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.

Java

note

This function exists for memory management and is not exposed.

JavaScript (Live)

note

This function exists for memory management and is not exposed.

Python

h3.cell_to_children_size(h, res=None)

If res = None, we set res = resolution(h) + 1. See the h3-py docs.

Shell

$ h3 cellToChildrenSize --help
h3: Returns the maximum number of children for a given cell at the specified child resolution
H3 4.1.0

    cellToChildrenSize  Returns the maximum number of children for a given cell at the specified child resolution
    -h, --help  Show this help message.
    -c, --cell <index>  Required. H3 Cell
    -r, --resolution <res>  Required. Resolution, 1-15 inclusive, excluding 0 as it can never be a child

$ h3 cellToChildrenSize -c 85283473fffffff -r 6
7

cellToCenterChild

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

C

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

Returns 0 (E_SUCCESS) on success.

Java

long cellToCenterChild(long cell, int childRes);
String cellToCenterChild(String cellAddress, int childRes);

JavaScript (Live)

h3.cellToCenterChild(cell, childRes)

Live Editor

function example() { const cell = '85283473fffffff'; return h3.cellToCenterChild(cell, 7); }

function example() {
  const cell = '85283473fffffff';
  return h3.cellToCenterChild(cell, 7);
}

Result

Loading...

Python

h3.cell_to_center_child(h, res=None)

If res = None, we set res = resolution(h) + 1. See the h3-py docs.

Shell

$ h3 cellToCenterChild --help
h3: Returns the H3 index that is the centrally-placed child (or lower) of the provided cell
H3 4.1.0

    cellToCenterChild   Returns the H3 index that is the centrally-placed child (or lower) of the provided cell
    -h, --help  Show this help message.
    -c, --cell <index>  Required. H3 Cell
    -r, --resolution <res>  Required. Resolution, 1-15 inclusive, excluding 0 as it can never be a child
    -f, --format <FMT>  'json' for "CELL"\n, 'newline' for CELL\n (Default: json)

$ h3 cellToCenterChild -c 85283473fffffff -r 7
"872834700ffffff"

cellToChildPos

Provides 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.

C

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

Returns 0 (E_SUCCESS) on success.

Java

long cellToChildPos(long child, int parentRes);
long cellToChildPos(String childAddress, int parentRes);

JavaScript (Live)

h3.cellToChildPos(child, parentRes)

Live Editor

function example() { const cell = '85283473fffffff'; return h3.cellToChildPos(cell, 3); }

function example() {
  const cell = '85283473fffffff';
  return h3.cellToChildPos(cell, 3);
}

Result

Loading...

Python

h3.cell_to_child_pos(child, res_parent)

Shell

$ h3 cellToChildPos --help
h3: Returns the position of the child cell within an ordered list of all children of the cell's parent at the specified child resolution
H3 4.1.0

    cellToChildPos  Returns the position of the child cell within an ordered list of all children of the cell's parent at the specified child resolution
    -h, --help  Show this help message.
    -c, --cell <index>  Required. H3 Cell
    -r, --resolution <res>  Required. Resolution, 1-15 inclusive, excluding 0 as it can never be a child

$ h3 cellToChildPos -c 85283473fffffff -r 3
25

childPosToCell

Provides 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.

C

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

Returns 0 (E_SUCCESS) on success.

Java

long childPosToCell(long childPos, long parent, int childRes);
String childPosToCell(long childPos, String parentAddress, int childRes);

JavaScript (Live)

h3.childPosToCell(childPos, parent, childRes);

Live Editor

function example() { const parent = '85283473fffffff'; const childPos = 42; return h3.childPosToCell(childPos, parent, 7); }

function example() {
  const parent = '85283473fffffff';
  const childPos = 42;
  return h3.childPosToCell(childPos, parent, 7);
}

Result

Loading...

Python

h3.child_pos_to_cell(parent, res_child, child_pos)

Shell

$ h3 childPosToCell --help
h3: Returns the child cell at a given position and resolution within an ordered list of all children of the parent cell
H3 4.1.0

    childPosToCell  Returns the child cell at a given position and resolution within an ordered list of all children of the parent cell
    -h, --help  Show this help message.
    -c, --cell <index>  Required. H3 Cell
    -r, --resolution <res>  Required. Resolution, 1-15 inclusive, excluding 0 as it can never be a child
    -p, --position <pos>    Required. The child position within the set of children of the parent cell
    -f, --format <FMT>  'json' for "CELL"\n, 'newline' for CELL\n (Default: json)

$ h3 childPosToCell -p 42 -c 85283473fffffff -r 7
"872834730ffffff"

compactCells

Compacts a collection of H3 cells by recursively replacing children cells with their parents if all children are present. Input cells must all share the same resolution.

C

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

Compacts cellSet into the array compactedSet. compactedSet must be at least the size of cellSet (in case the set cannot be compacted).

Returns 0 (E_SUCCESS) on success.

Java

List<Long> compactCells(Collection<Long> cells);
List<String> compactCellAddress(Collection<String> cells);

JavaScript (Live)

h3.compactCells(cells)

Live Editor

function example() { const cell = '85283473fffffff'; const nearby = h3.gridDisk(cell, 4); return h3.compactCells(nearby); }

function example() {
  const cell = '85283473fffffff';
  const nearby = h3.gridDisk(cell, 4);
  return h3.compactCells(nearby);
}

Result

Loading...

Python

h3.compact_cells(cells)

Shell

$ h3 compactCells --help
h3: Compacts the provided set of cells as best as possible. The set of input cells must all share the same resolution.
H3 4.1.0

    compactCells    Compacts the provided set of cells as best as possible. The set of input cells must all share the same resolution.
    -h, --help  Show this help message.
    -i, --file <FILENAME>   The file to load the cells from. Use -- to read from stdin.
    -c, --cells <CELLS> The cells to compact. Up to 100 cells if provided as hexadecimals with zero padding.
    -f, --format <FMT>  'json' for ["CELL", ...], 'newline' for CELL\n... (Default: json)

$ h3 compactCells -c 85283473fffffff,85283447fffffff,8528347bfffffff,85283463fffffff,85283477fffffff,8528340ffffffff,8528340bfffffff,85283457fffffff,85283443fffffff,8528344ffffffff,852836b7fffffff,8528346bfffffff,8528346ffffffff,85283467fffffff,8528342bfffffff,8528343bfffffff,85283407fffffff,85283403fffffff,8528341bfffffff
[ "85283447fffffff", "8528340ffffffff", "8528340bfffffff", "85283457fffffff", "85283443fffffff", "8528344ffffffff", "852836b7fffffff", "8528342bfffffff", "8528343bfffffff", "85283407fffffff", "85283403fffffff", "8528341bfffffff", "8428347ffffffff" ]

uncompactCells

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

C

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

Returns 0 (E_SUCCESS) on success.

Java

List<Long> uncompactCells(Collection<Long> cells, int res);
List<String> uncompactCellAddress(Collection<String> cells, int res);

JavaScript (Live)

h3.uncompactCells(cells, res)

Live Editor

function example() { const cell = '85283473fffffff'; const nearby = h3.gridDisk(cell, 4); const compacted = h3.compactCells(nearby); return h3.uncompactCells(compacted, 5); }

function example() {
  const cell = '85283473fffffff';
  const nearby = h3.gridDisk(cell, 4);
  const compacted = h3.compactCells(nearby);
  return h3.uncompactCells(compacted, 5);
}

Result

Loading...

Python

h3.uncompact_cells(cells, res)

Shell

$ h3 uncompactCells --help
h3: Unompacts the provided set of compacted cells.The uncompacted cells will be printed one per line to stdout.
H3 4.1.0

    uncompactCells  Unompacts the provided set of compacted cells.The uncompacted cells will be printed one per line to stdout.
    -h, --help  Show this help message.
    -i, --file <FILENAME>   The file to load the cells from. Use -- to read from stdin.
    -c, --cells <CELLS> The cells to uncompact. Up to 100 cells if provided as hexadecimals with zero padding.
    -r, --resolution <res>  Required. Resolution, 0-15 inclusive, that the compacted set should be uncompacted to. Must be greater than or equal to the highest resolution within the compacted set.
    -f, --format <FMT>  'json' for ["CELL", ...], 'newline' for CELL\n... (Default: json)

$ h3 uncompactCells -r 5 -c 85283447fffffff,8528340ffffffff,8528340bfffffff,85283457fffffff,85283443fffffff,8528344ffffffff,852836b7fffffff,8528342bfffffff,8528343bfffffff,85283407fffffff,85283403fffffff,8528341bfffffff,8428347ffffffff
[ "85283447fffffff", "8528340ffffffff", "8528340bfffffff", "85283457fffffff", "85283443fffffff", "8528344ffffffff", "852836b7fffffff", "8528342bfffffff", "8528343bfffffff", "85283407fffffff", "85283403fffffff", "8528341bfffffff", "85283463fffffff", "85283467fffffff", "8528346bfffffff", "8528346ffffffff", "85283473fffffff", "85283477fffffff", "8528347bfffffff" ]

uncompactCellsSize

Provides the total resulting number of cells if uncompacting a cell set to a given resolution.

C

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

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

Returns 0 (E_SUCCESS) on success.

Java

note

This function exists for memory management and is not exposed.

JavaScript (Live)

note

This function exists for memory management and is not exposed.

Python

note

This function exists for memory management and is not exposed.

Shell

note

This function exists for memory management and is not exposed.