georust
Clarification Needed on Bearing Output Range
Bearing (azimuth) is typically measured either in the range of 0° to 360° or in the signed range of -180° to +180°. After exploring the relevant methods in the crate, I discovered that they produce results in the signed range of -180° to +180°. However, this is not clearly stated in the current documentation.
To prevent any confusion or incorrect assumptions by users, I suggest updating the documentation to explicitly mention that the output of these methods lies in the signed range.
If this concern is valid, I am willing to create a pull request to address this documentation update.
To make this even more confusing, I noticed HaversineBearing and GeodesicBearing return -180..180, while Rhumb returns 0..360!
I'm going to take a stab at unifying this as part of #1181
My understanding is the same as yours - that it is more common for GIS libraries to represent west as 270, rather than -90, so the new traits I'm introducing as part of #1181 will switch to that convention. Since it's introducing a new set of traits/methods, it seems like a good time for this break.
And I'll document it. =)
I recently discovered another unexpected (for me) behaviour that isn't explicitly documented in either geographic-lib or geo. While other bearing calculations return 0 for two identical points, GeodesicBearing returns +180 in such cases.
Interesting. I'm not really sure what to expect in that situation.
Just thinking about it conceptually, it seems like bearing is undefined in the case of no movement.
But if there is a coherent argument for any particular value, I'd consider adopting it.
Yes, the bearing for a stationary point is technically undefined. Using 0.0 is not ideal as well since it can be a valid bearing for non-equivalent points, which could cause confusion. However, it might still be better to consistently fallback to a specific value (such as 0.0), provided that it's clearly documented.
Other alternatives, such as using Option, -1.0, or NaN, would provide more precise semantics but might be considered more disruptive in terms of breaking changes. And the current default value of 180.0 for geodesic bearing seems to be the least intuitive in this context.
Closing the loop on this - the new line measure traits in #1216 uniformly output a bearing in 0...360.
I decided to leave the legacy traits as they are (with haversine and geodesic outputting -180...180), in hopes of surprising fewer people.
https://github.com/georust/geo/pull/1222 deprecates the legacy traits, so they'd go away at some point.