Be clearer about degrees vs radians

[EliRibble]

I just spend some time figuring out how H3 expects latitude and longitude to be expressed in degrees vs radians. I wasn't able to find any mention the org marketing site of preferring degrees over radians. I wasn't able to find any mention of degrees vs radians in the terminology site. I also didn't find it mentioned in the API reference. The definition of CellBoundary indicates that the boundary is defined in lat/long, and the LatLng struct is specific about being in radians. A sample Python program:

import h3

#cell = 644721767721573641
cell = "8f2830828019d09"
bounds = h3.cell_to_boundary(cell)
for b in bounds:
    print(b)

produces the following output:

8f2830828019d09
(37.77471334627101, -122.41822577410242)
(37.774718252055095, -122.41822265074703)
(37.77472263858535, -122.41822632302795)
(37.774722119331315, -122.4182331186643)
(37.77471721354722, -122.41823624201916)
(37.77471282701717, -122.41823256973821)

These are the lat/long in degrees, showing that at least one language binding performs to conversion for you. If you run bin/cellToBoundary --index 8f2830828019d09 you will get this output:

bin/cellToBoundary --index 8f2830828019d09
8f2830828019d09
{
   37.774713346 -122.418225774
   37.774718252 -122.418222651
   37.774722639 -122.418226323
   37.774722119 -122.418233119
   37.774717214 -122.418236242
   37.774712827 -122.418232570
}

This may lead one (like me) to mistakenly believe that the output of cellToBoundary is degrees because that's what's printed.

It would be very useful to newbies to do one or more of the following:

• Use an opaque struct pattern to be clear about what the units for a given value are. This provides a compiler-enforced way to signal users.
• Improve the API reference documentation to explicitly mention units
• Alter the sample programs to make it clearer a conversion is being performed, perhaps by printing the value in radians first, then the conversion secondarily, with labels.

I'm open to making PR(s) myself with some changes, if after some discussion the owners of the project are open to it. Thoughts?

[isaacbrodsky]

I think the current pattern is that the C library deals with radians, and all of the bindings (including the CLI and so on) accept degrees. It has been our observation that most users have their coordinates in degrees and this makes that more convenient.

Regarding the opaque struct pattern, I think we try to be very conservative about breaking API changes in order to not cause issues for our users. I am not entirely sure what you suggest about that, but I would prefer not to change APIs if we can avoid it.

We could certainly improve this aspect of the documentation. Happy to review & accept a PR to the docs to clarify what exactly accepts radians vs degrees.

The filter programs in e.g. https://github.com/uber/h3/blob/master/src/apps/filters/cellToBoundary.c are likely to be removed soon in favor of the combined h3 CLI program. (https://github.com/uber/h3/blob/master/src/apps/filters/h3.c Note: I would not add duplicate output to the h3 program because it is intended to be used as a UNIX style filter. So a command line argument would be appropriate but not duplicating the output.) As such I wouldn't recommend updating those old filters. However, updating the examples could be helpful.

[EliRibble]

Thanks for the response.

Based on your explanation, it sounds like the Swift bindings that I used in my original exploration, which I believe are just a few weeks old, probably should have output degrees like other language bindings. I can discuss that with the owners of that project.

I'll see if I can track down concrete areas of the documentation to create PRs.