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

NAME

6       RhumbSolve -- perform rhumb line calculations
7

SYNOPSIS

9       RhumbSolve [ -i | -L lat1 lon1 azi12 ] [ -e a f ] [ -d | -: ] [ -w ] [
10       -p prec ] [ -s ] [ --comment-delimiter commentdelim ] [ --version | -h
11       | --help ] [ --input-file infile | --input-string instring ] [
12       --line-separator linesep ] [ --output-file outfile ]
13

DESCRIPTION

15       The path with constant heading between two points on the ellipsoid at
16       (lat1, lon1) and (lat2, lon2) is called the rhumb line or loxodrome.
17       Its length is s12 and the rhumb line has a forward azimuth azi12 along
18       its length.  Also computed is S12 is the area between the rhumb line
19       from point 1 to point 2 and the equator; i.e., it is the area, measured
20       counter-clockwise, of the geodesic quadrilateral with corners
21       (lat1,lon1), (0,lon1), (0,lon2), and (lat2,lon2).  A point at a pole is
22       treated as a point a tiny distance away from the pole on the given line
23       of longitude.  The longitude becomes indeterminate when a rhumb line
24       passes through a pole, and RhumbSolve reports NaNs for the longitude
25       and the area in this case.
26
27       NOTE: the rhumb line is not the shortest path between two points; that
28       is the geodesic and it is calculated by GeodSolve(1).
29
30       RhumbSolve operates in one of three modes:
31
32       1.  By default, RhumbSolve accepts lines on the standard input
33           containing lat1 lon1 azi12 s12 and prints lat2 lon2 S12 on standard
34           output.  This is the direct calculation.
35
36       2.  With the -i command line argument, RhumbSolve performs the inverse
37           calculation.  It reads lines containing lat1 lon1 lat2 lon2 and
38           prints the values of azi12 s12 S12 for the corresponding shortest
39           rhumb lines.  If the end points are on opposite meridians, there
40           are two shortest rhumb lines and the east-going one is chosen.
41
42       3.  Command line arguments -L lat1 lon1 azi12 specify a rhumb line.
43           RhumbSolve then accepts a sequence of s12 values (one per line) on
44           standard input and prints lat2 lon2 S12 for each.  This generates a
45           sequence of points on a rhumb line.
46

OPTIONS

48       -i  perform an inverse calculation (see 2 above).
49
50       -L lat1 lon1 azi12
51           line mode (see 3 above); generate a sequence of points along the
52           rhumb line specified by lat1 lon1 azi12.  The -w flag can be used
53           to swap the default order of the 2 geographic coordinates, provided
54           that it appears before -L.  (-l is an alternative, deprecated,
55           spelling of this flag.)
56
57       -e a f
58           specify the ellipsoid via the equatorial radius, a and the
59           flattening, f.  Setting f = 0 results in a sphere.  Specify f < 0
60           for a prolate ellipsoid.  A simple fraction, e.g., 1/297, is
61           allowed for f.  By default, the WGS84 ellipsoid is used, a =
62           6378137 m, f = 1/298.257223563.
63
64       -d  output angles as degrees, minutes, seconds instead of decimal
65           degrees.
66
67       -:  like -d, except use : as a separator instead of the d, ', and "
68           delimiters.
69
70       -w  on input and output, longitude precedes latitude (except that on
71           input this can be overridden by a hemisphere designator, N, S, E,
72           W).
73
74       -p prec
75           set the output precision to prec (default 3); prec is the precision
76           relative to 1 m.  See "PRECISION".
77
78       -s  By default, the rhumb line calculations are carried out exactly in
79           terms of elliptic integrals.  This includes the use of the addition
80           theorem for elliptic integrals to compute the divided difference of
81           the isometric and rectifying latitudes.  If -s is supplied this
82           divided difference is computed using Krueger series for the
83           transverse Mercator projection which is only accurate for |f| <
84           0.01.  See "ACCURACY".
85
86       --comment-delimiter commentdelim
87           set the comment delimiter to commentdelim (e.g., "#" or "//").  If
88           set, the input lines will be scanned for this delimiter and, if
89           found, the delimiter and the rest of the line will be removed prior
90           to processing and subsequently appended to the output line
91           (separated by a space).
92
93       --version
94           print version and exit.
95
96       -h  print usage and exit.
97
98       --help
99           print full documentation and exit.
100
101       --input-file infile
102           read input from the file infile instead of from standard input; a
103           file name of "-" stands for standard input.
104
105       --input-string instring
106           read input from the string instring instead of from standard input.
107           All occurrences of the line separator character (default is a
108           semicolon) in instring are converted to newlines before the reading
109           begins.
110
111       --line-separator linesep
112           set the line separator character to linesep.  By default this is a
113           semicolon.
114
115       --output-file outfile
116           write output to the file outfile instead of to standard output; a
117           file name of "-" stands for standard output.
118

INPUT

120       RhumbSolve measures all angles in degrees, all lengths (s12) in meters,
121       and all areas (S12) in meters^2.  On input angles (latitude, longitude,
122       azimuth, arc length) can be as decimal degrees or degrees, minutes,
123       seconds.  For example, "40d30", "40d30'", "40:30", "40.5d", and 40.5
124       are all equivalent.  By default, latitude precedes longitude for each
125       point (the -w flag switches this convention); however on input either
126       may be given first by appending (or prepending) N or S to the latitude
127       and E or W to the longitude.  Azimuths are measured clockwise from
128       north; however this may be overridden with E or W.
129
130       For details on the allowed formats for angles, see the "GEOGRAPHIC
131       COORDINATES" section of GeoConvert(1).
132

PRECISION

134       prec gives precision of the output with prec = 0 giving 1 m precision,
135       prec = 3 giving 1 mm precision, etc.  prec is the number of digits
136       after the decimal point for lengths.  For decimal degrees, the number
137       of digits after the decimal point is prec + 5.  For DMS (degree,
138       minute, seconds) output, the number of digits after the decimal point
139       in the seconds component is prec + 1.  The minimum value of prec is 0
140       and the maximum is 10.
141

ERRORS

143       An illegal line of input will print an error message to standard output
144       beginning with "ERROR:" and causes RhumbSolve to return an exit code of
145       1.  However, an error does not cause RhumbSolve to terminate; following
146       lines will be converted.
147

ACCURACY

149       The algorithm used by RhumbSolve uses exact formulas for converting
150       between the latitude, rectifying latitude (mu), and isometric latitude
151       (psi).  These formulas are accurate for any value of the flattening.
152       The computation of rhumb lines involves the ratio (psi1 - psi2) / (mu1
153       - mu2) and this is subject to large round-off errors if lat1 is close
154       to lat2.  So this ratio is computed using divided differences using one
155       of two methods: by default, this uses the addition theorem for elliptic
156       integrals (accurate for all values of f); however, with the -s options,
157       it is computed using the series expansions used by
158       TransverseMercatorProj(1) for the conversions between rectifying and
159       conformal latitudes (accurate for |f| < 0.01).  For the WGS84
160       ellipsoid, the error is about 10 nanometers using either method.
161

EXAMPLES

163       Route from JFK Airport to Singapore Changi Airport:
164
165          echo 40:38:23N 073:46:44W 01:21:33N 103:59:22E |
166          RhumbSolve -i -: -p 0
167
168          103:34:58.2 18523563
169
170       N.B. This is not the route typically taken by aircraft because it's
171       considerably longer than the geodesic given by GeodSolve(1).
172
173       Waypoints on the route at intervals of 2000km:
174
175          for ((i = 0; i <= 20; i += 2)); do echo ${i}000000;done |
176          RhumbSolve -L 40:38:23N 073:46:44W 103:34:58.2 -: -p 0
177
178          40:38:23.0N 073:46:44.0W 0
179          36:24:30.3N 051:28:26.4W 9817078307821
180          32:10:26.8N 030:20:57.3W 18224745682005
181          27:56:13.2N 010:10:54.2W 25358020327741
182          23:41:50.1N 009:12:45.5E 31321269267102
183          19:27:18.7N 027:59:22.1E 36195163180159
184          15:12:40.2N 046:17:01.1E 40041499143669
185          10:57:55.9N 064:12:52.8E 42906570007050
186          06:43:07.3N 081:53:28.8E 44823504180200
187          02:28:16.2N 099:24:54.5E 45813843358737
188          01:46:36.0S 116:52:59.7E 45888525219677
189

SEE ALSO

191       GeoConvert(1), GeodSolve(1), TransverseMercatorProj(1).
192
193       An online version of this utility is availbable at
194       <https://geographiclib.sourceforge.io/cgi-bin/RhumbSolve>.
195
196       The Wikipedia page, Rhumb line,
197       <https://en.wikipedia.org/wiki/Rhumb_line>.
198

AUTHOR

200       RhumbSolve was written by Charles Karney.
201

HISTORY

203       RhumbSolve was added to GeographicLib,
204       <https://geographiclib.sourceforge.io>, in version 1.37.
205
206
207
208GeographicLib 1.51                2020-11-22                     RHUMBSOLVE(1)
Impressum