Hex Grid Neighborhood Planner

Construct localized neighborhoods and shortest routes between hexagonal grid cells identified by the H3 index format.

Capabilities

Neighborhood disks

• For origin cell 89283082e6bffff and radius 1, returns exactly 7 unique cells (the origin plus its six immediate neighbors). @test
• For the same origin and radius 2, returns exactly 19 unique cells and fully contains every cell from the radius-1 result; ordering is irrelevant but duplicates are not allowed. @test

Perimeter rings

• For origin cell 89283082e6bffff and radius 2, returns exactly 12 unique cells that exclude the origin and do not overlap the radius-1 perimeter. @test

Adjacency checks

• Using the origin above, reports True for each cell produced by cells_on_ring(origin, 1) and False for each cell produced by cells_on_ring(origin, 2) generated by this implementation. @test

Shortest paths

• With the same origin and any radius-2 perimeter cell, returns a path that starts and ends with the provided cells, has length 3 (radius + 1), and ensures every consecutive pair is adjacent. Paths for other distances must likewise be minimal in step count. @test

Implementation

@generates

API

def cells_within_radius(origin: str, steps: int) -> list[str]:
    """Return the origin and all grid cells reachable within the given number of steps."""

def cells_on_ring(origin: str, steps: int) -> list[str]:
    """Return cells that are exactly the given number of steps away from the origin."""

def are_adjacent(cell_a: str, cell_b: str) -> bool:
    """Return True if the two cells share a grid edge at the same resolution."""

def shortest_path(start: str, end: str) -> list[str]:
    """Return an ordered list of cells forming a minimal stepwise path from start to end, inclusive."""

Dependencies { .dependencies }

h3 { .dependency }

Hexagonal grid indexing and navigation toolkit used for cell neighborhoods, adjacency, distance, and routing. @satisfied-by