Crate geoconv

Expand description

geoconv implements support for converting between some basic coordinate systems. This package contains support for Wgs84 Latitude/Longitude/Elevation (Lle) geodetic coordinates, Earth-centered, Earth-fixed (Xyz), and local tangent plane (both East/North/Up (Enu) and Azimuth/Elevation/Range (Aer)) systems.

This is also absolutely not ready to be used for navigational purposes. Please do not use this library in any situation that may cause harm to life or property.

This package is particularly useful if you know your location on Earth, and want to geolocate an object that you can observe, or if you know your location on Earth, and an object’s location on Earth and want to determine your relative positions.

This also includes Haversine-distance using the circumference of the earth for approximate great-circle distance between two Lat/Lon points, but only on the “Earth’s surface”. In some cases (long distances) this is a way better approach for distance. If both points are line-of-sight, you likely care more about using the local tangent plane to work out the Range to the target in 3-space by converting both lat/lons to Earth-North-Up or an Azimuth/Elevation/Range.

§Supported Coordinate Systems

I only implemented what I was interested in (Wgs84), but I threw in another system (Wgs72) since it should be pretty straight-forward to support both. I have no reference data, so some additional testing for that coordinate system would be most welcome.

Coordinate System	State	Note
Wgs84	Tested	You likely want this
Wgs72	Implemented

§Types

Within geoconv, the main types that you’ll be interacting with for location data are listed below, along with a short description.

Name	Cartesian or Angular	Where is `0`, `0`, `0`?	Description
Lle	Angular	Null Island	Latitude, Longitude, and Elevation
Xyz	Cartesian	Earth’s Core	X, Y, Z (sometimes called ECEF, Earth-centered, Earth-fixed)
Aer	Angular	Some point on the local tangent plane	Azimuth, Elevation and Range
Enu	Cartesian	Some point on the local tangent plane	East-North-Up

§Determining the Azimuth, Elevation and Rage between two points

Using geoconv, we can take some Latitude, Longitude and Elevation (Lle) and figure out where another Lle point is in reference to our local tangent plane – for instance, what the bearing (azimuth), elevation (up and down) and range to the “other” point is from where “we” are.

use geoconv::{Lle, Wgs84, Degrees, Meters, Aer};

// Alias for a lat/lon/elevation in the Wgs84 coordinate system,
// used by (among many others), GPS -- this is usually what you
// want when you're processing lat/lon information.
type LleW84 = Lle<Wgs84>;

// "My" point on earth.
let me = LleW84::new(
    Degrees::new(42.352211),
    Degrees::new(-71.051315),
    Meters::new(0.0),
);

// "Your" point on earth.
let you = LleW84::new(
    Degrees::new(42.320239),
    Degrees::new(-70.929482),
    Meters::new(100.0),
);

// Compute in what direction I'd need to look to see you.
let look: Aer<Degrees> = me.aer_to(&you);

§Determine the coordinates of something you can range

Using geoconv, we can take some observation taken from a point, and figure out where that point is. Let’s work through taking a reading in Azimuth, Elevation and Range (Aer) and turning that back into Latitude, Longitude and Elevation (Lle) given our location.

use geoconv::{Lle, Wgs84, Degrees, Meters, Aer};

type LleW84 = Lle<Wgs84>;

// "My" point on earth.
let me = LleW84::new(
    Degrees::new(42.352211),
    Degrees::new(-71.051315),
    Meters::new(0.0),
);

// I see something straight ahead of me, 45 degrees in elevation (up),
// and 30 meters away.
let observation = Aer {
    azimuth: Degrees::new(0.0),
    elevation: Degrees::new(45.0),
    range: Meters::new(30.0),
};

// Assuming I have a perfect reading on where that object is, where
// is that object as a latitude/longitude?
let observed_lle: LleW84 = observation.to_lle(&me);

§Haversine (Great Circle) distance between two points

In addition to operations on the local tangent plane, sometimes the two points being measured are far enough away where the range between two points is not the distance you’d travel between them.

For instance, when traving, from San Francisco to Paris, we need to travel along the curve of the earth, rather than directly through the crust of Earth.

To compute distance beyond line of sight between to latitude and longitude points, we can use the Haversine formula to approximate the distance.

Haversine distance does not easily take into account elevation, so the haversine_distance function does not accept a Lle, rather, a tuple of AngularMeasures, such as Degrees or Radians.

use geoconv::{Degrees, haversine_distance, Meters};

// Latitude, then Longitude (in that order) for the tuples
let lat_lon_a = (Degrees::new(22.55), Degrees::new(43.12));
let lat_lob_b = (Degrees::new(13.45), Degrees::new(100.28));

let result: Meters = haversine_distance(lat_lon_a, lat_lob_b);

Modules§

maidenhead: A Maidenhead Locator is a way of describing a location on earth commonly used by amateur radio operators. These are usually either 4 or 6 bytes long, with increasing precision as the number of bytes increases.

Structs§

Aer: Aer represents an Azimuth, Elevation, and Range measurement.
Degrees: Degrees is an angular measure that ranges from 0 to 360 (sometimes negative)
Enu: Enu is East, North, Up in Meters.
Lle: Lle or Latitude, Longitude, Elevation, is a location somewhere around Earth, in refernce to some CoordinateSystem’s ellipsoid.
Meters: Meters represent the SI unit of measure, Meter
Radians: Radians is an angular measure that ranges from 0 to 2π (𝜏).
Wgs72: Wgs72 (“World Geodetic System 1972”) is a standard published by the United States National Geospatial-Intelligence Agency.
Wgs84: Wgs84 (“World Geodetic System 1984”) is a standard published and maintained by the United States National Geospatial-Intelligence Agency. This is the CoordinateSystem used by most systems “by default”, including GPS.
Xyz: Xyz is the earth-centric Xyz point system.

Traits§

CoordinateSystem: CoordinateSystem is a trait to enable converstion between locations (usually Latitude and Longitude, in the form of Lle objects) to absolute points in space and vice versa.

Functions§

bearing: Compute the bearing (compass heading) from one point to another, provided in Latitude/Longitude points along Earth’s “surface” in either Degrees or Radians.
haversine_distance: Haversine (Great Circle) distance between two points returns the distance between to Latitude/Longitude points along the great circle path along Earth’s “surface”, in either Degrees or Radians.

Type Aliases§

AERDeprecated: Alias for AER. This struct was renamed to better match Rust style, and this alias will be removed in a future release.
ENUDeprecated: Alias for Enu. This struct was renamed to better match Rust style, and this alias will be removed in a future release.
LLEDeprecated: Alias for LLE. This struct was renamed to better match Rust style, and this alias will be removed in a future release.
XYZDeprecated: Alias for XYZ. This struct was renamed to better match Rust style, and this alias will be removed in a future release.

Crate geoconvCopy item path