Coverage Compaction Helpers

Utilities for shrinking and expanding coverage sets of hexagonal grid cells while preserving the represented area.

Capabilities

Compact uniform coverage

• Given the complete set of seven resolution-4 child cells belonging to a single resolution-3 parent, compaction returns exactly that parent cell and expanding back to resolution 4 yields the original seven identifiers (order ignored). @test

Reject mixed resolutions

• Passing a mixture of resolution-4 and resolution-5 cells raises a ValueError before any compaction is attempted. @test

Expand to target resolution

• Expanding a compacted set that mixes resolution-3 parents and resolution-4 children to resolution 5 returns the full set of resolution-5 children covering the same area without duplicates. @test

Preserve idempotence

• Compacting a collection that cannot be reduced because no parent has all children present returns the same cell identifiers (ignoring ordering). @test

Implementation

@generates

API

from typing import Iterable, List

def compact_coverage(cells: Iterable[str]) -> List[str]:
    """
    Reduce a collection of uniform-resolution cell identifiers to the smallest set that covers the same area.
    Raises ValueError when input is empty, contains invalid identifiers, or spans multiple resolutions.
    Returns unique identifiers sorted in deterministic order.
    """

def expand_coverage(cells: Iterable[str], resolution: int) -> List[str]:
    """
    Expand a compacted or mixed-resolution collection to the specified resolution, returning unique identifiers.
    Raises ValueError when resolution is negative or any input cell is already deeper than the target.
    Output identifiers are sorted in deterministic order.
    """

Dependencies { .dependencies }

h3 { .dependency }

Provides hierarchical hexagonal grid operations for cell compaction and expansion.