Crate unit_sphere

unit-sphere

A library for performing geometric calculations on the surface of a sphere.

The library uses a combination of spherical trigonometry and vector geometry to perform great-circle navigation on the surface of a unit sphere, see Figure 1.

Figure 1 A Great Circle Path

A great circle is the shortest path between positions on the surface of a sphere. It is the spherical equivalent of a straight line in planar geometry.

Spherical trigonometry

A great circle path between positions may be found using spherical trigonometry.

The course (initial azimuth) of a great circle can be calculated from the latitudes and longitudes of the start and end points. While great circle distance can also be calculated from the latitudes and longitudes of the start and end points using the haversine formula. The resulting distance in Radians can be converted to the required units by multiplying the distance by the Earth radius measured in the required units.

Vector geometry

Points on the surface of a sphere and great circle poles may be represented by 3D vectors. Many calculations are simpler using vectors than spherical trigonometry.

For example, the across track distance of a point from a great circle can be calculated from the dot product of the point and the great circle pole vectors. While intersection points of great circles can simply be calculated from the cross product of their pole vectors.

Design

The great_circle module performs spherical trigonometric calculations and the vector module performs vector geometry calculations.

The library is declared no_std so it can be used in embedded applications.

Example

The following example calculates the intersection between two Great Circle Arcs it is taken from Charles Karney’s original solution to Intersection between two geodesic lines.

use unit_sphere::{Arc, Degrees, LatLong, calculate_intersection_point};
use angle_sc::is_within_tolerance;

let istanbul = LatLong::new(Degrees(42.0), Degrees(29.0));
let washington = LatLong::new(Degrees(39.0), Degrees(-77.0));
let reyjavik = LatLong::new(Degrees(64.0), Degrees(-22.0));
let accra = LatLong::new(Degrees(6.0), Degrees(0.0));

let arc1 = Arc::try_from((&istanbul, &washington)).unwrap();
let arc2 = Arc::try_from((&reyjavik, &accra)).unwrap();

let intersection_point = calculate_intersection_point(&arc1, &arc2).unwrap();
let lat_long = LatLong::from(&intersection_point);
// Geodesic intersection latitude is 54.7170296089477
assert!(is_within_tolerance(54.72, lat_long.lat().0, 0.05));
// Geodesic intersection longitude is -14.56385574430775
assert!(is_within_tolerance(-14.56, lat_long.lon().0, 0.02));

Modules

• great_circle
  The great_circle module contains functions for calculating the course and distance between points along great circles on a unit sphere.
• vector
  The vector module contains functions for performing great circle calculations using Vector3ds to represent points and great circle poles on a unit sphere.

Structs

• Angle
  An angle represented by it’s sine and cosine as UnitNegRanges.
• Arc
  An Arc of a Great Circle on a unit sphere.
• Degrees
  The Degrees newtype an f64.
• LatLong
  A position as a latitude and longitude pair of Degrees.
• Radians
  The Radians newtype an f64.

Traits

• Validate
  The Validate trait.

Functions

• calculate_azimuth_and_distance
  Calculate the azimuth and distance along the great circle of point b from point a.
• calculate_intersection_distances
  Calculate the great-circle distances along a pair of Arcs to their closest intersection point or their coincident arc distances if the Arcs are on coincident Great Circles.
• calculate_intersection_point
  Calculate whether a pair of Arcs intersect and (if so) where.
• haversine_distance
  Calculate the distance along the great circle of point b from point a, see: Haversine formula. This function is less accurate than calculate_azimuth_and_distance.
• is_valid_latitude
  Test whether a latitude in degrees is a valid latitude. I.e. whether it lies in the range: -90.0 <= degrees <= 90.0
• is_valid_longitude
  Test whether a longitude in degrees is a valid longitude. I.e. whether it lies in the range: -180.0 <= degrees <= 180.0
• latitude
  Calculate the latitude of a Point.
• longitude
  Calculate the longitude of a Point.

Type Aliases

• Vector3d
  A Vector3d is a nalgebra Vector3<f64>.