Cell-specific area calculations

[ajfriend]

Adds functions to compute the exact spherical area of individual H3 cells:

• cellAreaRads2
• cellAreaKm2
• cellAreaM2

Also exposes to the public API some related functions for computing
haversine (great circle) distance between spherical points, and the
lengths of H3 unidirectional edges:

• pointDistRads
• pointDistKm
• pointDistM
• exactEdgeLengthRads
• exactEdgeLengthKm
• exactEdgeLengthM

[coveralls]

Coverage increased (+0.04%) to 99.187% when pulling a0ccdef on ajfriend:area into f8bbc4b on uber:master.

[ajfriend]

Note: I need to look into the conditioning of different methods for computing distance.

• https://gis.stackexchange.com/questions/4906/why-is-law-of-cosines-more-preferable-than-haversine-when-calculating-distance-b
• https://cs.nyu.edu/visual/home/proj/tiger/gisfaq.html
• https://www.movable-type.co.uk/scripts/latlong.html

[ajfriend]

In working on this, I've got a couple of questions for the group.

1. Does it make sense to expose functions like these to users?

double H3_EXPORT(pointDistRads)(GeoCoord a, GeoCoord b);
double H3_EXPORT(pointDistKm)(GeoCoord a, GeoCoord b);
double H3_EXPORT(pointDistM)(GeoCoord a, GeoCoord b);

(I'm using pointDist* since GeoCoord will change to GeoPoint in 4.0.)

I'm thinking it does, since the area, length, and bounding box algorithms all depend on a "great circle" distance calculation. Also, this calculation depends on our choice for model of the earth, the earth radius we're using, and the distance formula we've chosen. Exposing this to users could help them debug things when numbers don't seem to add up quite right.
Also, exposing the Rads version makes it easier to use for spherical bodies other than the Earth.

2. I think it would make sense to make sure that every downstream function uses one of the three listed above, to ensure everything in the library is using the same distance logic.

3. Does it make more sense for these functions to be pass-by-reference, or pass-by-value?

   • Pass-by-value seems a little cleaner/safer, but the library seems to prefer pass-by-reference for structs (to reduce data on the stack, I assume).
   • However, GeoCoord objects are pretty small (just two doubles), so I'm not sure the data on the stack concern is as relevant.
   • Curious to learn how we've thought about this in the past!

[ajfriend]

Very likely, the answer will be "Just use pass-by-reference", but I wanted to make sure that it still made sense, rather than going with it blindly.

[nrabinowitz]

Super exciting to see these come together!

[ajfriend]

I implemented and tested 3 different distance functions:

• _pointDist_lawOfCosines
• _pointDist_mystery
• _pointDist_haversine

They seem to be numerically indistinguishable; they each fail the cellArea test somewhere between a tolerance of 1e-6 and 1e-7.

However, I'm not sure if there's a performance benefit of one over the others (and this might also be affected by our choice ov pass by reference vs value.)

[ajfriend]

Sounds like everyone on stackoverflow thinks pass by reference is the way to go:

• https://stackoverflow.com/questions/161788/are-there-any-downsides-to-passing-structs-by-value-in-c-rather-than-passing-a
• https://stackoverflow.com/questions/30980759/when-should-i-pass-or-return-a-struct-by-value/30981026

I'll update!

[isaacbrodsky]

I assume for these functions they have undefined output when the H3 index is invalid.

[ajfriend]

yes, should we document that? or test for validity?