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