Hierarchical grid functions - H3

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

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.

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

Returns 0 (E_SUCCESS) on success.

</TabItem> <TabItem value="java">

java

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

</TabItem> <TabItem value="javascript">

h3.cellToParent(cell, parentRes)

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

</TabItem> <TabItem value="python">

h3.cell_to_parent(h, res=None)

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

</TabItem> <TabItem value="go">

cell.Parent(res)

</TabItem> <TabItem value="duckdb">

sql

h3_cell_to_parent(h, res)

</TabItem> <TabItem value="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)

bash

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

</TabItem> </Tabs>

cellToChildren

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

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.

</TabItem> <TabItem value="java">

java

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

</TabItem> <TabItem value="javascript">

h3.cellToChildren(cell, childRes)

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

</TabItem> <TabItem value="python">

h3.cell_to_children(h, res=None)

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

</TabItem> <TabItem value="go">

cell.Children(res)

</TabItem> <TabItem value="duckdb">

sql

h3_cell_to_children(h, res)

</TabItem> <TabItem value="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)

bash

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

</TabItem> </Tabs>

cellToChildrenSize

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

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.

</TabItem> <TabItem value="java">

java

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

</TabItem> <TabItem value="javascript">

h3.cellToChildrenSize(cell, childRes)

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

</TabItem> <TabItem value="python">

h3.cell_to_children_size(h, res=None)

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

</TabItem> <TabItem value="go">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem> <TabItem value="duckdb">

sql

h3_cell_to_children_size(h, res)

</TabItem> <TabItem value="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

bash

$ h3 cellToChildrenSize -c 85283473fffffff -r 6
7

</TabItem> </Tabs>

cellToCenterChild

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

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

Returns 0 (E_SUCCESS) on success.

</TabItem> <TabItem value="java">

java

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

</TabItem> <TabItem value="javascript">

h3.cellToCenterChild(cell, childRes)

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

</TabItem> <TabItem value="python">

h3.cell_to_center_child(h, res=None)

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

</TabItem> <TabItem value="go">

cell.CenterChild(res)

</TabItem> <TabItem value="duckdb">

sql

h3_cell_to_center_child(h, res)

</TabItem> <TabItem value="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)

bash

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

</TabItem> </Tabs>

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.

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

Returns 0 (E_SUCCESS) on success.

</TabItem> <TabItem value="java">

java

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

</TabItem> <TabItem value="javascript">

h3.cellToChildPos(child, parentRes)

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

</TabItem> <TabItem value="python">

h3.cell_to_child_pos(child, res_parent)

</TabItem> <TabItem value="go">

child.ChildPos(parentRes)

</TabItem> <TabItem value="duckdb">

sql

h3_cell_to_child_pos(child, res_parent)

</TabItem> <TabItem value="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

bash

$ h3 cellToChildPos -c 85283473fffffff -r 3
25

</TabItem> </Tabs>

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.

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

Returns 0 (E_SUCCESS) on success.

</TabItem> <TabItem value="java">

java

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

</TabItem> <TabItem value="javascript">

h3.childPosToCell(childPos, parent, childRes);

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

</TabItem> <TabItem value="python">

h3.child_pos_to_cell(parent, res_child, child_pos)

</TabItem> <TabItem value="go">

parent.ChildPosToCell(childPos, res)

</TabItem> <TabItem value="duckdb">

sql

h3_child_pos_to_cell(child_pos, parent, res_child)

</TabItem> <TabItem value="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)

bash

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

</TabItem> </Tabs>

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.

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.

</TabItem> <TabItem value="java">

java

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

</TabItem> <TabItem value="javascript">

h3.compactCells(cells)

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

</TabItem> <TabItem value="python">

h3.compact_cells(cells)

</TabItem> <TabItem value="go">

h3.CompactCells(cells)

</TabItem> <TabItem value="duckdb">

sql

h3_compact_cells(cells)

</TabItem> <TabItem value="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)

bash

$ 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" ]

</TabItem> </Tabs>

uncompactCells

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

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

Returns 0 (E_SUCCESS) on success.

</TabItem> <TabItem value="java">

java

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

</TabItem> <TabItem value="javascript">

h3.uncompactCells(cells, res)

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

</TabItem> <TabItem value="python">

h3.uncompact_cells(cells, res)

</TabItem> <TabItem value="go">

h3.UncompactCells(cells, res)

</TabItem> <TabItem value="duckdb">

sql

h3_uncompact_cells(cells, res)

</TabItem> <TabItem value="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)

bash

$ 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" ]

</TabItem> </Tabs>

uncompactCellsSize

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

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.

</TabItem> <TabItem value="java">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem> <TabItem value="javascript">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem> <TabItem value="python">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem> <TabItem value="go">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem> <TabItem value="duckdb">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem> <TabItem value="shell">

:::note

This function exists for memory management and is not exposed.

:::

</TabItem> </Tabs>