Tutorial: The library interface

Jump to

• The units
• The results
• The outmask and caps parameters
• Restrictions on the parameters

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+.

The results

The results returned by Geodesic.Direct, Geodesic.Inverse, GeodesicLine.Position, etc., return an object with (some) of the following 12 fields set:

• lat1 = φ₁, latitude of point 1 (degrees)
• lon1 = λ₁, longitude of point 1 (degrees)
• azi1 = α₁, azimuth of line at point 1 (degrees)
• lat2 = φ₂, latitude of point 2 (degrees)
• lon2 = λ₂, longitude of point 2 (degrees)
• azi2 = α₂, (forward) azimuth of line at point 2 (degrees)
• s12 = s₁₂, distance from 1 to 2 (meters)
• a12 = σ₁₂, arc length on auxiliary sphere from 1 to 2 (degrees)
• m12 = m₁₂, reduced length of geodesic (meters)
• M12 = M₁₂, geodesic scale at 2 relative to 1 (dimensionless)
• M21 = M₂₁, geodesic scale at 1 relative to 2 (dimensionless)
• S12 = S₁₂, area between geodesic and equator (meters²)

The input parameters together with a12 are always included in the object. Azimuths are reduced to the range [−180°, 180°]. See General information on geodesics for the definitions of these quantities.

The outmask and caps parameters

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

• Geodesic.NONE, no capabilities, no output;
• Geodesic.ARC, compute arc length, a12; this is always implicitly set;
• Geodesic.LATITUDE, compute latitude, lat2;
• Geodesic.LONGITUDE, compute longitude, lon2;
• Geodesic.AZIMUTH, compute azimuths, azi1 and azi2;
• Geodesic.DISTANCE, compute distance, s12;
• Geodesic.STANDARD, all of the above;
• Geodesic.DISTANCE_IN, allow s12 to be used as input in the direct problem;
• Geodesic.REDUCEDLENGTH, compute reduced length, m12;
• Geodesic.GEODESICSCALE, compute geodesic scales, M12 and M21;
• Geodesic.AREA, compute area, S12;
• Geodesic.ALL, all of the above;
• Geodesic.LONG_UNROLL, unroll longitudes.

Geodesic.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.

Geodesic.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.

Here 1 nm = 1 nanometer = 10⁻⁹ m (not 1 nautical mile!)