perf: cover polygons by descending the geohash tree

[mailletf]

Problem

polygons_to_geohashes flood-filled at the target precision, testing every cell against the full polygon. Cost tracked the polygon's area, and each test walked every vertex.

Fix

Walk the geohash tree top-down. A cell disjoint from the polygon prunes its whole subtree; a cell the polygon contains yields all 32ⁿ descendants with no further geometry tests; only cells straddling the boundary subdivide. Cost now tracks the perimeter.

One PreparedGeometry::relate per visited cell answers intersects and contains together, and its R*-tree keeps each call proportional to the edges near that cell rather than the polygon's vertex count.

Both halves are needed. Measured separately, plain Contains inside the descent is ~6× slower than the old code, and relate without the descent is a net loss for the intersects-only case (943 ms → 1570 ms on verdun p9), because relate computes the full DE-9IM matrix where Intersects short-circuits.

Benchmarks

case	before	after
verdun p8 inner=false	48.4 ms	17.4 ms	2.8×
verdun p8 inner=true	86.4 ms	16.6 ms	5.2×
verdun p9 inner=false	943 ms	121 ms	7.8×
verdun p9 inner=true	2524 ms	121 ms	20.9×
verdun p10 inner=false	32.8 s	2.58 s	12.7×
verdun p10 inner=true	90.4 s	2.48 s	36.5×
whitehorse p7 inner=false	1472 ms	146 ms	10.1×
whitehorse p7 inner=true	3396 ms	141 ms	24.1×
whitehorse p8 inner=false	53.5 s	5.48 s	9.8×
whitehorse p8 inner=true	117 s	5.85 s	20.0×

Output sets are identical to the previous implementation in every case. Below p6 it is a wash — the gain scales with precision because interior cells stop costing anything.

Also

• New ghbits module: a geohash of precision 1..=12 is 5·p interleaved bits and fits in a u64, so cells live in an FxHashSet<u64> and a cell's bbox is a couple of shifts rather than a base32 decode. Verified against the geohash crate across all 12 precisions, both bit parities, and the grid corners.
• Precision is validated up front (1..=12) instead of failing later inside encode.
• The descent seeds at the deepest level whose cover is still small, so it does not spend a relate call per cell on levels where the cell dwarfs the polygon and the R*-tree cannot prune.

⚠️ Breaking

Removes pub fn seed_interior_point_fast. The descent starts from the grid and never needs a point known to be inside the polygon, so the whole centroid → 24 probes → bbox centre → 4×4 grid → interior_point ladder has no callers. Deleting it also removes a failure mode rather than just dead code: the old walk silently skipped any polygon the ladder could not seed.

Tests

A brute-force oracle over both WKT fixtures checking every cell in the bounding box with no descent and no prepared geometry, plus a refinement-consistency check. The MultiPolygon regression tests from #30 still pass — the descent walks each part over the whole grid, so that class of bug is now structurally impossible.

Behaviour changes (deliberate)

• inner=true keeps boundary-touching cells. Containment is now DE-9IM contains — the cell's interior inside the polygon, boundaries allowed to meet — for all polygons. The old fast path for hole-free polygons rejected any cell sharing an edge or vertex with the polygon boundary, so grid-aligned geometry gets more cells than before: a polygon exactly equal to one p5 cell now yields all 32 of its p6 children with inner=true, not just the 12 interior ones. This matches shapely's contains and how holed polygons were always treated; off the grid lines a boundary cell genuinely crosses the edge and is excluded either way, so non-aligned covers are unchanged. Pinned by test_inner_cover_keeps_boundary_touching_cells (Rust + Python).
• Out-of-range coordinates now error. cover_range clamps grid indices, so a polygon past the antimeridian or a pole would have come back as a silently empty cover, and one straddling the domain edge as a half cover. The polygon's bounding box is validated up front and raises InvalidCoordinateRange, restoring the old flood-fill's contract.

[mailletf]

This change is part of the following stack:

• fix: don't drop multipolygon parts whose seed lands in an earlier part #30
  • perf: cover polygons by descending the geohash tree #31 ◀
    • perf: optionally dictionary-encode geog_id in the Arrow mapping output #39
      • perf: cover large polygons across Rayon workers #40
        • fix: reject null list slots and empty geohashes #42

_{Change managed by git-spice.}

[Copilot]

Pull request overview

This pull request optimizes polygon-to-geohash coverage using hierarchical descent, packed geohash bits, and prepared geometry.

Changes:

• Adds top-down pruning and subtree emission.
• Adds packed geohash encoding and precision validation.
• Removes obsolete interior-point seeding.
• Updates dependencies and regression documentation.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Summary	Review status
tests/test_geohasher.py	Updates crescent regression documentation.	No findings.
tests/conftest.py	Updates crescent fixture documentation.	No findings.
src/lib.rs	Implements hierarchical coverage and packed geohashes.	Moderate: Boundary-aligned polygon minima can miss west/south touching cells. Use boundary-inclusive lower-index calculation and add a regression test.
Cargo.toml	Adds rustc-hash.	No findings.
Cargo.lock	Locks the new dependency.	No findings.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[mailletf]

Good catch — real bug, fixed in f924e36.

The asymmetry was the tell: floor on the upper bound already names the cell east/north of a grid-aligned maximum (the touching one), so only the lower bound was dropping them. A polygon equal to one p5 cell covered 4 of the 9 cells it meets. Switched the lower bound to ceil(v / span) - 1, clamped at zero, and added test_grid_aligned_polygon_reaches_touching_neighbours — it fails on the old code with exactly those 4 cells.

The seed range only has to be a superset; relate still decides what is kept, so the cost of an extra seed is one topological test.