1GEODSOLVE(1)                GeographicLib Utilities               GEODSOLVE(1)
2
3
4

NAME

6       GeodSolve -- perform geodesic calculations
7

SYNOPSIS

9       GeodSolve [ -i | -L lat1 lon1 azi1 | -D lat1 lon1 azi1 s13 | -I lat1
10       lon1 lat3 lon3 ] [ -a ] [ -e a f ] [ -u ] [ -F ] [ -d | -: ] [ -w ] [
11       -b ] [ -f ] [ -p prec ] [ -E ] [ --comment-delimiter commentdelim ] [
12       --version | -h | --help ] [ --input-file infile | --input-string
13       instring ] [ --line-separator linesep ] [ --output-file outfile ]
14

DESCRIPTION

16       The shortest path between two points on the ellipsoid at (lat1, lon1)
17       and (lat2, lon2) is called the geodesic.  Its length is s12 and the
18       geodesic from point 1 to point 2 has forward azimuths azi1 and azi2 at
19       the two end points.
20
21       GeodSolve operates in one of three modes:
22
23       1.  By default, GeodSolve accepts lines on the standard input
24           containing lat1 lon1 azi1 s12 and prints lat2 lon2 azi2 on standard
25           output.  This is the direct geodesic calculation.
26
27       2.  With the -i command line argument, GeodSolve performs the inverse
28           geodesic calculation.  It reads lines containing lat1 lon1 lat2
29           lon2 and prints the corresponding values of azi1 azi2 s12.
30
31       3.  Command line arguments -L lat1 lon1 azi1 specify a geodesic line.
32           GeodSolve then accepts a sequence of s12 values (one per line) on
33           standard input and prints lat2 lon2 azi2 for each.  This generates
34           a sequence of points on a single geodesic.  Command line arguments
35           -D and -I work similarly with the geodesic line defined in terms of
36           a direct or inverse geodesic calculation, respectively.
37

OPTIONS

39       -i  perform an inverse geodesic calculation (see 2 above).
40
41       -L lat1 lon1 azi1
42           line mode (see 3 above); generate a sequence of points along the
43           geodesic specified by lat1 lon1 azi1.  The -w flag can be used to
44           swap the default order of the 2 geographic coordinates, provided
45           that it appears before -L.  (-l is an alternative, deprecated,
46           spelling of this flag.)
47
48       -D lat1 lon1 azi1 s13
49           line mode (see 3 above); generate a sequence of points along the
50           geodesic specified by lat1 lon1 azi1 s13.  The -w flag can be used
51           to swap the default order of the 2 geographic coordinates, provided
52           that it appears before -D.  Similarly, the -a flag can be used to
53           change the interpretation of s13 to a13, provided that it appears
54           before -D.
55
56       -I lat1 lon1 lat3 lon3
57           line mode (see 3 above); generate a sequence of points along the
58           geodesic specified by lat1 lon1 lat3 lon3.  The -w flag can be used
59           to swap the default order of the 2 geographic coordinates, provided
60           that it appears before -I.
61
62       -a  toggle the arc mode flag (it starts off); if this flag is on, then
63           on input and output s12 is replaced by a12 the arc length (in
64           degrees) on the auxiliary sphere.  See "AUXILIARY SPHERE".
65
66       -e a f
67           specify the ellipsoid via the equatorial radius, a and the
68           flattening, f.  Setting f = 0 results in a sphere.  Specify f < 0
69           for a prolate ellipsoid.  A simple fraction, e.g., 1/297, is
70           allowed for f.  By default, the WGS84 ellipsoid is used, a =
71           6378137 m, f = 1/298.257223563.
72
73       -u  unroll the longitude.  Normally, on output longitudes are reduced
74           to lie in [-180deg,180deg).  However with this option, the returned
75           longitude lon2 is "unrolled" so that lon2 - lon1 indicates how
76           often and in what sense the geodesic has encircled the earth.  Use
77           the -f option, to get both longitudes printed.
78
79       -F  fractional mode.  This only has any effect with the -D and -I
80           options (and is otherwise ignored).  The values read on standard
81           input are interpreted as fractional distances to point 3, i.e., as
82           s12/s13 instead of s12.  If arc mode is in effect, then the values
83           denote fractional arc length, i.e., a12/a13.  The fractional
84           distances can be entered as a simple fraction, e.g., 3/4.
85
86       -d  output angles as degrees, minutes, seconds instead of decimal
87           degrees.
88
89       -:  like -d, except use : as a separator instead of the d, ', and "
90           delimiters.
91
92       -w  toggle the longitude first flag (it starts off); if the flag is on,
93           then on input and output, longitude precedes latitude (except that,
94           on input, this can be overridden by a hemisphere designator, N, S,
95           E, W).
96
97       -b  report the back azimuth at point 2 instead of the forward azimuth.
98
99       -f  full output; each line of output consists of 12 quantities: lat1
100           lon1 azi1 lat2 lon2 azi2 s12 a12 m12 M12 M21 S12.  a12 is described
101           in "AUXILIARY SPHERE".  The four quantities m12, M12, M21, and S12
102           are described in "ADDITIONAL QUANTITIES".
103
104       -p prec
105           set the output precision to prec (default 3); prec is the precision
106           relative to 1 m.  See "PRECISION".
107
108       -E  use "exact" algorithms (based on elliptic integrals) for the
109           geodesic calculations.  These are more accurate than the (default)
110           series expansions for |f| > 0.02.
111
112       --comment-delimiter commentdelim
113           set the comment delimiter to commentdelim (e.g., "#" or "//").  If
114           set, the input lines will be scanned for this delimiter and, if
115           found, the delimiter and the rest of the line will be removed prior
116           to processing and subsequently appended to the output line
117           (separated by a space).
118
119       --version
120           print version and exit.
121
122       -h  print usage and exit.
123
124       --help
125           print full documentation and exit.
126
127       --input-file infile
128           read input from the file infile instead of from standard input; a
129           file name of "-" stands for standard input.
130
131       --input-string instring
132           read input from the string instring instead of from standard input.
133           All occurrences of the line separator character (default is a
134           semicolon) in instring are converted to newlines before the reading
135           begins.
136
137       --line-separator linesep
138           set the line separator character to linesep.  By default this is a
139           semicolon.
140
141       --output-file outfile
142           write output to the file outfile instead of to standard output; a
143           file name of "-" stands for standard output.
144

INPUT

146       GeodSolve measures all angles in degrees and all lengths (s12) in
147       meters, and all areas (S12) in meters^2.  On input angles (latitude,
148       longitude, azimuth, arc length) can be as decimal degrees or degrees,
149       minutes, seconds.  For example, "40d30", "40d30'", "40:30", "40.5d",
150       and 40.5 are all equivalent.  By default, latitude precedes longitude
151       for each point (the -w flag switches this convention); however on input
152       either may be given first by appending (or prepending) N or S to the
153       latitude and E or W to the longitude.  Azimuths are measured clockwise
154       from north; however this may be overridden with E or W.
155
156       For details on the allowed formats for angles, see the "GEOGRAPHIC
157       COORDINATES" section of GeoConvert(1).
158

AUXILIARY SPHERE

160       Geodesics on the ellipsoid can be transferred to the auxiliary sphere
161       on which the distance is measured in terms of the arc length a12
162       (measured in degrees) instead of s12.  In terms of a12, 180 degrees is
163       the distance from one equator crossing to the next or from the minimum
164       latitude to the maximum latitude.  Geodesics with a12 > 180 degrees do
165       not correspond to shortest paths.  With the -a flag, s12 (on both input
166       and output) is replaced by a12.  The -a flag does not affect the full
167       output given by the -f flag (which always includes both s12 and a12).
168

ADDITIONAL QUANTITIES

170       The -f flag reports four additional quantities.
171
172       The reduced length of the geodesic, m12, is defined such that if the
173       initial azimuth is perturbed by dazi1 (radians) then the second point
174       is displaced by m12 dazi1 in the direction perpendicular to the
175       geodesic.  m12 is given in meters.  On a curved surface the reduced
176       length obeys a symmetry relation, m12 + m21 = 0.  On a flat surface, we
177       have m12 = s12.
178
179       M12 and M21 are geodesic scales.  If two geodesics are parallel at
180       point 1 and separated by a small distance dt, then they are separated
181       by a distance M12 dt at point 2.  M21 is defined similarly (with the
182       geodesics being parallel to one another at point 2).  M12 and M21 are
183       dimensionless quantities.  On a flat surface, we have M12 = M21 = 1.
184
185       If points 1, 2, and 3 lie on a single geodesic, then the following
186       addition rules hold:
187
188          s13 = s12 + s23,
189          a13 = a12 + a23,
190          S13 = S12 + S23,
191          m13 = m12 M23 + m23 M21,
192          M13 = M12 M23 - (1 - M12 M21) m23 / m12,
193          M31 = M32 M21 - (1 - M23 M32) m12 / m23.
194
195       Finally, S12 is the area between the geodesic from point 1 to point 2
196       and the equator; i.e., it is the area, measured counter-clockwise, of
197       the geodesic quadrilateral with corners (lat1,lon1), (0,lon1),
198       (0,lon2), and (lat2,lon2).  It is given in meters^2.
199

PRECISION

201       prec gives precision of the output with prec = 0 giving 1 m precision,
202       prec = 3 giving 1 mm precision, etc.  prec is the number of digits
203       after the decimal point for lengths.  For decimal degrees, the number
204       of digits after the decimal point is prec + 5.  For DMS (degree,
205       minute, seconds) output, the number of digits after the decimal point
206       in the seconds component is prec + 1.  The minimum value of prec is 0
207       and the maximum is 10.
208

ERRORS

210       An illegal line of input will print an error message to standard output
211       beginning with "ERROR:" and causes GeodSolve to return an exit code of
212       1.  However, an error does not cause GeodSolve to terminate; following
213       lines will be converted.
214

ACCURACY

216       Using the (default) series solution, GeodSolve is accurate to about 15
217       nm (15 nanometers) for the WGS84 ellipsoid.  The approximate maximum
218       error (expressed as a distance) for an ellipsoid with the same
219       equatorial radius as the WGS84 ellipsoid and different values of the
220       flattening is
221
222          |f|     error
223          0.01    25 nm
224          0.02    30 nm
225          0.05    10 um
226          0.1    1.5 mm
227          0.2    300 mm
228
229       If -E is specified, GeodSolve is accurate to about 40 nm (40
230       nanometers) for the WGS84 ellipsoid.  The approximate maximum error
231       (expressed as a distance) for an ellipsoid with a quarter meridian of
232       10000 km and different values of the a/b = 1 - f is
233
234          1-f    error (nm)
235          1/128   387
236          1/64    345
237          1/32    269
238          1/16    210
239          1/8     115
240          1/4      69
241          1/2      36
242            1      15
243            2      25
244            4      96
245            8     318
246           16     985
247           32    2352
248           64    6008
249          128   19024
250

MULTIPLE SOLUTIONS

252       The shortest distance returned for the inverse problem is (obviously)
253       uniquely defined.  However, in a few special cases there are multiple
254       azimuths which yield the same shortest distance.  Here is a catalog of
255       those cases:
256
257       lat1 = -lat2 (with neither point at a pole)
258           If azi1 = azi2, the geodesic is unique.  Otherwise there are two
259           geodesics and the second one is obtained by setting [azi1,azi2] =
260           [azi2,azi1], [M12,M21] = [M21,M12], S12 = -S12.  (This occurs when
261           the longitude difference is near +/-180 for oblate ellipsoids.)
262
263       lon2 = lon1 +/- 180 (with neither point at a pole)
264           If azi1 = 0 or +/-180, the geodesic is unique.  Otherwise there are
265           two geodesics and the second one is obtained by setting [azi1,azi2]
266           = [-azi1,-azi2], S12 = -S12.  (This occurs when lat2 is near -lat1
267           for prolate ellipsoids.)
268
269       Points 1 and 2 at opposite poles
270           There are infinitely many geodesics which can be generated by
271           setting [azi1,azi2] = [azi1,azi2] + [d,-d], for arbitrary d.  (For
272           spheres, this prescription applies when points 1 and 2 are
273           antipodal.)
274
275       s12 = 0 (coincident points)
276           There are infinitely many geodesics which can be generated by
277           setting [azi1,azi2] = [azi1,azi2] + [d,d], for arbitrary d.
278

EXAMPLES

280       Route from JFK Airport to Singapore Changi Airport:
281
282          echo 40:38:23N 073:46:44W 01:21:33N 103:59:22E |
283          GeodSolve -i -: -p 0
284
285          003:18:29.9 177:29:09.2 15347628
286
287       Equally spaced waypoints on the route:
288
289          for ((i = 0; i <= 10; ++i)); do echo $i/10; done |
290          GeodSolve -I 40:38:23N 073:46:44W 01:21:33N 103:59:22E -F -: -p 0
291
292          40:38:23.0N 073:46:44.0W 003:18:29.9
293          54:24:51.3N 072:25:39.6W 004:18:44.1
294          68:07:37.7N 069:40:42.9W 006:44:25.4
295          81:38:00.4N 058:37:53.9W 017:28:52.7
296          83:43:26.0N 080:37:16.9E 156:26:00.4
297          70:20:29.2N 097:01:29.4E 172:31:56.4
298          56:38:36.0N 100:14:47.6E 175:26:10.5
299          42:52:37.1N 101:43:37.2E 176:34:28.6
300          29:03:57.0N 102:39:34.8E 177:07:35.2
301          15:13:18.6N 103:22:08.0E 177:23:44.7
302          01:21:33.0N 103:59:22.0E 177:29:09.2
303

SEE ALSO

305       GeoConvert(1).
306
307       An online version of this utility is availbable at
308       <https://geographiclib.sourceforge.io/cgi-bin/GeodSolve>.
309
310       The algorithms are described in C. F. F. Karney, Algorithms for
311       geodesics, J. Geodesy 87, 43-55 (2013); DOI:
312       <https://doi.org/10.1007/s00190-012-0578-z>; addenda:
313       <https://geographiclib.sourceforge.io/geod-addenda.html>.
314
315       The Wikipedia page, Geodesics on an ellipsoid,
316       <https://en.wikipedia.org/wiki/Geodesics_on_an_ellipsoid>.
317

AUTHOR

319       GeodSolve was written by Charles Karney.
320

HISTORY

322       GeodSolve was added to GeographicLib,
323       <https://geographiclib.sourceforge.io>, in 2009-03.  Prior to version
324       1.30, it was called Geod.  (The name was changed to avoid a conflict
325       with the geod utility in proj.4.)
326
327
328
329GeographicLib 1.51                2020-11-22                      GEODSOLVE(1)
Impressum