254 lines
8.6 KiB
Plaintext
254 lines
8.6 KiB
Plaintext
=head1 NAME
|
|
|
|
RhumbSolve -- perform rhumb line calculations
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
B<RhumbSolve> [ B<-i> | B<-L> I<lat1> I<lon1> I<azi12> ]
|
|
[ B<-e> I<a> I<f> ]
|
|
[ B<-d> | B<-:> ] [ B<-w> ] [ B<-p> I<prec> ] [ B<-s> ]
|
|
[ B<--comment-delimiter> I<commentdelim> ]
|
|
[ B<--version> | B<-h> | B<--help> ]
|
|
[ B<--input-file> I<infile> | B<--input-string> I<instring> ]
|
|
[ B<--line-separator> I<linesep> ]
|
|
[ B<--output-file> I<outfile> ]
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
The path with constant heading between two points on the ellipsoid at
|
|
(I<lat1>, I<lon1>) and (I<lat2>, I<lon2>) is called the rhumb line or
|
|
loxodrome. Its length is I<s12> and the rhumb line has a forward
|
|
azimuth I<azi12> along its length. Also computed is I<S12> is the area
|
|
between the rhumb line from point 1 to point 2 and the equator; i.e., it
|
|
is the area, measured counter-clockwise, of the geodesic quadrilateral
|
|
with corners (I<lat1>,I<lon1>), (0,I<lon1>), (0,I<lon2>), and
|
|
(I<lat2>,I<lon2>). A point at a pole is treated as a point a tiny
|
|
distance away from the pole on the given line of longitude. The
|
|
longitude becomes indeterminate when a rhumb line passes through a pole,
|
|
and B<RhumbSolve> reports NaNs for the longitude and the area in this
|
|
case.
|
|
|
|
B<NOTE:> the rhumb line is B<not> the shortest path between two points;
|
|
that is the geodesic and it is calculated by GeodSolve(1).
|
|
|
|
B<RhumbSolve> operates in one of three modes:
|
|
|
|
=over
|
|
|
|
=item 1.
|
|
|
|
By default, B<RhumbSolve> accepts lines on the standard input containing
|
|
I<lat1> I<lon1> I<azi12> I<s12> and prints I<lat2> I<lon2> I<S12> on
|
|
standard output. This is the direct calculation.
|
|
|
|
=item 2.
|
|
|
|
With the B<-i> command line argument, B<RhumbSolve> performs the inverse
|
|
calculation. It reads lines containing I<lat1> I<lon1> I<lat2> I<lon2>
|
|
and prints the values of I<azi12> I<s12> I<S12> for the corresponding
|
|
shortest rhumb lines. If the end points are on opposite meridians,
|
|
there are two shortest rhumb lines and the east-going one is chosen.
|
|
|
|
=item 3.
|
|
|
|
Command line arguments B<-L> I<lat1> I<lon1> I<azi12> specify a rhumb
|
|
line. B<RhumbSolve> then accepts a sequence of I<s12> values (one per
|
|
line) on standard input and prints I<lat2> I<lon2> I<S12> for each.
|
|
This generates a sequence of points on a rhumb line.
|
|
|
|
=back
|
|
|
|
=head1 OPTIONS
|
|
|
|
=over
|
|
|
|
=item B<-i>
|
|
|
|
perform an inverse calculation (see 2 above).
|
|
|
|
=item B<-L> I<lat1> I<lon1> I<azi12>
|
|
|
|
line mode (see 3 above); generate a sequence of points along the rhumb
|
|
line specified by I<lat1> I<lon1> I<azi12>. The B<-w> flag can be used
|
|
to swap the default order of the 2 geographic coordinates, provided that
|
|
it appears before B<-L>. (B<-l> is an alternative, deprecated, spelling
|
|
of this flag.)
|
|
|
|
=item B<-e> I<a> I<f>
|
|
|
|
specify the ellipsoid via the equatorial radius, I<a> and
|
|
the flattening, I<f>. Setting I<f> = 0 results in a sphere. Specify
|
|
I<f> E<lt> 0 for a prolate ellipsoid. A simple fraction, e.g., 1/297,
|
|
is allowed for I<f>. By default, the WGS84 ellipsoid is used, I<a> =
|
|
6378137 m, I<f> = 1/298.257223563.
|
|
|
|
=item B<-d>
|
|
|
|
output angles as degrees, minutes, seconds instead of decimal degrees.
|
|
|
|
=item B<-:>
|
|
|
|
like B<-d>, except use : as a separator instead of the d, ', and "
|
|
delimiters.
|
|
|
|
=item B<-w>
|
|
|
|
on input and output, longitude precedes latitude (except that on input
|
|
this can be overridden by a hemisphere designator, I<N>, I<S>, I<E>,
|
|
I<W>).
|
|
|
|
=item B<-p> I<prec>
|
|
|
|
set the output precision to I<prec> (default 3); I<prec> is the
|
|
precision relative to 1 m. See L</PRECISION>.
|
|
|
|
=item B<-s>
|
|
|
|
By default, the rhumb line calculations are carried out exactly in terms
|
|
of elliptic integrals. This includes the use of the addition theorem
|
|
for elliptic integrals to compute the divided difference of the
|
|
isometric and rectifying latitudes. If B<-s> is supplied this divided
|
|
difference is computed using Krueger series for the transverse Mercator
|
|
projection which is only accurate for |I<f>| E<lt> 0.01. See
|
|
L</ACCURACY>.
|
|
|
|
=item B<--comment-delimiter> I<commentdelim>
|
|
|
|
set the comment delimiter to I<commentdelim> (e.g., "#" or "//"). If
|
|
set, the input lines will be scanned for this delimiter and, if found,
|
|
the delimiter and the rest of the line will be removed prior to
|
|
processing and subsequently appended to the output line (separated by a
|
|
space).
|
|
|
|
=item B<--version>
|
|
|
|
print version and exit.
|
|
|
|
=item B<-h>
|
|
|
|
print usage and exit.
|
|
|
|
=item B<--help>
|
|
|
|
print full documentation and exit.
|
|
|
|
=item B<--input-file> I<infile>
|
|
|
|
read input from the file I<infile> instead of from standard input; a file
|
|
name of "-" stands for standard input.
|
|
|
|
=item B<--input-string> I<instring>
|
|
|
|
read input from the string I<instring> instead of from standard input.
|
|
All occurrences of the line separator character (default is a semicolon)
|
|
in I<instring> are converted to newlines before the reading begins.
|
|
|
|
=item B<--line-separator> I<linesep>
|
|
|
|
set the line separator character to I<linesep>. By default this is a
|
|
semicolon.
|
|
|
|
=item B<--output-file> I<outfile>
|
|
|
|
write output to the file I<outfile> instead of to standard output; a
|
|
file name of "-" stands for standard output.
|
|
|
|
=back
|
|
|
|
=head1 INPUT
|
|
|
|
B<RhumbSolve> measures all angles in degrees, all lengths (I<s12>) in
|
|
meters, and all areas (I<S12>) in meters^2. On input angles (latitude,
|
|
longitude, azimuth, arc length) can be as decimal degrees or degrees,
|
|
minutes, seconds. For example, C<40d30>, C<40d30'>, C<40:30>, C<40.5d>,
|
|
and C<40.5> are all equivalent. By default, latitude precedes longitude
|
|
for each point (the B<-w> flag switches this convention); however on
|
|
input either may be given first by appending (or prepending) I<N> or
|
|
I<S> to the latitude and I<E> or I<W> to the longitude. Azimuths are
|
|
measured clockwise from north; however this may be overridden with I<E>
|
|
or I<W>.
|
|
|
|
For details on the allowed formats for angles, see the C<GEOGRAPHIC
|
|
COORDINATES> section of GeoConvert(1).
|
|
|
|
=head1 PRECISION
|
|
|
|
I<prec> gives precision of the output with I<prec> = 0 giving 1 m
|
|
precision, I<prec> = 3 giving 1 mm precision, etc. I<prec> is the
|
|
number of digits after the decimal point for lengths. For decimal
|
|
degrees, the number of digits after the decimal point is I<prec> + 5.
|
|
For DMS (degree, minute, seconds) output, the number of digits after the
|
|
decimal point in the seconds component is I<prec> + 1. The minimum
|
|
value of I<prec> is 0 and the maximum is 10.
|
|
|
|
=head1 ERRORS
|
|
|
|
An illegal line of input will print an error message to standard output
|
|
beginning with C<ERROR:> and causes B<RhumbSolve> to return an exit code
|
|
of 1. However, an error does not cause B<RhumbSolve> to terminate;
|
|
following lines will be converted.
|
|
|
|
=head1 ACCURACY
|
|
|
|
The algorithm used by B<RhumbSolve> uses exact formulas for converting
|
|
between the latitude, rectifying latitude (I<mu>), and isometric
|
|
latitude (I<psi>). These formulas are accurate for any value of the
|
|
flattening. The computation of rhumb lines involves the ratio (I<psi1>
|
|
- I<psi2>) / (I<mu1> - I<mu2>) and this is subject to large round-off
|
|
errors if I<lat1> is close to I<lat2>. So this ratio is computed using
|
|
divided differences using one of two methods: by default, this uses the
|
|
addition theorem for elliptic integrals (accurate for all values of
|
|
I<f>); however, with the B<-s> options, it is computed using the series
|
|
expansions used by TransverseMercatorProj(1) for the conversions between
|
|
rectifying and conformal latitudes (accurate for |I<f>| E<lt> 0.01).
|
|
For the WGS84 ellipsoid, the error is about 10 nanometers using either
|
|
method.
|
|
|
|
=head1 EXAMPLES
|
|
|
|
Route from JFK Airport to Singapore Changi Airport:
|
|
|
|
echo 40:38:23N 073:46:44W 01:21:33N 103:59:22E |
|
|
RhumbSolve -i -: -p 0
|
|
|
|
103:34:58.2 18523563
|
|
|
|
N.B. This is B<not> the route typically taken by aircraft because it's
|
|
considerably longer than the geodesic given by GeodSolve(1).
|
|
|
|
Waypoints on the route at intervals of 2000km:
|
|
|
|
for ((i = 0; i <= 20; i += 2)); do echo ${i}000000;done |
|
|
RhumbSolve -L 40:38:23N 073:46:44W 103:34:58.2 -: -p 0
|
|
|
|
40:38:23.0N 073:46:44.0W 0
|
|
36:24:30.3N 051:28:26.4W 9817078307821
|
|
32:10:26.8N 030:20:57.3W 18224745682005
|
|
27:56:13.2N 010:10:54.2W 25358020327741
|
|
23:41:50.1N 009:12:45.5E 31321269267102
|
|
19:27:18.7N 027:59:22.1E 36195163180159
|
|
15:12:40.2N 046:17:01.1E 40041499143669
|
|
10:57:55.9N 064:12:52.8E 42906570007050
|
|
06:43:07.3N 081:53:28.8E 44823504180200
|
|
02:28:16.2N 099:24:54.5E 45813843358737
|
|
01:46:36.0S 116:52:59.7E 45888525219677
|
|
|
|
=head1 SEE ALSO
|
|
|
|
GeoConvert(1), GeodSolve(1), TransverseMercatorProj(1).
|
|
|
|
An online version of this utility is availbable at
|
|
L<https://geographiclib.sourceforge.io/cgi-bin/RhumbSolve>.
|
|
|
|
The Wikipedia page, Rhumb line,
|
|
L<https://en.wikipedia.org/wiki/Rhumb_line>.
|
|
|
|
=head1 AUTHOR
|
|
|
|
B<RhumbSolve> was written by Charles Karney.
|
|
|
|
=head1 HISTORY
|
|
|
|
B<RhumbSolve> was added to GeographicLib,
|
|
L<https://geographiclib.sourceforge.io>, in version 1.37.
|