Struct HaversineMeasure 

pub struct HaversineMeasure { /* private fields */ }

Use the Haversine constant (an instance of HaversineMeasure) rather than building your own customized HaversineMeasure for standard spherical Earth measurements.

HaversineMeasure measures distance on a sphere using the haversine formula. Distances are considered great circle lengths and given in units that match those of the radius passed to HaversineMeasure::new (typically meters).

You may specify a custom radius for the Earth (or other sphere), but for normal spherical measurements of the Earth, you should use the simpler Haversine which uses the standard earth radius of 6371.0088 km (6_371_008.7714 m), based on the recommendation of the IUGG.

Examples

use geo::{wkt, HaversineMeasure, Haversine, Distance};

let start = wkt!(POINT(23.319941 42.698334)); // Sofia: Longitude, Latitude
let finish = wkt!(POINT(24.742168 42.136097)); // Plovdiv: Longitude, Latitude

// Typically, you can use `Haversine` for measuring on the Earth's surface.
assert_relative_eq!(
    132433.09929460194,
    Haversine.distance(start, finish)
);

// The default `Haversine` const has a radius equal to the mean radius of the GRS80 ellipsoid (6371.0088 km).
assert_relative_eq!(
    Haversine.radius(),
    HaversineMeasure::GRS80_MEAN_RADIUS.radius()
);

// You may choose to use one of the other well known estimations of the Earth's radius,
// which may result in *slightly* different results.
assert_relative_eq!(
    132433.06564071847,
    HaversineMeasure::GRS80_EQUAL_AREA.distance(start, finish)
);

// Or you can specify whatever radius you want to get some "out of this world" results.
let mars_sphere = HaversineMeasure::new(3_389_500.0); // 👽 Mars radius in meters
assert_relative_eq!(
    70456.97222377927,
    mars_sphere.distance(start, finish)
);

References

Moritz, H. (2000). Geodetic Reference System 1980. Journal of Geodesy, 74(1), 128–133. doi:10.1007/s001900050278 “Derived Geometric Constants: R1: mean radius” (p131)

• https://link.springer.com/article/10.1007%2Fs001900050278
• https://sci-hub.se/https://doi.org/10.1007/s001900050278

Implementations

impl HaversineMeasure

pub const GRS80_MEAN_RADIUS: Self

A sphere with radius equal to the mean radius of the GRS80 ellipsoid — R₁, copied from Moritz (2000).

Moritz, H. (2000). Geodetic Reference System 1980. Journal of Geodesy, 74(1), 128–133. doi:10.1007/s001900050278 “Derived Geometric Constants: R₁: mean radius” (p131)

• https://link.springer.com/article/10.1007%2Fs001900050278
• https://sci-hub.se/https://doi.org/10.1007/s001900050278

pub const GRS80_EQUAL_AREA: Self

A sphere with the same surface area as the GRS80 ellipsoid, having radius R₂, copied from Moritz (2000).

Moritz, H. (2000). Geodetic Reference System 1980. Journal of Geodesy, 74(1), 128–133. doi:10.1007/s001900050278 “Derived Geometric Constants: R₂: radius of sphere of same surface” (p131)

• https://link.springer.com/article/10.1007%2Fs001900050278
• https://sci-hub.se/https://doi.org/10.1007/s001900050278

pub const GRS80_EQUAL_VOLUME: Self

A sphere with the same volume as the GRS80 ellipsoid, having radius R₃, copied from Moritz (2000).

Moritz, H. (2000). Geodetic Reference System 1980. Journal of Geodesy, 74(1), 128–133. doi:10.1007/s001900050278 “Derived Geometric Constants: R₃: radius of sphere of same volume” (p131)

• https://link.springer.com/article/10.1007%2Fs001900050278
• https://sci-hub.se/https://doi.org/10.1007/s001900050278

pub const fn new(radius: f64) -> Self

Parameters

• radius: The radius of the sphere, typically in meters.

pub const fn radius(&self) -> f64

Trait Implementations

impl<F: CoordFloat + FromPrimitive> Bearing<F> for HaversineMeasure

fn bearing(&self, origin: Point<F>, destination: Point<F>) -> F

Returns the bearing from origin to destination in degrees along a great circle.

Units

• origin, destination: Points where x/y are lon/lat degree coordinates
• returns: degrees, where: North: 0°, East: 90°, South: 180°, West: 270°

Examples

use geo::{Haversine, Bearing};
use geo::Point;

let origin = Point::new(9.0, 10.0);
let destination = Point::new(9.5, 10.1);
let bearing = Haversine.bearing(origin, destination);
// A little north of east
assert_relative_eq!(bearing, 78.47, epsilon = 1.0e-2);

References

Bullock, R.: Great Circle Distances and Bearings Between Two Locations, 2007. (https://dtcenter.org/met/users/docs/write_ups/gc_simple.pdf)

impl Default for HaversineMeasure

fn default() -> Self

Returns the “default value” for a type.

impl<F: CoordFloat + FromPrimitive> Destination<F> for HaversineMeasure

fn destination(&self, origin: Point<F>, bearing: F, meters: F) -> Point<F>

Returns a new point having travelled the distance along a [great circle] from the origin point with the given bearing.

Units

• origin: Point where x/y are lon/lat degree coordinates
• bearing: degrees, where: North: 0°, East: 90°, South: 180°, West: 270°
• distance: meters
• returns: Point where x/y are lon/lat degree coordinates

Examples

use geo::{Haversine, Destination};
use geo::Point;

let origin = Point::new(9.177789688110352, 48.776781529534965);
let destination = Haversine.destination(origin, 45., 10000.);
assert_relative_eq!(Point::new(9.274409949623532, 48.84033274015048), destination);

impl<F: CoordFloat + FromPrimitive> Distance<F, Point<F>, Point<F>> for HaversineMeasure

fn distance(&self, origin: Point<F>, destination: Point<F>) -> F

Determine the distance between two points using the haversine formula.

Units

• origin, destination: Points where x/y are lon/lat degree coordinates
• returns: meters

Examples

use geo::{Haversine, Distance};
use geo::Point;

let new_york_city = Point::new(-74.006f64, 40.7128f64);
let london = Point::new(-0.1278f64, 51.5074f64);

let distance = Haversine.distance(new_york_city, london);

assert_relative_eq!(
    5_570_230., // meters
    distance.round()
);

impl<F: CoordFloat + FromPrimitive> InterpolatePoint<F> for HaversineMeasure

Interpolate Point(s) along a great circle.

fn point_at_distance_between( &self, start: Point<F>, end: Point<F>, meters_from_start: F, ) -> Point<F>

Returns a new Point along a great circle between two existing points.

Examples

use geo::{Haversine, InterpolatePoint};
use geo::Point;

let p1 = Point::new(10.0, 20.0);
let p2 = Point::new(125.0, 25.0);

let closer_to_p1 = Haversine.point_at_distance_between(p1, p2, 100_000.0);
assert_relative_eq!(closer_to_p1, Point::new(10.81, 20.49), epsilon = 1.0e-2);

let closer_to_p2 = Haversine.point_at_distance_between(p1, p2, 10_000_000.0);
assert_relative_eq!(closer_to_p2, Point::new(112.33, 30.57), epsilon = 1.0e-2);

fn point_at_ratio_between( &self, start: Point<F>, end: Point<F>, ratio_from_start: F, ) -> Point<F>

Returns a new Point along a great circle between two existing points.

Examples

use geo::{Haversine, InterpolatePoint};
use geo::Point;

let p1 = Point::new(10.0, 20.0);
let p2 = Point::new(125.0, 25.0);

let closer_to_p1 = Haversine.point_at_ratio_between(p1, p2, 0.1);
assert_relative_eq!(closer_to_p1, Point::new(19.52, 25.27), epsilon = 1.0e-2);

let closer_to_p2 = Haversine.point_at_ratio_between(p1, p2, 0.9);
assert_relative_eq!(closer_to_p2, Point::new(114.72, 29.65), epsilon = 1.0e-2);

let midpoint = Haversine.point_at_ratio_between(p1, p2, 0.5);
assert_relative_eq!(midpoint, Point::new(65.87, 37.62), epsilon = 1.0e-2);

fn points_along_line( &self, start: Point<F>, end: Point<F>, max_distance: F, include_ends: bool, ) -> impl Iterator<Item = Point<F>>

Interpolates Points along a great circle between start and end.

As many points as necessary will be added such that the [haversine 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?