Customizable metric space for line measures

[michaelkirk]

• I agree to follow the project's code of conduct.
• I added an entry to CHANGES.md if knowledge of this change could be valuable to users.

---

Motivation

Currently, our Haversine metric space calculation uses the IUGG's "mean radius", but there are several other reasonable values. Similarly, the Geodesic internally uses Karney's geographic algorithms which support other geoid parameters.

Proposal

By reorganizing our traits, we can let users take advantage of all the associated algorithms (length, densify, distance) for any given (potentially customizable) metric space.

The trick is, almost nobody (by my count) actually wants this configurability, so the resultant API must not make it burdensome for the vast majority who want the "default" case.

Some conversation in #1274 and another in #1140 lead me to revisit the recently overhauled line_measure traits, and that it's possible to support this kind of customization in a reasonable way.

There are a lot of changes, but they are pretty mechanical. You can get a pretty good idea of the kinds of changes our users will need to make by reviewing this diff.

As well as being more expressive, I actually prefer where the code is now, without the turbo-fish. I just wish I'd avoided the churn by thinking of it before the big changes in the v0.29.0 (primarily #1216) were released (on 2024-10-30):

// Before v0.29.0)
p1.haversine_distance(p2);
line_string.haversine_length();
line_string.densify_haversine(100);

// Currently (as of v0.29.0)
Haversine::distance(p1, p2);
line_string.length::<Haversine>();
line_string.densify::<Haversine>(100);

Version 1 of this PR - move trait associated functions to instance methods:

// Common case:
Haversine.distance(p1, p2);
Haversine.length(&line_string);
Haversine.densify(&line_string, 100);

// Custom case:
let planet_mars = CustomHaversine::new(3_389_500.0);
planet_mars.densify(&line_string, 100);

Version 2 of this PR - (based on some PR feedback) make all Haversine customizable (removing distinction of CustomHaversine), and make the "common" Haversine a constant:

// Common case:
HAVERSINE.distance(p1, p2);
HAVERSINE.length(&line_string);
HAVERSINE.densify(&line_string, 100);

// Custom case:
let planet_mars = CustomHaversine::new(3_389_500.0);
planet_mars.densify(&line_string, 100);

Version 3 of this PR - (based on some further feedback in discord) Same as version 2 but stop SHOUTING the Haversine constant name, so it nicely avoids the redundant implementations like v2, but still looks like v1 from a user perspective:

// Common case:
Haversine.distance(p1, p2);
Haversine.length(&line_string);
Haversine.densify(&line_string, 100);

// Custom case:
let planet_mars = HaversineMeasure::new(3_389_500.0);
planet_mars.densify(&line_string, 100);

References

This solves the same problem as #1220, but more generally.
Tracking issue for line_measure overhaul here #1181

[michaelkirk]

I've only moved this to geo/CHANGES.md where I think it belongs.

[urschrei]

Haven't reviewed, but this is a lot better from a UX perspective, and – I think – worth the churn.

[michaelkirk]

Converting this to a draft while I incorporate some feedback from @lnicola - what do you think, does
Make all Haversine customizable, removing CustomHaversine make things better or worse?

In summary:

// "long ago" before 0.29.0
point1.haversine_distance(point2)
point1.rhumb_distance(point2)

// as of 0.29.0
Haversine::distance(point1, point2)
Rhumb::distance(point1, point2)

// v1 of this PR:
CustomHaversine::new(3_389_500.0).distance(point1, point2)
Haversine.distance(point1, point2)
Rhumb.distance(point1, point2)

// current version of this PR (with @lnicola's suggestion - removing "CustomHaversine")
Haversine::new(3_389_500.0).distance(point1, point2)
HAVERSINE.distance(point_1, point_2)
RHUMB.distance(point_1, point_2)

[michaelkirk]

What do you think @lnicola - based on the diff do you prefer the HAVERSINE constant vs having separate Haversine/CustomHaversine { radius } structs?

If so, I'd like to push through the rest of the changes.

[lnicola]

@michaelkirk sorry for the late reply. It looks.. just as I expected. Seems fine to me, but you might want to ask for a third opinion 😀.

[michaelkirk]

This is ready for review!

I've incorporated some more feedback (from discord) into this and updated the description with a "Version 3 of this PR".

[urschrei]

My concern (perhaps badly articulated on Discord), was that we're shipping public structs that can contain an arbitrary value (e.g. the sphere radius in HaversineMeasure), which could be either confusing in downstream libraries / applications or used maliciously. One reasonable counterpoint to this is that downstream users are already trusting us, all kinds of malicious interventions are possible with a newtype wrapper, and that concerned users should be testing and auditing the code they use (HaversineMeasure's radius field is public) and / or engaging in other supply-chain security practices that are not our responsibility.