Unify line measures #1216
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| use geo_types::{CoordFloat, Point}; | ||
|
|
||
| /// Calculate the bearing between two points | ||
| pub trait Bearing<F: CoordFloat> { | ||
| /// Calculate the bearing from `origin` to `destination` in degrees. | ||
| /// | ||
| /// See [specific implementations](#implementors) for details. | ||
| /// | ||
| /// # Units | ||
| /// - `origin`, `destination`: Point where the units of x/y depend on the [trait implementation](#implementors). | ||
| /// - returns: degrees, where: North: 0°, East: 90°, South: 180°, West: 270° | ||
| fn bearing(origin: Point<F>, destination: Point<F>) -> F; | ||
| } |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| use geo_types::{CoordFloat, Point}; | ||
|
|
||
| /// Calculate the destination point from an origin point, a bearing and a distance. | ||
| pub trait Destination<F: CoordFloat> { | ||
| /// Returns a new point having travelled the `distance` along a line | ||
| /// from the `origin` point with the given `bearing`. | ||
| /// | ||
| /// See [specific implementations](#implementors) for details. | ||
| /// | ||
| /// # Units | ||
| /// | ||
| /// - `origin`: Point where the units of x/y depend on the [trait implementation](#implementors). | ||
| /// - `bearing`: degrees, where: North: 0°, East: 90°, South: 180°, West: 270° | ||
| /// - `distance`: depends on the [trait implementation](#implementors). | ||
| /// - returns: Point where the units of x/y depend on the [trait implementation](#implementors). | ||
| /// | ||
| /// [`metric_spaces`]: super::metric_spaces | ||
| fn destination(origin: Point<F>, bearing: F, distance: F) -> Point<F>; | ||
| } |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,12 @@ | ||
| /// Calculate the distance between the `Origin` and `Destination` geometry. | ||
| pub trait Distance<F, Origin, Destination> { | ||
| /// Note that not all implementations support all geometry combinations, but at least `Point` to `Point` | ||
| /// is supported. | ||
| /// See [specific implementations](#implementors) for details. | ||
| /// | ||
| /// # Units | ||
| /// | ||
| /// - `origin`, `destination`: geometry where the units of x/y depend on the trait implementation. | ||
| /// - returns: depends on the trait implementation. | ||
| fn distance(origin: Origin, destination: Destination) -> F; | ||
| } |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,34 @@ | ||
| use crate::{CoordFloat, Point}; | ||
|
|
||
| // REVIEW: Naming alternatives: | ||
| // - LinearReferencing | ||
| // - PointAlongLine | ||
| // - LineInterpolatePoint (postgis) | ||
| // - Interpolate (shapely) | ||
| // - Position (geographiclib) | ||
| // - Intermediate (georust::geo) | ||
| pub trait InterpolatePoint<F: CoordFloat> { | ||
| /// Returns a new Point along a line between two existing points | ||
| /// | ||
| /// See [specific implementations](#implementors) for details. | ||
| fn point_at_ratio_between(start: Point<F>, end: Point<F>, ratio_from_start: F) -> Point<F>; | ||
|
|
||
| // TODO: | ||
| // fn point_at_distance_between(start: Point<F>, end: Point<F>, distance_from_start: F) -> Point<F>; | ||
|
|
||
| /// Interpolates `Point`s along a line between `start` and `end`. | ||
| /// | ||
| /// See [specific implementations](#implementors) for details. | ||
| /// | ||
| /// As many points as necessary will be added such that the distance between points | ||
| /// never exceeds `max_distance`. If the distance between start and end is less than | ||
| /// `max_distance`, no additional points will be included in the output. | ||
| /// | ||
| /// `include_ends`: Should the start and end points be included in the output? | ||
| fn points_along_line( | ||
| start: Point<F>, | ||
| end: Point<F>, | ||
| max_distance: F, | ||
| include_ends: bool, | ||
| ) -> impl Iterator<Item = Point<F>>; | ||
| } |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,71 @@ | ||
| use super::super::Distance; | ||
| use crate::{GeoFloat, Point}; | ||
|
|
||
| /// Euclidean space measures distance with the pythagorean formula - what you'd measure with a ruler. | ||
| /// | ||
| /// You must use projected coordinates with Euclidean space — | ||
| /// for lon/lat points, use the [`Haversine`], [`Geodesic`], or other [metric spaces]. | ||
| /// | ||
| /// [`Haversine`]: super::Haversine | ||
| /// [`Geodesic`]: super::Geodesic | ||
| /// [metric spaces]: super | ||
| pub struct Euclidean; | ||
|
|
||
| /// Calculate the Euclidean distance (a.k.a. pythagorean distance) between two Points | ||
| impl<F: GeoFloat> Distance<F, Point<F>, Point<F>> for Euclidean { | ||
| /// Calculate the Euclidean distance (a.k.a. pythagorean distance) between two Points | ||
| /// | ||
| /// # Units | ||
| /// - `origin`, `destination`: Point where the units of x/y represent non-angular units | ||
| /// — e.g. meters or miles, not lon/lat. For lon/lat points, use the | ||
|
There was a problem hiding this comment. In a similar vein, I don't think we should be referring to "meters or miles" here: non-Euclidean distances are often measured in meters / miles, so this is confusing. "Not lon/lat" is OK, but I'd prefer that this is either implicit (you can't measure lon / lat distances in Euclidean space, and we are in Euclidean space, therefore…) or that we decline to explain with physical-world examples completely. There was a problem hiding this comment.
I believe you, but I honestly didn't know that was true. Can you give me an example?
Oh but you can! And it's a common error that gives you a meaningless result. Look no further than our own example code on the legacy euclidean distance: I think it's important to keep simple relatable language and examples to help mitigate that. There was a problem hiding this comment.
Any physical measurement of distance on the earth's surface (or a simplified abstraction of it) is definitionally non-Euclidean because it's a curved surface. There was a problem hiding this comment. Ah I see, that makes sense. Thank you for bearing with me. I don't have a formal GIS background, so a lot of things that may seem obvious, I truly don't know. I've included the link to [Euclidean Plane], which I hope addresses your ambiguity concern. I've also linked to the I still think it's important that our documentation aim to help people avoid the most likely errors by saying something like:
But the negation:
Feels awkward and unnecessarily mysterious without an example. I now understand how Euclidean space is not the only space that could use meters as a unit, but as an example of what we mean by "not lng/lat", I think it is clarifying, and unlikely to confuse. So if I've said something that is incorrect, let me know and I'll try again to fix it. But if it's more so that you think it reads like it was written for dummies, well then I'd please beg of you to have mercy on us dummies. |
||
| /// [`Haversine`] or [`Geodesic`] [metric spaces]. | ||
| /// - returns: distance in the same units as the `origin` and `destination` points | ||
| /// | ||
| /// # Example | ||
| /// ``` | ||
| /// use geo::{Euclidean, Distance}; | ||
| /// use geo::Point; | ||
| /// // web mercator | ||
| /// let new_york_city = Point::new(-8238310.24, 4942194.78); | ||
| /// // web mercator | ||
| /// let london = Point::new(-14226.63, 6678077.70); | ||
| /// let distance: f64 = Euclidean::distance(new_york_city, london); | ||
| /// | ||
| /// assert_eq!( | ||
| /// 8_405_286., // meters in web mercator | ||
| /// distance.round() | ||
| /// ); | ||
| /// ``` | ||
| /// | ||
| /// [`Haversine`]: super::Haversine | ||
| /// [`Geodesic`]: super::Geodesic | ||
| /// [metric spaces]: super | ||
| fn distance(origin: Point<F>, destination: Point<F>) -> F { | ||
| crate::EuclideanDistance::euclidean_distance(&origin, &destination) | ||
| } | ||
| } | ||
|
|
||
| #[cfg(test)] | ||
| mod tests { | ||
| use super::*; | ||
|
|
||
| type MetricSpace = Euclidean; | ||
|
|
||
| mod distance { | ||
| use super::*; | ||
|
|
||
| #[test] | ||
| fn new_york_to_london() { | ||
| // web mercator | ||
| let new_york_city = Point::new(-8238310.24, 4942194.78); | ||
| // web mercator | ||
| let london = Point::new(-14226.63, 6678077.70); | ||
| let distance: f64 = MetricSpace::distance(new_york_city, london); | ||
|
|
||
| assert_relative_eq!( | ||
| 8_405_286., // meters in web mercator | ||
| distance.round() | ||
| ); | ||
| } | ||
| } | ||
| } | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I know some people have complained about excessively technical language (I disagree), but I'm uneasy about using terminology like "ruler" or "projected coordinates". I think we should refer to this space and link to it as The Euclidean Plane, specifically "the set R2 of the ordered pairs of real numbers, equipped with the dot product", because it's unambiguous. We could also provide examples of what it isn't (I'm not particularly in favour, but I can see why it might be helpful).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I like that euclidean plane link - I'll work that in.
I think that your very technical description will be, on average, more confusing for someone (like me) who just wants "regular old normal measurements like I learned to do in middle school geometry".
My impression is that you are trying to target a more mathematically adroit user with your precise definition, which is a reasonable segment to target, but at the cost of confusing users like me... I'm not sure it's worth it.
Is there plausible confusion here? What other metric space would people think we're talking about?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Phrased a little differently:
I think the most likely mistake people will make is trying to put GPS coordinates into a euclidean method or vice-versa.
So rather than giving a complete dictionary definition of what a thing is I'm optimizing to have documentation that I think will lead to the fewest number of errors based on peoples short attention spans.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I agree, but I also want to avoid using language that's going to be confusing to people who aren't familiar with coordinate systems. Fundamentally, we want people to know what the rules of the system they using are (because we are declining to enforce the rules using the type system)
I want people to know they're in The Euclidean Plane, because that's unambiguous information that they can expand upon if they're unsure, and it defines the rules that are in use w/r/t/ distance etc.
For people who are implementing algorithms using geo, they will want to know they're in R2 because the literature that you have to read to implement them often states this as an assumption.
So I would say I don't think we disagree about who we're targeting (the widest possible range of users).