Add support for full containment and overlapping modes in polygonToCellsExperimental

[nrabinowitz]

Adds support for full containment mode and overlapping modes in polygonToCellsExperimental.

• Defines an enum for the containment modes. My assumption here is that the lowest 4 bits of the 32-bit flag are reserved for containment modes (not sure that we'd need more than 7, but wanted to be on the safe side), and that we'd use them as an integer, not as bitwise flags, since the modes are mutually exclusive.
• Implements the check for containment in iterStepPolygonCompact. This was very straightforward as we already have cellBoundaryInsidePolygon polygon available.
• Implements the check for overlapping cells in iterStepPolygonCompact. This checks center point inclusion first, then shares code with the full containment check, substituting a new cellBoundaryCrossesPolygon check for cellBoundaryInsidePolygon.
• Adds some very basic tests, which essentially just duplicate existing polyfill tests with full containment and overlapping turned on, substituting an empirically determined result and checking that it's reasonable compared to the center containment mode.
• Updates all tests to use modes instead of 0 for flags.

TODO:

• [x] We should probably clean up the tests and use CENTER_CONTAINMENT instead of 0 for the flag value in existing tests.
• [x] There are a couple of error branches here that I think we can get coverage on by sticking invalid cells into the iterator object.
• [ ] I'd love better tests here, though I'm not sure what would make sense.

[coveralls]

coverage: 98.806% (+0.02%) from 98.784% when pulling f0f1b45adff09a01f09c9fc29fc6e9e0f7c1cf56 on nrabinowitz:polyfill-contained into 6c1b00307fa7f2b3babf68006190120ac640c06c on uber:master.

[nrabinowitz]

@isaacbrodsky I believe the latest commit should close the holes in coverage.

[michaelbrichko]

Thanks for adding this functionality !! How mature is it? Are there any knows issues for overlapping functionality? Any known gaps ?

[nrabinowitz]

Thanks for adding this functionality !! How mature is it? Are there any knows issues for overlapping functionality? Any known gaps ?

Well, you can see it was merged two weeks ago, so that's how mature it is :). But we've done a fair amount of testing against the older algo, and it seems to behave as expected. Overlapping mode seems to work as expected, we aren't aware of any issues, but it's hard to extensively test this. The main (expected) issue is that overlapping mode is slower than the other modes, as discussed in this PR.

[michaelbrichko]

Ok, thanks for quick answer !

[BrendanJM]

Look great! Has this been released yet? If not, is there a stable tag we could reference? We use the h3-py bindings and it looks like it’s been a bit since the last release.

[bertday]

Hello H3 friends! 👋

I use H3 often and this PR would be tremendously helpful. Is there any timeline for when a new release might come out with the new polyfill modes?

Thank you for all of the hard work that went into this!