geographiclib_rs/lib.rs
1//! A subset of [geographiclib](https://geographiclib.sourceforge.io/) implemented in Rust.
2//!
3//! # Examples
4//!
5//! ```rust
6//! // Determine the point 10000 km NE of JFK - the "direct" geodesic calculation.
7//! use geographiclib_rs::{Geodesic, DirectGeodesic};
8//!
9//! let g = Geodesic::wgs84();
10//! let jfk_lat = 40.64;
11//! let jfk_lon = -73.78;
12//! let northeast_azimuth = 45.0;
13//!
14//! let (lat, lon, az) = g.direct(jfk_lat, jfk_lon, northeast_azimuth, 10e6);
15//!
16//! use approx::assert_relative_eq;
17//! assert_relative_eq!(lat, 32.621100463725796);
18//! assert_relative_eq!(lon, 49.052487092959836);
19//! assert_relative_eq!(az, 140.4059858768007);
20//! ```
21//!
22//! ```rust
23//! // Determine the distance between two points - the "inverse" geodesic calculation.
24//! use geographiclib_rs::{Geodesic, InverseGeodesic};
25//!
26//! let g = Geodesic::wgs84();
27//! let p1 = (34.095925, -118.2884237);
28//! let p2 = (59.4323439, 24.7341649);
29//! let s12: f64 = g.inverse(p1.0, p1.1, p2.0, p2.1);
30//!
31//! use approx::assert_relative_eq;
32//! assert_relative_eq!(s12, 9094718.72751138);
33//! ```
34//!
35//! ```rust
36//! // Determine the perimeter and area of a polygon.
37//! use geographiclib_rs::{Geodesic, PolygonArea, Winding};
38//!
39//! let g = Geodesic::wgs84();
40//! let mut pa = PolygonArea::new(&g, Winding::CounterClockwise);
41//! pa.add_point(0.0, 0.0);
42//! pa.add_point(0.0, 1.0);
43//! pa.add_point(1.0, 1.0);
44//! pa.add_point(1.0, 0.0);
45//!
46//! let (perimeter_m, area_m_squared, num_points) = pa.compute(false);
47//!
48//! use approx::assert_relative_eq;
49//! assert_relative_eq!(perimeter_m, 443770.91724830196);
50//! assert_relative_eq!(area_m_squared, 12308778361.469452);
51//! assert_eq!(num_points, 4);
52//! ```
53//!
54//! ```rust
55//! // Determine the distance between rovers Pathfinder and Curiosity on Mars
56//! use geographiclib_rs::{Geodesic, InverseGeodesic};
57//!
58//! let mars = Geodesic::new(3396190.0, 1.0 / 169.8944472);
59//! let pathfinder = (19.26, 326.75);
60//! let curiosity = (-4.765700445, 137.39820983);
61//! let distance_m: f64 = mars.inverse(curiosity.0, curiosity.1, pathfinder.0, pathfinder.1);
62//!
63//! assert_eq!(distance_m.round(), 9639113.0);
64//! ```
65//!
66//! # Features
67//!
68//! 1. `accurate`: Enabled by default. Use the [`accurate`](https://docs.rs/accurate/latest/accurate/) crate to provide high accuracy polygon areas and perimeters in `PolygonArea`. Can be disabled for better performance or when `PolygonArea` is not being used.
69
70// Since this library is a port of an existing (cpp) codebase, there are times we opt
71// to follow the upstream implementation rather than follow rust idioms.
72#![allow(clippy::bool_to_int_with_if)]
73#![allow(clippy::manual_range_contains)]
74#![allow(clippy::excessive_precision)]
75
76mod geodesic;
77pub use geodesic::{DirectGeodesic, Geodesic, InverseGeodesic};
78
79pub mod geodesic_capability;
80pub use geodesic_capability as capability;
81
82mod geodesic_line;
83pub use geodesic_line::GeodesicLine;
84mod geomath;
85mod polygon_area;
86pub use polygon_area::PolygonArea;
87pub use polygon_area::Winding;