h3shape_to_cells_experimental overlap without border?

[erikvanoosten]

Hi, I noticed that h3.h3shape_to_cells_experimental(h3shape, resolution, contain='overlap') includes tiles that only share a border with the input h3shape.

This leads to weird things like not being able to go from tiles to a geometry and then back to tiles:

santa_fe_res7 = ["8748d8732ffffff", "8748d8730ffffff", "8748d8735ffffff"]
geometry = h3.cells_to_h3shape(santa_fe_res7, tight=True)
tiles = h3.h3shape_to_cells_experimental(geometry, resolution=7, contain='overlap')
assert tiles == santa_fe_res7  # FAILS

tiles contains the 3 input tiles, and all direct neighbors.

My use case is to find all resolution 9 tiles that (partially) overlap a resolution 7 tile.

For this, the 2 tiles circled in red should not be selected.

This all leads to this question: how can we select the tiles that overlap with the contents of a geometry (that is, ignoring its border)?

[erikvanoosten]

For context, getting the resolution 9 child tiles is not what I need because these child tiles do not fully cover the resolution 7 tiles.

The result I am after is:

[khalilurrrahmanridoykhan]

contain="overlap" currently treats boundary contact as an overlap, so the practical way to request positive-area overlap is to use it for the candidate set and then remove candidates whose polygon intersection has zero (or numerical-noise) area.

Here is a reusable filter with Shapely:

import h3
from shapely.geometry import shape


def cells_with_interior_overlap(h3shape, resolution, relative_tolerance=1e-12):
    region = shape(h3shape.__geo_interface__)
    candidates = h3.h3shape_to_cells_experimental(
        h3shape,
        resolution,
        contain="overlap",
    )

    selected = []
    for cell in candidates:
        cell_shape = h3.cells_to_h3shape([cell], tight=True)
        cell_polygon = shape(cell_shape.__geo_interface__)
        intersection = region.intersection(cell_polygon)

        # Exclude cells that only touch the boundary. The relative threshold
        # also removes tiny floating-point slivers around shared H3 edges.
        if intersection.area > cell_polygon.area * relative_tolerance:
            selected.append(cell)

    return selected

Using the example from the question:

santa_fe_res7 = [
    "8748d8732ffffff",
    "8748d8730ffffff",
    "8748d8735ffffff",
]

geometry = h3.cells_to_h3shape(santa_fe_res7, tight=True)

res7 = cells_with_interior_overlap(geometry, 7)
assert set(res7) == set(santa_fe_res7)

res9 = cells_with_interior_overlap(geometry, 9)
print(len(res9))

I tested this with h3-py 4.5.0 and Shapely using the indexes in the discussion:

• raw contain="overlap" candidates at resolution 9: 190
• positive-area candidates after filtering: 180
• boundary-only candidates removed: 10

The result is intentionally larger than cell_to_children() (147 cells for the three resolution-7 parents), because it retains resolution-9 cells that genuinely cross the outer boundary while excluding cells that merely share an edge or vertex.

For this Santa Fe example, the area ratio in longitude/latitude space is sufficient as a topological/numerical filter. For regions crossing the antimeridian or near the poles, split/normalize the geometry first or project both geometries to a suitable equal-area CRS before comparing intersection areas.

So the containment modes currently express “intersects including boundary”; the additional positive-area predicate supplies the “overlaps the contents, not only its border” semantics requested here.