Trait DistanceStrategy 

pub trait DistanceStrategy<A: Geometry, B: Geometry> {
    type Out: CoordinateScalar;
    type Comparable: DistanceStrategy<A, B, Out = Self::Out>;

    // Required methods
    fn distance(&self, a: &A, b: &B) -> Self::Out;
    fn comparable(&self) -> Self::Comparable;
}

A strategy for computing the distance between two geometries.

Mirrors the per-CS strategy concept declared in boost/geometry/strategies/distance.hpp and refined per coordinate system in strategies/{cartesian,spherical,geographic}/ distance_*.hpp. The Boost concept exposes apply(g1, g2) plus a return_type<G1, G2> metafunction plus a comparable_type<...> sibling; we collapse those three onto one Rust trait via associated types.

Associated items

• Self::Out — the scalar the distance comes back as. Equivalent to Boost’s boost::geometry::strategy::distance::services::return_type<...> (strategies/distance/services.hpp). Typically the wider of A’s and B’s coordinate scalars after promotion.
• Self::Comparable — the “skip the sqrt” form of this strategy. For Pythagoras this is ComparablePythagoras; for strategies where there is nothing to save by deferring a square root (Andoyer, Vincenty), set type Comparable = Self; and the optimiser collapses the indirection. Mirrors comparable_type<...> from the same Boost services header.

Method shape

distance(&self, &A, &B) mirrors apply(g1, g2) on Boost’s strategy structs (e.g. strategies/cartesian/distance_pythagoras.hpp:75-95 for the comparable form, :99-115 for the sqrt-paying form). comparable(&self) mirrors get_comparable(strategy) from strategies/distance/services.hpp.

Required Associated Types

type Out: CoordinateScalar

The output scalar type. Typically the promoted scalar of A and B. Mirrors services::return_type<Strategy, P1, P2>::type from strategies/distance/services.hpp.

type Comparable: DistanceStrategy<A, B, Out = Self::Out>

The “skip the sqrt” form of this strategy.

For Pythagoras → ComparablePythagoras (returns squared distance). For strategies where there is no win from a comparable form (Vincenty, Andoyer), type Comparable = Self; — the optimiser collapses it. Mirrors comparable_type<Strategy>::type from strategies/distance/services.hpp.

The bound DistanceStrategy<A, B, Out = Self::Out> enforces the invariant that comparing two comparable distances gives the same ordering as comparing two real distances — both sides of the comparison must speak the same scalar type.

Required Methods

fn distance(&self, a: &A, b: &B) -> Self::Out

Compute the distance between a and b.

Mirrors apply(g1, g2) on Boost strategy structs (e.g. strategies/cartesian/distance_pythagoras.hpp:99-115).

fn comparable(&self) -> Self::Comparable

Return the comparable-form companion of this strategy.

Mirrors services::get_comparable(strategy) from strategies/distance/services.hpp — most concrete strategies implement it as a no-op constructor of the sibling comparable::* type.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl<A, B, S> DistanceStrategy<B, A> for Reversed<S>

where A: Geometry, B: Geometry, S: DistanceStrategy<A, B>,

type Out = <S as DistanceStrategy<A, B>>::Out

type Comparable = Reversed<<S as DistanceStrategy<A, B>>::Comparable>

impl<P1, P2> DistanceStrategy<P1, P2> for Andoyer

where P1: Point<Scalar = f64>, P2: Point<Scalar = f64>, P1::Cs: HasAngularUnits, P2::Cs: HasAngularUnits, <P1::Cs as CoordinateSystem>::Family: SameAs<GeographicFamily>, <P2::Cs as CoordinateSystem>::Family: SameAs<GeographicFamily>,

Available on crate feature std only.

Andoyer on f64 geographic points.

Mirrors formula::andoyer_inverse<CT, true, false>::apply at formulas/andoyer_inverse.hpp:58-123 — the distance-only branch (EnableDistance = true, all other flags false). Computes:

cos_d  = sin(lat1)·sin(lat2) + cos(lat1)·cos(lat2)·cos(Δlon)
d      = acos(cos_d)
K      = (sin(lat1) − sin(lat2))²
L      = (sin(lat1) + sin(lat2))²
H      = (d + 3·sin_d) / (1 − cos_d)
G      = (d − 3·sin_d) / (1 + cos_d)
dd     = −(f/4) · (H·K + G·L)
result = a · (d + dd)

with the degenerate 1 ± cos_d == 0 branches falling back to H = 0 / G = 0 as in formulas/andoyer_inverse.hpp:111-117.

Diagnostics on mis-paired CS

A caller who pairs a Cartesian or Spherical point with Andoyer hits the <P::Cs as CoordinateSystem>::Family: SameAs<GeographicFamily> bound below and gets the redirect plate on geometry_tag::SameAs pointing them at WithCs<_, Geographic<…>> or at the Cartesian / Spherical strategies. See T31 and proposal §3.7.

type Out = f64

type Comparable = Andoyer

impl<P1, P2> DistanceStrategy<P1, P2> for ComparableHaversine

where P1: Point<Scalar = f64>, P2: Point<Scalar = f64>, P1::Cs: HasAngularUnits, P2::Cs: HasAngularUnits, <P1::Cs as CoordinateSystem>::Family: SameAs<SphericalFamily>, <P2::Cs as CoordinateSystem>::Family: SameAs<SphericalFamily>,

Available on crate feature std only.

type Out = f64

type Comparable = ComparableHaversine

impl<P1, P2> DistanceStrategy<P1, P2> for ComparablePythagoras

where P1: Point, P2: Point<Scalar = P1::Scalar>, <P1::Cs as CoordinateSystem>::Family: SameAs<CartesianFamily>, <P2::Cs as CoordinateSystem>::Family: SameAs<CartesianFamily>,

type Out = <P1 as Point>::Scalar

type Comparable = ComparablePythagoras

impl<P1, P2> DistanceStrategy<P1, P2> for Haversine

where P1: Point<Scalar = f64>, P2: Point<Scalar = f64>, P1::Cs: HasAngularUnits, P2::Cs: HasAngularUnits, <P1::Cs as CoordinateSystem>::Family: SameAs<SphericalFamily>, <P2::Cs as CoordinateSystem>::Family: SameAs<SphericalFamily>,

Available on crate feature std only.

Haversine on f64 spherical points.

Mirrors the apply(p1, p2) member of boost::geometry::strategy::distance::haversine at strategies/spherical/distance_haversine.hpp:188-199:

d = 2 · R · asin(sqrt(h))
  where h = sin²(Δlat/2) + cos(lat1)·cos(lat2)·sin²(Δlon/2)

Diagnostics on mis-paired CS

A caller who pairs a Cartesian or Geographic point with Haversine hits the <P::Cs as CoordinateSystem>::Family: SameAs<SphericalFamily> bound below and gets the redirect plate on geometry_tag::SameAs pointing them at WithCs<_, Spherical<…>> or at the geographic strategies (Andoyer, Vincenty). See T31 and proposal §3.7.

type Out = f64

type Comparable = ComparableHaversine

impl<P1, P2> DistanceStrategy<P1, P2> for KarneyInverse

where P1: Point<Scalar = f64>, P2: Point<Scalar = f64>, P1::Cs: HasAngularUnits, P2::Cs: HasAngularUnits, <P1::Cs as CoordinateSystem>::Family: SameAs<GeographicFamily>, <P2::Cs as CoordinateSystem>::Family: SameAs<GeographicFamily>,

Available on crate feature std only.

type Out = f64

type Comparable = KarneyInverse

impl<P1, P2> DistanceStrategy<P1, P2> for Pythagoras

where P1: Point, P2: Point<Scalar = P1::Scalar>, <P1::Cs as CoordinateSystem>::Family: SameAs<CartesianFamily>, <P2::Cs as CoordinateSystem>::Family: SameAs<CartesianFamily>,

type Out = <P1 as Point>::Scalar

type Comparable = ComparablePythagoras

impl<P1, P2> DistanceStrategy<P1, P2> for Rhumb

where P1: Point<Scalar = f64>, P2: Point<Scalar = f64, Cs = P1::Cs>, P1::Cs: HasAngularUnits + CoordinateSystem, <P1::Cs as CoordinateSystem>::Family: RhumbFamily,

type Out = f64

type Comparable = Rhumb

impl<P1, P2> DistanceStrategy<P1, P2> for Thomas

where P1: Point<Scalar = f64>, P2: Point<Scalar = f64>, P1::Cs: HasAngularUnits, P2::Cs: HasAngularUnits, <P1::Cs as CoordinateSystem>::Family: SameAs<GeographicFamily>, <P2::Cs as CoordinateSystem>::Family: SameAs<GeographicFamily>,

Available on crate feature std only.

Thomas on f64 geographic points.

Mirrors formula::thomas_inverse<CT, true, false>::apply at formulas/thomas_inverse.hpp:59-215 — the distance-only branch (EnableDistance = true, all other flags false). The full derivation lives in Paul D. Thomas, Mathematical Models for Navigation Systems, 1965, and Spheroidal Geodesics, Reference Systems, and Local Geometry, 1970.

Diagnostics on mis-paired CS

A caller who pairs a Cartesian or Spherical point with Thomas hits the <P::Cs as CoordinateSystem>::Family: SameAs<GeographicFamily> bound below and gets the redirect plate on geometry_tag::SameAs pointing them at WithCs<_, Geographic<…>> or at the Cartesian / Spherical strategies. See T31 and proposal §3.7.

type Out = f64

type Comparable = Thomas

impl<P1, P2> DistanceStrategy<P1, P2> for Vincenty

where P1: Point<Scalar = f64>, P2: Point<Scalar = f64>, P1::Cs: HasAngularUnits, P2::Cs: HasAngularUnits, <P1::Cs as CoordinateSystem>::Family: SameAs<GeographicFamily>, <P2::Cs as CoordinateSystem>::Family: SameAs<GeographicFamily>,

Available on crate feature std only.

Vincenty on f64 geographic points.

Mirrors formula::vincenty_inverse<CT, true, false>::apply at formulas/vincenty_inverse.hpp:67-188 — the distance-only branch. Iterates λ on the auxiliary sphere until either successive λ differ by less than self.tolerance, |λ| exits the (−π, π) interval, or self.max_iterations is reached, then evaluates the arc length on the ellipsoid via the standard A / B / Δσ series.

Diagnostics on mis-paired CS

A caller who pairs a Cartesian or Spherical point with Vincenty hits the <P::Cs as CoordinateSystem>::Family: SameAs<GeographicFamily> bound below and gets the redirect plate on geometry_tag::SameAs pointing them at WithCs<_, Geographic<…>> or at the Cartesian / Spherical strategies. See T31 and proposal §3.7.

type Out = f64

type Comparable = Vincenty

impl<P, S, PP> DistanceStrategy<P, S> for PointToSegment<PP>

where P: PointMut + Default, S: Segment<Point = P>, <P::Cs as CoordinateSystem>::Family: SameAs<CartesianFamily>, PP: DistanceStrategy<P, P, Out = P::Scalar>, PP::Comparable: DistanceStrategy<P, P, Out = P::Scalar>,

type Out = <P as Point>::Scalar

type Comparable = PointToSegment<<PP as DistanceStrategy<P, P>>::Comparable>

impl<P> DistanceStrategy<P, Segment<P>> for CrossTrack

where P: Point<Scalar = f64> + PointMut + Default + Copy, P::Cs: HasAngularUnits, <P::Cs as CoordinateSystem>::Family: SameAs<SphericalFamily>,

type Out = f64

type Comparable = CrossTrack

impl<P> DistanceStrategy<Segment<P>, P> for CrossTrack

where P: Point<Scalar = f64> + PointMut + Default + Copy, P::Cs: HasAngularUnits, <P::Cs as CoordinateSystem>::Family: SameAs<SphericalFamily>,

type Out = f64

type Comparable = CrossTrack