line interpolate point across MetricSpaces

[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.

---

LineInterpolatePoint is currently Euclidean only. As part of #1216, I wanted to make this functionality work across metric spaces.

// geos
line_interpolate_point(line, 0.8, true)
// georust::geo
Euclidean.interpolate_point_at_ratio_from_start(line, 0.8)

// also:
Haversine.interpolate_point_at_ratio_from_start(line, 0.8)
Geodesic.interpolate_point_at_ratio_from_start(line, 0.8)
Rhumb.interpolate_point_at_ratio_from_start(line, 0.8)

As a bonus, I also wanted to add some (IMO) long missing niceties to the api.

// geos communicates "from end" with a negative distance
line_interpolate_point(line, -0.8, true)
// georust::geo
Euclidean.interpolate_point_at_ratio_from_end(line, 0.8)

// geos communicates "distance" rather than "ratio" by passing in `false`
line_interpolate_point(line, 0.8, false)
// georust::geo
Euclidean.interpolate_point_at_distance_from_start(line, 0.8)

// geos
line_interpolate_point(line, -0.8, false)
// georust::geo
Euclidean.interpolate_point_at_distance_from_end(line, 0.8)

You can use all those methods across metric spaces:

Haversine.interpolate_point_at_ratio_from_end(line, 0.8)
Geodesic.interpolate_point_at_distance_from_start(line, 0.8)
Rhumb.interpolate_point_at_distance_from_end(line, 0.8)
// etc.

The names are admittedly long. It's my own preference to have verbose method names over geos-like "mode" parameters.

Bonus

While working on this, and filling out the deprecations, I found and fixed a bug in LineStringSegmentizeHaversine which was using the legacy LineInterpolatePoint, which was Euclidean only. It's easy to make this kind of mistake, the way we've historically not been very explicit about which metric space an algorithm is for.

[michaelkirk]

This is a big PR, but it's overwhelmingly docs and tests, I swear!

[michaelkirk]

At first I assumed I wanted to do line_string.lines().rev() but that's not quite what I needed.

For example, given a line string with points a, b, c:

lines():
1. a->b
2. b->c

lines().rev():
1. b->c
2. a->b

But what I want is:

rev_lines():
1. c->b
2. b->a

[michaelkirk]

I've just pushed up a bike-shedding commit.

There are two equivalent new APIs:

Euclidean.point_at_ratio_from_start(&line_string, 0.5)
line_string.point_at_ratio_from_start(&Euclidean, 0.5)

Previously, the deprecation pointed you to the first version. I changed that deprecation to now recommend the latter.

I don't think it matters much, but the second version is closer to the existing API, so I think it'll be slightly easier to migrate to.

[michaelkirk]

This is a bugfix in the case of Haversine