`Point` instead of `GeoPoint`?

[ajfriend]

Within the function names Point is now synonymous with lat/lon. It feels a little redundant to me to then use GeoPoint for the lat/lon data type. Maybe it should just be Point?

Originally posted by @sahrk in https://github.com/uber/h3/issues/403#issuecomment-730844967

[lokkju]

One issue with this is that to anyone from a geoinformatics or GIS background, a Point is represented as [X,Y], which translates to [longitude,latitude]. It's confusing enough that H3 currently represents it's points as [Y,X] / [latitude,longitude]; changing the name to Point would remove the current naming differentiation between the way points are represented in H3 vs virtually every other geometry package (GeoJSON, WKT, etc).

I'd really like to see this fixed internally in H3, so it uses [X,Y] / [longitude,latitude] ordering like every other major geographical package, but it would be a confusing and breaking change for much existing code.

At the least, it'd be nice to have a pretty big warning in the documentation that GeoPoints (and all other coordinate ordering) is the (programmatically) non-standard [Y,X]/[latitude,longitude]

[sahrk]

One issue with this is that to anyone from a geoinformatics or GIS background, a Point is represented as [X,Y], which translates to [longitude,latitude].

But (lat, lon) are polar coordinates, not cartesian coordinates, and in polar coordinates the polar angle is given before the azimuthal angle. We sometimes find it convenient to treat them as if they are cartesian coordinates, which I suppose led to the convention of changing the order. But with the exception of that representation convention geographic coordinates are always referred to as "latitude, longitude". For example, I just looked up a ship at vesselfinder.com and it gives the latitude first, not the longitude.

It's confusing enough that H3 currently represents it's points as [Y,X] / [latitude,longitude]; changing the name to Point would remove the current naming differentiation between the way points are represented in H3 vs virtually every other geometry package (GeoJSON, WKT, etc).

H3 represents cartesian (x, y) coordinates using the Vec2D structure. It is unrelated to GeoPoint, and stores the components in x, y order.

I do agree that, though geographic coordinates are the only kind of point used by the API, the term Point is too ambiguous. Rather than changing GeoPoint to Point, it might be better to use GeoPoint throughout (which would require changing function names).

[lokkju]

But (lat, lon) are polar coordinates, not cartesian coordinates, and in polar coordinates the polar angle is given before the azimuthal angle. We sometimes find it convenient to treat them as if they are cartesian coordinates, which I suppose led to the convention of changing the order

You're of course correct that it's standard, in geography, to list [latitude,longitude] pairs; I believe the origin of the [X,Y] standard for geoinformatics was the OGC spec for WKT, considering that WKT is designed to represent any multi-coordinate system, and longitude counts left to right, while latitude counts bottom to top; when translated to x/y this means the longitude/latitude approach made the most sense. Since then, GeoJSON and most other standards that use a Point type expect this ordering.

H3 represents cartesian (x, y) coordinates using the Vec2D structure. It is unrelated to GeoPoint, and stores the components in x, y order.

Apologies for being unclear; I meant internally in it's quasi-geojson formats.

What I have seen done that may be a good solution is to rename it to LatLngPoint; this makes the ordering explicit, and differentiates it from any other sort of [X,Y] point.

[nrabinowitz]

What I have seen done that may be a good solution is to rename it to LatLngPoint; this makes the ordering explicit, and differentiates it from any other sort of [X,Y] point.

I'd be in favor of this - perhaps just LatLng? If the current geoToH3 and h3ToGeo functions were called latLngToCell and cellToLatLng it would save us a great deal of user confusion I suspect.

[sahrk]

What I have seen done that may be a good solution is to rename it to LatLngPoint; this makes the ordering explicit, and differentiates it from any other sort of [X,Y] point.

I'd be in favor of this - perhaps just LatLng? If the current geoToH3 and h3ToGeo functions were called latLngToCell and cellToLatLng it would save us a great deal of user confusion I suspect.

I'm partial to latLon, rather than latLng, but I think either would neatly solve all the issues. Thanks @lokkju !

[lokkju]

linking to #121 - there is still nothing in the documentation about the datum and ellipsoid being used for latitude and longitude coordinate functions, and the only reference in code is a comment: earth radius in kilometers using WGS84 authalic radius

[isaacbrodsky]

+1 to the idea of explicitly stating latLng/latLon. This seems to be the clearest option by far.

[ajfriend]

I also like the explicitness of latlng/latLng/latlon/latLon; you might notice the camel case bugging me here, but that's a separate issue :)

More importantly, in terms of lon vs lng, we should probably pick one. A quick search shows that the codebase is currently inconsistent. Should we start an issue to settle it? Or a mini-RFC?

lng vs lon fits well under the currently-active v4.0 terminology work.

[dfellis]

Also a +1 for LatLng (camelCase 4ever!). As for Lng vs Lon I personally prefer Lng. Implicit vowels works well enough that some languages are based on it. ;) While Lon reminds me of Lon Lon Ranch and I just can't take it seriously. That's not a good enough reason to actually go with one or the other, but I think this is entirely down to personal preferences as both are used in the wild.

[sahrk]

linking to #121 - there is still nothing in the documentation about the datum and ellipsoid

The datum for H3 is a sphere with the WGS84 authalic radius. I agree that should be in the documentation.

[sahrk]

Also a +1 for LatLng (camelCase 4ever!). As for Lng vs Lon I personally prefer Lng. Implicit vowels works well enough that some languages are based on it. ;) While Lon reminds me of Lon Lon Ranch and I just can't take it seriously. That's not a good enough reason to actually go with one or the other, but I think this is entirely down to personal preferences as both are used in the wild.

An argument for Lon: "latitude/longitude" is always abbreviated verbally as "lat/lon". Because of that GeoPoint uses lon for the longitude field. If we go with Lng then GeoPoint should probably also be changed for consistency.

[nrabinowitz]

When we have to write a mini-RFC to decide between lng and lon the naming discussion has jumped the shark :). I agree that we should be consistent. I have a slight preference for lng as retaining the ŋ phoneme, but we should just pick one.

[ajfriend]

I'm also in favor of lng.

So it sounds like the current summary is that we'll be renaming GeoPoint to LatLng.

[ajfriend]

Here's a currently broken PR which shows the changes to the RFC and in h3api.h: https://github.com/uber/h3/pull/454