Summary

Adds the geodesic traversal mode to polygonToCellsExperimental, letting us follow true great-circle edges when filling massive polygons (think continental footprints and polar caps). The PR builds the geodesic stack from the ground up—new vector math helpers, bounding caps, iterator wiring, and plenty of validation coverage—while keeping the default planar behavior unchanged (and safely rejecting geodesic flags on the legacy API).

Highlights

• New geodesic mode

  • Introduces FLAG_GEODESIC_MASK (with helpers) so callers can opt into geodesic coverage; validates acceptable containment modes (FULL, OVERLAPPING) at both maxPolygonToCellsSizeExperimental and polygonToCellsExperimental.
  • Dispatches a dedicated geodesic iterator path that reuses the existing traversal logic but evaluates cells using great-circle geometry.

• Core geometry plumbing

  • Adds GeodesicPolygon acceleration structures + helpers (geodesicPolygonCreate/Destroy, containment, boundary/cap intersection tests).
  • Extends the vector toolkit (latLngToVec3, cross/dot/normalize, distance helpers) and new conversions: vec3dToCell, cellToVec3, cellToGeodesicBoundary, cellToSphereCap.
  • Pulls bounding-cap tables into sphereCapTables.h for both prod code and tests; exposes SphereCap/AABB helpers.

• Iterator & polyfill updates

  • Refactors polygon iterators into polyfill_iterator.h (with _extra context) and wires in geodesic_iterator.c.
  • Ensures geodesic flags short-circuit the legacy planar polygonToCells path.

• Benchmarks, fuzzers, and tests

  • Benchmarks: geodesic variants for existing benchmark.
  • Fuzzers now exercise geodesic flag permutations.
  • Added new test suites: testGeodesicPolygonToCellsExperimental, testSphereCap, testVec3d, plus extended testBBoxInternal, testPolygonToCells(Experimental) flag validation, and memory-failure coverage.
  • Hooks new tests into CMakeLists.txt/CMakeTests.cmake.

• Documentation

  • Updates the Regions API docs to explain the geodesic flag, trade-offs, and usage tips.

Attribution

This geodesic polyfill work originated at Yellowbrick Data (where I’m currently employed). We’re upstreaming it to the H3 project so the broader community can benefit and use it for coverage.