1The library interface 2===================== 3 4Jump to 5 6* :ref:`units` 7* :ref:`dict` 8* :ref:`outmask` 9* :ref:`restrictions` 10 11.. _units: 12 13The units 14--------- 15 16All angles (latitude, longitude, azimuth, arc length) are measured in 17degrees with latitudes increasing northwards, longitudes increasing 18eastwards, and azimuths measured clockwise from north. For a point at a 19pole, the azimuth is defined by keeping the longitude fixed, writing φ = 20±(90° − ε), and taking the limit ε → 0+ 21 22.. _dict: 23 24Geodesic dictionary 25------------------- 26 27The results returned by 28:meth:`Geodesic.Direct <geographiclib.geodesic.Geodesic.Direct>`, 29:meth:`Geodesic.Inverse <geographiclib.geodesic.Geodesic.Inverse>`, 30:meth:`GeodesicLine.Position <geographiclib.geodesicline.GeodesicLine.Position>`, 31etc., return a dictionary with some of the following 12 fields set: 32 33* *lat1* = φ\ :sub:`1`, latitude of point 1 (degrees) 34* *lon1* = λ\ :sub:`1`, longitude of point 1 (degrees) 35* *azi1* = α\ :sub:`1`, azimuth of line at point 1 (degrees) 36* *lat2* = φ\ :sub:`2`, latitude of point 2 (degrees) 37* *lon2* = λ\ :sub:`2`, longitude of point 2 (degrees) 38* *azi2* = α\ :sub:`2`, (forward) azimuth of line at point 2 (degrees) 39* *s12* = *s*\ :sub:`12`, distance from 1 to 2 (meters) 40* *a12* = σ\ :sub:`12`, arc length on auxiliary sphere from 1 to 2 (degrees) 41* *m12* = *m*\ :sub:`12`, reduced length of geodesic (meters) 42* *M12* = *M*\ :sub:`12`, geodesic scale at 2 relative to 1 (dimensionless) 43* *M21* = *M*\ :sub:`21`, geodesic scale at 1 relative to 2 (dimensionless) 44* *S12* = *S*\ :sub:`12`, area between geodesic and equator (meters\ :sup:`2`) 45 46.. _outmask: 47 48*outmask* and *caps* 49-------------------- 50 51By default, the geodesic routines return the 7 basic quantities: *lat1*, 52*lon1*, *azi1*, *lat2*, *lon2*, *azi2*, *s12*, together with the arc 53length *a12*. The optional output mask parameter, *outmask*, can be 54used to tailor which quantities to calculate. In addition, when a 55:class:`~geographiclib.geodesicline.GeodesicLine` is constructed it can 56be provided with the optional capabilities parameter, *caps*, which 57specifies what quantities can be returned from the resulting object. 58 59Both *outmask* and *caps* are obtained by or'ing together the following 60values 61 62* :data:`~geographiclib.geodesic.Geodesic.EMPTY`, no capabilities, no output 63* :data:`~geographiclib.geodesic.Geodesic.LATITUDE`, compute latitude, *lat2* 64* :data:`~geographiclib.geodesic.Geodesic.LONGITUDE`, 65 compute longitude, *lon2* 66* :data:`~geographiclib.geodesic.Geodesic.AZIMUTH`, 67 compute azimuths, *azi1* and *azi2* 68* :data:`~geographiclib.geodesic.Geodesic.DISTANCE`, compute distance, *s12* 69* :data:`~geographiclib.geodesic.Geodesic.STANDARD`, all of the above 70* :data:`~geographiclib.geodesic.Geodesic.DISTANCE_IN`, 71 allow *s12* to be used as input in the direct problem 72* :data:`~geographiclib.geodesic.Geodesic.REDUCEDLENGTH`, 73 compute reduced length, *m12* 74* :data:`~geographiclib.geodesic.Geodesic.GEODESICSCALE`, 75 compute geodesic scales, *M12* and *M21* 76* :data:`~geographiclib.geodesic.Geodesic.AREA`, compute area, *S12* 77* :data:`~geographiclib.geodesic.Geodesic.ALL`, all of the above; 78* :data:`~geographiclib.geodesic.Geodesic.LONG_UNROLL`, unroll longitudes 79 80DISTANCE_IN is a capability provided to the GeodesicLine constructor. It 81allows the position on the line to specified in terms of 82distance. (Without this, the position can only be specified in terms of 83the arc length.) This only makes sense in the *caps* parameter. 84 85LONG_UNROLL controls the treatment of longitude. If it is not set then 86the *lon1* and *lon2* fields are both reduced to the range [−180°, 87180°). If it is set, then *lon1* is as given in the function call and 88(*lon2* − *lon1*) determines how many times and in what sense the 89geodesic has encircled the ellipsoid. This only makes sense in the 90*outmask* parameter. 91 92Note that *a12* is always included in the result. 93 94.. _restrictions: 95 96Restrictions on the parameters 97------------------------------ 98 99* Latitudes must lie in [−90°, 90°]. Latitudes outside this range are 100 replaced by NaNs. 101* The distance *s12* is unrestricted. This allows geodesics to wrap 102 around the ellipsoid. Such geodesics are no longer shortest 103 paths. However they retain the property that they are the straightest 104 curves on the surface. 105* Similarly, the spherical arc length *a12* is unrestricted. 106* Longitudes and azimuths are unrestricted; internally these are 107 exactly reduced to the range [−180°, 180°); but see also the 108 LONG_UNROLL bit. 109* The equatorial radius *a* and the polar semi-axis *b* must both be 110 positive and finite (this implies that −∞ < *f* < 1). 111* The flattening *f* should satisfy *f* ∈ [−1/50,1/50] in order to retain 112 full accuracy. This condition holds for most applications in geodesy. 113 114Reasonably accurate results can be obtained for −0.2 ≤ *f* ≤ 0.2. Here 115is a table of the approximate maximum error (expressed as a distance) 116for an ellipsoid with the same equatorial radius as the WGS84 ellipsoid 117and different values of the flattening. 118 119======== ======= 120abs(*f*) error 121-------- ------- 1220.003 15 nm 1230.01 25 nm 1240.02 30 nm 1250.05 10 μm 1260.1 1.5 mm 1270.2 300 mm 128======== ======= 129 130Here 1 nm = 1 nanometer = 10\ :sup:`−9` m (*not* 1 nautical mile!) 131