The library interface

Jump to

The units

All angles (latitude, longitude, azimuth, arc length) are measured in degrees with latitudes increasing northwards, longitudes increasing eastwards, and azimuths measured clockwise from north. For a point at a pole, the azimuth is defined by keeping the longitude fixed, writing φ = ±(90° − ε), and taking the limit ε → 0+

Geodesic dictionary

The results returned by Geodesic.Direct, Geodesic.Inverse, GeodesicLine.Position, etc., return a dictionary with some of the following 12 fields set:

  • lat1 = φ1, latitude of point 1 (degrees)

  • lon1 = λ1, longitude of point 1 (degrees)

  • azi1 = α1, azimuth of line at point 1 (degrees)

  • lat2 = φ2, latitude of point 2 (degrees)

  • lon2 = λ2, longitude of point 2 (degrees)

  • azi2 = α2, (forward) azimuth of line at point 2 (degrees)

  • s12 = s12, distance from 1 to 2 (meters)

  • a12 = σ12, arc length on auxiliary sphere from 1 to 2 (degrees)

  • m12 = m12, reduced length of geodesic (meters)

  • M12 = M12, geodesic scale at 2 relative to 1 (dimensionless)

  • M21 = M21, geodesic scale at 1 relative to 2 (dimensionless)

  • S12 = S12, area between geodesic and equator (meters2)

outmask and caps

By default, the geodesic routines return the 7 basic quantities: lat1, lon1, azi1, lat2, lon2, azi2, s12, together with the arc length a12. The optional output mask parameter, outmask, can be used to tailor which quantities to calculate. In addition, when a GeodesicLine is constructed it can be provided with the optional capabilities parameter, caps, which specifies what quantities can be returned from the resulting object.

Both outmask and caps are obtained by or’ing together the following values

DISTANCE_IN is a capability provided to the GeodesicLine constructor. It allows the position on the line to specified in terms of distance. (Without this, the position can only be specified in terms of the arc length.) This only makes sense in the caps parameter.

LONG_UNROLL controls the treatment of longitude. If it is not set then the lon1 and lon2 fields are both reduced to the range [−180°, 180°]. If it is set, then lon1 is as given in the function call and (lon2 − lon1) determines how many times and in what sense the geodesic has encircled the ellipsoid. This only makes sense in the outmask parameter.

Note that a12 is always included in the result.

Restrictions on the parameters

  • Latitudes must lie in [−90°, 90°]. Latitudes outside this range are replaced by NaNs.

  • The distance s12 is unrestricted. This allows geodesics to wrap around the ellipsoid. Such geodesics are no longer shortest paths. However they retain the property that they are the straightest curves on the surface.

  • Similarly, the spherical arc length a12 is unrestricted.

  • Longitudes and azimuths are unrestricted; internally these are exactly reduced to the range [−180°, 180°]; but see also the LONG_UNROLL bit.

  • The equatorial radius a and the polar semi-axis b must both be positive and finite (this implies that −∞ < f < 1).

  • The flattening f should satisfy f ∈ [−1/50,1/50] in order to retain full accuracy. This condition holds for most applications in geodesy.

Reasonably accurate results can be obtained for −0.2 ≤ f ≤ 0.2. Here is a table of the approximate maximum error (expressed as a distance) for an ellipsoid with the same equatorial radius as the WGS84 ellipsoid and different values of the flattening.

abs(f)

error

0.003

15 nm

0.01

25 nm

0.02

30 nm

0.05

10 μm

0.1

1.5 mm

0.2

300 mm

Here 1 nm = 1 nanometer = 10−9 m (not 1 nautical mile!)