(Multi)polygon helper functions

[ajfriend]

Continuation of #1101, please review that first.

• public API functions

  • destroyGeoMultiPolygon

• internal functions

  • destroyGeoLoop
  • destroyGeoPolygon
  • geoPolygonAreaRads2
    • note the logic for computing the area of holes properly
  • geoMultiPolygonAreaRads2
  • createGlobalMultiPolygon
    • We need some multipolygon to return when the user provides, for example, all the cells of a given resolution. Other options could work (like all the res 0 cells), but I think this one is nice because it is fairly simple, all the edge arcs are 90 degrees (our area functions can only handle arcs less than 180), and it has seams along the antimeridian, so other downstream libraries are more likely to be able to process it properly (as opposed to, say, one giant "world polygon")

[ajfriend]

Last Thursday, we discussed what cellsToMultiPolygon should return when a user provides cells that cover the entire globe.

One option is to raise an error. However, I'm not a fan of this choice because I think it creates an artificial discontinuity in the API. Users should be able to supply no cells, all cells, and everything in between, and expect a reasonable answer, without having to catch and handle a special case. It would also be nice for cellsToMultiPolygon and multiPolygonToCells (which doesn't currently exist in the API) to be inverses of each other, including on the extreme input examples.

The other (current) option is to return a "globe multipolygon or polygon", which is what I was planning with createGlobeMultiPolygon. As mentioned above, the current implementation returns 8 triangles that cover the globe, with all edge arcs at 90, and seams along the antimeridian and poles. This choice is nice because we expect that this polygon would be easier for downstream libraries to handle, which, for example, may expect a seam along the antimeridian for polygons that would otherwise cross it. It has the downside of being otherwise unrelated to the geometry of H3.

Another option is to return an alternative globe multipolygon that has something to do with the H3 geometry, like the base icosahedron. This has the downside of being less nice for downstream libraries, but, on the other hand, it probably doesn't make sense to single out this one specific case, since any other valid output might cross the antimeridian and/or poles.

I don't like the idea of raising an error, and the implementation can always change for the globe multipolygon, so I'll try implementing createGlobeMultiPolygon with the base icosahedron for now.

[ajfriend]

After looking into it, I don't see an obvious simple construction of the icosahedron faces for createGlobeMultiPolygon, since we don't store the icosahedron vertices explicitly anywhere in the code. I think I could take the pentagon vertices for this purpose, but that construction still seems more complicated than what I currently have.

For the time being, I think I prefer the existing construction, since it is the simplest thing that meets the needs of #1103. I'll make a follow-up task where we can consider if we'd prefer some other construction.

[ajfriend]

#1110

[nrabinowitz]

Looks good to me 👍. After our discussion, I think the triangle-based globe multipolygon is a reasonable option.