Polygon Coverage Toolkit

from collections.abc import Iterable
from typing import Any, Mapping, Sequence

def cover_geojson(geometry: Mapping[str, Any], resolution: int) -> list[str]:
    """
    Return a sorted list of unique hexagonal cell identifiers that cover the given GeoJSON Polygon or MultiPolygon.

    - Accepts GeoJSON-style dictionaries with coordinates in [lng, lat] order.
    - Validates geometry type and resolution (0-15) and rejects malformed rings.
    - Every returned identifier must be at the requested resolution.
    """

def cover_polygon(
    outer_ring: Sequence[Sequence[float]],
    holes: Sequence[Sequence[Sequence[float]]] | None,
    resolution: int,
) -> list[str]:
    """
    Convenience wrapper that accepts coordinates as (lat, lng) pairs for the outer ring and optional holes.

    - Applies the same coverage behavior and sorting guarantees as cover_geojson.
    - Rejects rings with fewer than three distinct points.
    """

def cells_to_geojson(cells: Iterable[str], tight: bool = True) -> Mapping[str, Any]:
    """
    Convert a collection of cell identifiers to GeoJSON.

    - Returns a Polygon when coverage is contiguous and tight=True, otherwise a MultiPolygon.
    - Preserves holes present in the coverage and emits coordinates in [lng, lat] order.
    - Rejects invalid cell identifiers.
    """