[Feature Proposal] Geodesic polygon coverage

[holoskii]

Summary
We (Yellowbrick Data) have implemented geodesic polygon coverage — a function that returns the set of H3 cells covering a spherical polygon, with edges interpreted on the sphere (great-circle segments). We’d like to contribute this upstream.

Motivation / Use cases

• Covering large spherical regions (e.g., big-circle/spherical-cap areas, airspace/maritime zones) where planar approximations fall short.

Proposed behavior (high level)

• Input: outer polygon, optional holes, target resolution res, flags to control mode
• Output: set of H3 cells that cover the spherical polygon under the chosen semantics.

API surface (illustrative; happy to follow project preferences)

• Core C: either extend existing polygon-coverage API with geodesic/semantics flags, or add a new function (e.g., polygonToCellsGeodesic(...)).

Status

• We have working production code and tests; adapting to H3 style, tests, and integrations should be straightforward on our side.

Questions for maintainers

• Is geodesic polygon coverage in scope for core H3?
• Would you prefer this as an extension of the existing polygon API (via options) or as a new function?

Next steps
If this aligns with the project direction, we’ll open a Draft PR. Thanks!

Makar Ivashko
(on behalf of the team at Yellowbrick Data)

[isaacbrodsky]

Yes, spherical/geodesic containment support is in scope for polygonToCells. When we previously discussed this, we expected to add that as an additional flag to the polygonToCells function: https://github.com/uber/h3/blob/master/dev-docs/RFCs/v4.0.0/polyfill-modes-rfc.md (Note this document doesn't match exactly what happened, since bit 3 being 0 actually refers to Cartesian containment by default)

We'd be happy to review your PR on it. Thanks for the contribution!

[holoskii]

Thanks for the quick reply
Two quick process questions:

1. Would you prefer a single end-to-end PR, or a short series?
2. If a series, is it OK for the first PR to land the core C implementation, with tests/docs following in subsequent PRs?

A couple of notes to set expectations:

• Geodesic coverage is inherently more expensive for large polygons; we’ve seen noticeably higher runtimes vs. Cartesian.
• To mitigate this, we applied several algorithm optimizations; these require broader changes than a simple intersection-routine swap.

If that plan sounds good, we’ll open a Draft PR next