uber · isaacbrodsky · Sep 27, 2024 · dfellis · Sep 27, 2024
diff --git a/docs/api_quick.md b/docs/api_quick.md
@@ -81,6 +81,8 @@ Functions relating H3 objects to geographic (lat/lng) coordinates.
    cell_to_center_child
    compact_cells
    uncompact_cells
+   cell_to_child_pos
+   child_pos_to_cell
 ```
 
 ## Cell grid relationships

diff --git a/src/h3/_cy/__init__.py b/src/h3/_cy/__init__.py
@@ -36,6 +36,8 @@
     get_icosahedron_faces,
     cell_to_local_ij,
     local_ij_to_cell,
+    cell_to_child_pos,
+    child_pos_to_cell,
 )
 
 from .edges import (

diff --git a/src/h3/_cy/cells.pxd b/src/h3/_cy/cells.pxd
@@ -22,3 +22,5 @@ cpdef H3int[:] get_res0_cells()
 cpdef get_icosahedron_faces(H3int h)
 cpdef (int, int) cell_to_local_ij(H3int origin, H3int h) except *
 cpdef H3int local_ij_to_cell(H3int origin, int i, int j) except 0
+cpdef int64_t cell_to_child_pos(H3int cell, int res) except *
+cpdef H3int child_pos_to_cell(int64_t pos, H3int origin, int res) except 0
diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx
@@ -417,3 +417,28 @@ cpdef H3int local_ij_to_cell(H3int origin, int i, int j) except 0:
         check_for_error_msg(err, msg)
 
     return out
+
+cpdef int64_t cell_to_child_pos(H3int child, int parentRes) except *:
+    cdef:
+        int64_t out
+
+    err = h3lib.cellToChildPos(child, parentRes, &out)
+    if err:
+        msg = "Couldn't find child pos with cell {} from res {}."
+        msg = msg.format(hex(child), parentRes)
+        check_for_error_msg(err, msg)
+
+    return out
+
+cpdef H3int child_pos_to_cell(int64_t childPos, H3int parent, int childRes) except 0:
+    cdef:
+        H3int child
+
+    err = h3lib.childPosToCell(childPos, parent, childRes, &child)
+    if err:
+        msg = "Couldn't find child with pos {} from parent {} with res {}."
+        msg = msg.format(childPos, hex(parent), childRes)
+        check_for_error_msg(err, msg)
+
+    return child
+
diff --git a/src/h3/_cy/h3lib.pxd b/src/h3/_cy/h3lib.pxd
@@ -135,6 +135,9 @@ cdef extern from 'h3api.h':
     H3Error cellToLocalIj(H3int origin, H3int h3, uint32_t mode, CoordIJ *out) nogil
     H3Error localIjToCell(H3int origin, const CoordIJ *ij, uint32_t mode, H3int *out) nogil
 
+    H3Error cellToChildPos(H3int child, int res, int64_t *out) nogil
+    H3Error childPosToCell(int64_t childPos, H3int parent, int childRes, H3int *child) nogil
+
     H3Error gridDiskDistances(H3int origin, int k, H3int *out, int *distances) nogil
     H3Error gridRingUnsafe(H3int origin, int k, H3int *out) nogil
 

diff --git a/src/h3/api/basic_int/__init__.py b/src/h3/api/basic_int/__init__.py
@@ -922,6 +922,65 @@ def local_ij_to_cell(origin, i, j):
     return h
 
 
+def cell_to_child_pos(child, parent_res):
+    """
+    TODO
+
+    Parameters
+    ----------
+    child: H3Cell
+        TODO
+    parent_res: int
+        TODO
+
+
+    Returns
+    -------
+    TODO
+
+
+    Notes
+    -----
+
+    TODO
+    """
+    child = _in_scalar(child)
+
+    h = _cy.cell_to_child_pos(child, parent_res)
+
+    return h
+
+
+def child_pos_to_cell(child_pos, parent, child_res):
+    """
+    TODO
+
+    Parameters
+    ----------
+    child_pos: int
+        TODO
+    parent: H3Cell
+        TODO
+    child_res: int
+        TODO
+
+    Returns
+    -------
+    TODO
+
+
+    Notes
+    -----
+    TODO
+    """
+    parent = _in_scalar(parent)
+
+    h = _cy.child_pos_to_cell(child_pos, parent, child_res)
+    h = _out_scalar(h)
+
+    return h
+
+
 def cell_area(h, unit='km^2'):
     """
     Compute the spherical surface area of a specific H3 cell.

diff --git a/tests/test_h3.py b/tests/test_h3.py
@@ -446,3 +446,31 @@ def test_is_valid_vertex():
     assert h3.is_valid_vertex('2114c3ffffffffff')
     assert not h3.is_valid_vertex(2455495337847029759)
     assert not h3.is_valid_vertex('foobar')
+
+
+def test_child_pos():
+    assert h3.cell_to_child_pos('88283080ddfffff', 8) == 0
+    assert h3.cell_to_child_pos('88283080ddfffff', 7) == 6
+    assert h3.cell_to_child_pos('88283080ddfffff', 6) == 41
+
+    with pytest.raises(h3.H3BaseException):
+        h3.cell_to_child_pos("88283080ddfffff", 9)
+
+    with pytest.raises(h3.H3BaseException):
+        h3.cell_to_child_pos("88283080ddfffff", 9)
+
+    assert h3.child_pos_to_cell(0, '88283080ddfffff', 8) == '88283080ddfffff'
+    assert h3.child_pos_to_cell(
+        6,
+        h3.cell_to_parent('88283080ddfffff', 7),
+        8) == '88283080ddfffff'
+    assert h3.child_pos_to_cell(
+        41,
+        h3.cell_to_parent('88283080ddfffff', 6),
+        8) == "88283080ddfffff"
+
+    with pytest.raises(h3.H3BaseException):
+        h3.child_pos_to_cell(-1, "88283080ddfffff", 9)
+
+    with pytest.raises(h3.H3BaseException):
+        h3.child_pos_to_cell(10000, "88283080ddfffff", 9)