henry/SimCore
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

ADD: new track message, Entity class and Position class

Browse Source
This commit is contained in:
Henry Winkel
2022-12-20 17:20:35 +01:00
parent 469ecfb099
commit 98ebb563a8
2114 changed files with 482360 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
libs/geographiclib/man/.gitignore vendored Normal file
View File

@@ -0,0 +1,8 @@
*.1
Makefile.in
Makefile
CMakeFiles
cmake_install.cmake
*.usage
*.1.html
*.tmp

31
libs/geographiclib/man/CMakeLists.txt Normal file
View File

@@ -0,0 +1,31 @@
if (RELEASE)
# In RELEASE mode the man pages are already available in man, html,
# and usage formats This cmake file then just has to install the man
# pages. The html pages will be copied by doc/CMakeLists.txt and the
# usage pages will be included by tools/CMakeLists.txt
if (MANDIR AND BINDIR)
foreach (TOOL ${TOOLS})
install (FILES ${TOOL}.1 DESTINATION ${MANDIR}/man1)
endforeach ()
endif ()
else ()
include (../cmake/maintainer-man.cmake)
endif ()
if (NOT WIN32)
# Install the man pages for the scripts. This is the same for RELEASE
# and non-RELEASE
set (SYSMANPAGES)
foreach (SCRIPT ${SCRIPTS})
string (REPLACE geographiclib-get- "" DATA ${SCRIPT})
set (SYSMANPAGES ${SYSMANPAGES} ${CMAKE_CURRENT_BINARY_DIR}/${SCRIPT}.8)
configure_file (script.8.in ${SCRIPT}.8 @ONLY)
endforeach ()
if (MANDIR AND SBINDIR)
install (FILES ${SYSMANPAGES} DESTINATION ${MANDIR}/man8)
endif ()
endif ()

150
libs/geographiclib/man/CartConvert.pod Normal file
View File

@@ -0,0 +1,150 @@
=head1 NAME
CartConvert -- convert geodetic coordinates to geocentric or local cartesian
=head1 SYNOPSIS
B<CartConvert> [ B<-r> ] [ B<-l> I<lat0> I<lon0> I<h0> ]
[ B<-e> I<a> I<f> ] [ B<-w> ] [ B<-p> I<prec> ]
[ 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
Convert geodetic coordinates to either geocentric or local cartesian
coordinates. Geocentric coordinates have the origin at the center of
the earth, with the I<z> axis going thru the north pole, and the I<x>
axis thru I<latitude> = 0, I<longitude> = 0. By default, the
conversion is to geocentric coordinates. Specifying B<-l> I<lat0>
I<lon0> I<h0> causes a local coordinate system to be used with the
origin at I<latitude> = I<lat0>, I<longitude> = I<lon0>, I<height> =
I<h0>, I<z> normal to the ellipsoid and I<y> due north.
Geodetic coordinates are provided on standard input as a set of lines
containing (blank separated) I<latitude>, I<longitude> (decimal degrees
or degrees, minutes and seconds), and I<height> above the ellipsoid
(meters); for details on the allowed formats for latitude and longitude,
see the C<GEOGRAPHIC COORDINATES> section of GeoConvert(1). For each
set of geodetic coordinates, the corresponding cartesian coordinates
I<x>, I<y>, I<z> (meters) are printed on standard output.
=head1 OPTIONS
=over
=item B<-r>
perform the reverse projection. I<x>, I<y>, I<z> are given on
standard input and each line of standard output gives I<latitude>,
I<longitude>, I<height>. In general there are multiple solutions and
the result which minimizes the absolute value of I<height> is
returned, i.e., (I<latitude>, I<longitude>) corresponds to the closest
point on the ellipsoid.
=item B<-l> I<lat0> I<lon0> I<h0>
specifies conversions to and from a local cartesion coordinate systems
with origin I<lat0> I<lon0> I<h0>, instead of a geocentric coordinate
system. The B<-w> flag can be used to swap the default order of the 2
geographic coordinates, provided that it appears before B<-l>.
=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<-w>
toggle the longitude first flag (it starts off); if the flag is on, then
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 6). I<prec> is the number
of digits after the decimal point for geocentric and local cartesion
coordinates and for the height (in meters). For latitudes and
longitudes (in degrees), the number of digits after the decimal point is
I<prec> + 5.
=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 EXAMPLES
echo 33.3 44.4 6000 | CartConvert
=> 3816209.60 3737108.55 3485109.57
echo 33.3 44.4 6000 | CartConvert -l 33 44 20
=> 37288.97 33374.29 5783.64
echo 30000 30000 0 | CartConvert -r
=> 6.483 45 -6335709.73
=head1 ERRORS
An illegal line of input will print an error message to standard output
beginning with C<ERROR:> and causes B<CartConvert> to return an exit
code of 1. However, an error does not cause B<CartConvert> to
terminate; following lines will be converted.
=head1 SEE ALSO
The algorithm for converting geocentric to geodetic coordinates is given
in Appendix B of C. F. F. Karney, I<Geodesics on an ellipsoid of
revolution>, Feb. 2011; preprint L<https://arxiv.org/abs/1102.1215>.
=head1 AUTHOR
B<CartConvert> was written by Charles Karney.
=head1 HISTORY
B<CartConvert> was added to GeographicLib,
L<https://geographiclib.sourceforge.io>, in 2009-02. Prior to 2009-03 it was
called ECEFConvert.

165
libs/geographiclib/man/ConicProj.pod Normal file
View File

@@ -0,0 +1,165 @@
=head1 NAME
ConicProj -- perform conic projections
=head1 SYNOPSIS
B<ConicProj> ( B<-c> | B<-a> ) I<lat1> I<lat2>
[ B<-l> I<lon0> ] [ B<-k> I<k1> ] [ B<-r> ]
[ B<-e> I<a> I<f> ] [ B<-w> ] [ B<-p> I<prec> ]
[ 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
Perform one of two conic projections geodesics. Convert geodetic
coordinates to either Lambert conformal conic or Albers equal area
coordinates. The standard latitudes I<lat1> and I<lat2> are specified
by that the B<-c> option (for Lambert conformal conic) or the B<-a>
option (for Albers equal area). At least one of these options must be
given (the last one given is used). Specify I<lat1> = I<lat2>, to
obtain the case with a single standard parallel. The central meridian
is given by I<lon0>. The longitude of origin is given by the latitude
of minimum (azimuthal) scale for Lambert conformal conic (Albers equal
area). The (azimuthal) scale on the standard parallels is I<k1>.
Geodetic coordinates are provided on standard input as a set of lines
containing (blank separated) I<latitude> and I<longitude> (decimal
degrees or degrees, minutes, seconds); for details on the allowed
formats for latitude and longitude, see the C<GEOGRAPHIC COORDINATES>
section of GeoConvert(1). For each set of geodetic coordinates, the
corresponding projected easting, I<x>, and northing, I<y>, (meters) are
printed on standard output together with the meridian convergence
I<gamma> (degrees) and (azimuthal) scale I<k>. For Albers equal area,
the radial scale is 1/I<k>. The meridian convergence is the bearing of
the I<y> axis measured clockwise from true north.
Special cases of the Lambert conformal projection are the Mercator
projection (the standard latitudes equal and opposite) and the polar
stereographic projection (both standard latitudes correspond to the same
pole). Special cases of the Albers equal area projection are the
cylindrical equal area projection (the standard latitudes equal and
opposite), the Lambert azimuthal equal area projection (both standard
latitude corresponds to the same pole), and the Lambert equal area conic
projection (one standard parallel is at a pole).
=head1 OPTIONS
=over
=item B<-c> I<lat1> I<lat2>
use the Lambert conformal conic projection with standard parallels
I<lat1> and I<lat2>.
=item B<-a> I<lat1> I<lat2>
use the Albers equal area projection with standard parallels I<lat1> and
I<lat2>.
=item B<-l> I<lon0>
specify the longitude of origin I<lon0> (degrees, default 0).
=item B<-k> I<k1>
specify the (azimuthal) scale I<k1> on the standard parallels (default
1).
=item B<-r>
perform the reverse projection. I<x> and I<y> are given on standard
input and each line of standard output gives I<latitude>, I<longitude>,
I<gamma>, and I<k>.
=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<-w>
toggle the longitude first flag (it starts off); if the flag is on, then
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 6). I<prec> is the number
of digits after the decimal point for lengths (in meters). For
latitudes and longitudes (in degrees), the number of digits after the
decimal point is I<prec> + 5. For the convergence (in degrees) and
scale, the number of digits after the decimal point is I<prec> + 6.
=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 EXAMPLES
echo 39.95N 75.17W | ConicProj -c 40d58 39d56 -l 77d45W
=> 220445 -52372 1.67 1.0
echo 220445 -52372 | ConicProj -c 40d58 39d56 -l 77d45W -r
=> 39.95 -75.17 1.67 1.0
=head1 ERRORS
An illegal line of input will print an error message to standard output
beginning with C<ERROR:> and causes B<ConicProj> to return an exit
code of 1. However, an error does not cause B<ConicProj> to
terminate; following lines will be converted.
=head1 AUTHOR
B<ConicProj> was written by Charles Karney.
=head1 HISTORY
B<ConicProj> was added to GeographicLib,
L<https://geographiclib.sourceforge.io>, in version 1.9.

424
libs/geographiclib/man/GeoConvert.pod Normal file
View File

@@ -0,0 +1,424 @@
=head1 NAME
GeoConvert -- convert geographic coordinates
=head1 SYNOPSIS
B<GeoConvert> [ B<-g> | B<-d> | B<-:> | B<-u> | B<-m> | B<-c> ]
[ B<-z> I<zone> | B<-s> | B<-t> | B<-S> | B<-T> ]
[ B<-n> ] [ B<-w> ] [ B<-p> I<prec> ] [ B<-l> | B<-a> ]
[ 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
B<GeoConvert> reads from standard input interpreting each line as a
geographic coordinate and prints the coordinate in the format specified
by the options on standard output. The input is interpreted in one of
three different ways depending on how many space or comma delimited
tokens there are on the line. The options B<-g>, B<-d>, B<-u>, and B<-m>
govern the format of output. In all cases, the WGS84 model of the earth
is used (I<a> = 6378137 m, I<f> = 1/298.257223563).
=over
=item B<geographic>
2 tokens (output options B<-g>, B<-d>, or B<-:>) given as I<latitude>
I<longitude> using decimal degrees or degrees, minutes, and seconds.
Latitude is given first (unless the B<-w> option is given). See
L</GEOGRAPHIC COORDINATES> for a description of the format. For
example, the following are all equivalent
33.3 44.4
E44.4 N33.3
33d18'N 44d24'E
44d24 33d18N
33:18 +44:24
=item B<UTM/UPS>
3 tokens (output option B<-u>) given as I<zone>+I<hemisphere> I<easting>
I<northing> or I<easting> I<northing> I<zone>+I<hemisphere>, where
I<hemisphere> is either I<n> (or I<north>) or I<s> (or I<south>). The
I<zone> is absent for a UPS specification. For example,
38n 444140.54 3684706.36
444140.54 3684706.36 38n
s 2173854.98 2985980.58
2173854.98 2985980.58 s
=item B<MRGS>
1 token (output option B<-m>) is used to specify the center of an MGRS
grid square. For example,
38SMB4484
38SMB44140847064
=back
=head1 OPTIONS
=over
=item B<-g>
output latitude and longitude using decimal degrees. Default output mode.
=item B<-d>
output latitude and longitude using degrees, minutes, and seconds (DMS).
=item B<-:>
like B<-d>, except use : as a separator instead of the d, ', and "
delimiters.
=item B<-u>
output UTM or UPS.
=item B<-m>
output MGRS.
=item B<-c>
output meridian convergence and scale for the corresponding UTM or UPS
projection. The meridian convergence is the bearing of grid north given
as degrees clockwise from true north.
=item B<-z> I<zone>
set the zone to I<zone> for output. Use either 0 E<lt> I<zone> E<lt>=
60 for a UTM zone or I<zone> = 0 for UPS. Alternatively use a
I<zone>+I<hemisphere> designation, e.g., 38n. See L</ZONE>.
=item B<-s>
use the standard UPS and UTM zones.
=item B<-t>
similar to B<-s> but forces UPS regions to the closest UTM zone.
=item B<-S> or B<-T>
behave the same as B<-s> and B<-t>, respectively, until the first legal
conversion is performed. For subsequent points, the zone and hemisphere
of that conversion are used. This enables a sequence of points to be
converted into UTM or UPS using a consistent coordinate system.
=item B<-n>
on input, MGRS coordinates refer to the south-west corner of the MGRS
square instead of the center; see L</MGRS>.
=item B<-w>
toggle the longitude first flag (it starts off); if the flag is on, then
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 0); I<prec> is the
precision relative to 1 m. See L</PRECISION>.
=item B<-l>
on output, UTM/UPS uses the long forms I<north> and I<south> to
designate the hemisphere instead of I<n> or I<s>.
=item B<-a>
on output, UTM/UPS uses the abbreviations I<n> and I<s> to designate the
hemisphere instead of I<north> or I<south>; this is the default
representation.
=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 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 UTM/UPS. For MGRS, The
number of digits per coordinate is 5 + I<prec>; I<prec> = -6 results in
just the grid zone. For decimal degrees, the number of digits after the
decimal point is 5 + I<prec>. For DMS (degree, minute, seconds) output,
the number of digits after the decimal point in the seconds components
is 1 + I<prec>; if this is negative then use minutes (I<prec> = -2 or
-3) or degrees (I<prec> E<lt>= -4) as the least significant component.
Print convergence, resp. scale, with 5 + I<prec>, resp. 7 + I<prec>,
digits after the decimal point. The minimum value of I<prec> is -5 (-6
for MGRS) and the maximum is 9 for UTM/UPS, 9 for decimal degrees, 10
for DMS, 6 for MGRS, and 8 for convergence and scale.
=head1 GEOGRAPHIC COORDINATES
The utility accepts geographic coordinates, latitude and longitude, in a
number of common formats. Latitude precedes longitude, unless the B<-w>
option is given which switches this convention. On input, either
coordinate 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. These hemisphere
designators carry an implied sign, positive for I<N> and I<E> and
negative for I<S> and I<W>. This sign multiplies any +/- sign prefixing
the coordinate. The coordinates may be given as decimal degree or as
degrees, minutes, and seconds. d, ', and " are used to denote degrees,
minutes, and seconds, with the least significant designator optional.
(See L</QUOTING> for how to quote the characters ' and " when entering
coordinates on the command line.) Alternatively, : (colon) may be used
to separate the various components. Only the final component of
coordinate can include a decimal point, and the minutes and seconds
components must be less than 60.
It is also possible to carry out addition or subtraction operations in
geographic coordinates. If the coordinate includes interior signs
(i.e., not at the beginning or immediately after an initial hemisphere
designator), then the coordinate is split before such signs; the pieces
are parsed separately and the results summed. For example the point 15"
east of 39N 70W is
39N 70W+0:0:15E
B<WARNING:> "Exponential" notation is not recognized for geographic
coordinates. Thus 7.0E1 is illegal, while 7.0E+1 is parsed
as (7.0E) + (+1), yielding the same result as 8.0E.
Various unicode characters (encoded with UTF-8) may also be used to
denote degrees, minutes, and seconds, e.g., the degree, prime, and
double prime symbols; in addition two single quotes can be used to
represent ".
The other GeographicLib utilities use the same rules for interpreting
geographic coordinates; in addition, azimuths and arc lengths are
interpreted the same way.
=head1 QUOTING
Unfortunately the characters ' and " have special meanings in many
shells and have to be entered with care. However note (1) that the
trailing designator is optional and that (2) you can use colons as a
separator character. Thus 10d20' can be entered as 10d20 or 10:20 and
10d20'30" can be entered as 10:20:30.
=over
=item Unix shells (sh, bash, tsch)
The characters ' and " can be quoted by preceding them with a \
(backslash); or you can quote a string containing ' with a pair of "s.
The two alternatives are illustrated by
echo 10d20\'30\" "20d30'40" | GeoConvert -d -p -1
=> 10d20'30"N 020d30'40"E
Quoting of command line arguments is similar
GeoConvert -d -p -1 --input-string "10d20'30\" 20d30'40"
=> 10d20'30"N 020d30'40"E
=item Windows command shell (cmd)
The ' character needs no quoting; the " character can either be quoted
by a ^ or can be represented by typing ' twice. (This quoting is
usually unnecessary because the trailing designator can be omitted.)
Thus
echo 10d20'30'' 20d30'40 | GeoConvert -d -p -1
=> 10d20'30"N 020d30'40"E
Use \ to quote the " character in a command line argument
GeoConvert -d -p -1 --input-string "10d20'30\" 20d30'40"
=> 10d20'30"N 020d30'40"E
=item Input from a file
No quoting need be done if the input from a file. Thus each line of the
file C<input.txt> should just contain the plain coordinates.
GeoConvert -d -p -1 < input.txt
=back
=head1 MGRS
MGRS coordinates represent a square patch of the earth, thus
C<38SMB4488> is in zone C<38n> with 444km E<lt>= I<easting> E<lt>
445km and 3688km E<lt>= I<northing> E<lt> 3689km. Consistent with
this representation, coordinates are I<truncated> (instead of
I<rounded>) to the requested precision. When an MGRS coordinate is
provided as input, B<GeoConvert> treats this as a representative point
within the square. By default, this representative point is the
I<center> of the square (C<38n 444500 3688500> in the example above).
(This leads to a stable conversion between MGRS and geographic
coordinates.) However, if the B<-n> option is given then the
south-west corner of the square is returned instead (C<38n 444000
3688000> in the example above).
=head1 ZONE
If the input is B<geographic>, B<GeoConvert> uses the standard rules of
selecting UTM vs UPS and for assigning the UTM zone (with the Norway and
Svalbard exceptions). If the input is B<UTM/UPS> or B<MGRS>, then the
choice between UTM and UPS and the UTM zone mirrors the input. The B<-z>
I<zone>, B<-s>, and B<-t> options allow these rules to be overridden
with I<zone> = 0 being used to indicate UPS. For example, the point
79.9S 6.1E
corresponds to possible MGRS coordinates
32CMS4324728161 (standard UTM zone = 32)
31CEM6066227959 (neighboring UTM zone = 31)
BBZ1945517770 (neighboring UPS zone)
then
echo 79.9S 6.1E | GeoConvert -p -3 -m => 32CMS4328
echo 31CEM6066227959 | GeoConvert -p -3 -m => 31CEM6027
echo 31CEM6066227959 | GeoConvert -p -3 -m -s => 32CMS4328
echo 31CEM6066227959 | GeoConvert -p -3 -m -z 0 => BBZ1917
Is I<zone> is specified with a hemisphere, then this is honored when
printing UTM coordinates:
echo -1 3 | GeoConvert -u => 31s 500000 9889470
echo -1 3 | GeoConvert -u -z 31 => 31s 500000 9889470
echo -1 3 | GeoConvert -u -z 31s => 31s 500000 9889470
echo -1 3 | GeoConvert -u -z 31n => 31n 500000 -110530
B<NOTE>: the letter in the zone specification for UTM is a hemisphere
designator I<n> or I<s> and I<not> an MGRS latitude band letter.
Convert the MGRS latitude band letter to a hemisphere as follows:
replace I<C> thru I<M> by I<s> (or I<south>); replace I<N> thru I<X> by
I<n> (or I<north>).
=head1 EXAMPLES
echo 38SMB4488 | GeoConvert => 33.33424 44.40363
echo 38SMB4488 | GeoConvert -: -p 1 => 33:20:03.25N 044:2413.06E
echo 38SMB4488 | GeoConvert -u => 38n 444500 3688500
echo E44d24 N33d20 | GeoConvert -m -p -3 => 38SMB4488
GeoConvert can be used to do simple arithmetic using degree, minutes,
and seconds. For example, sometimes data is tiled in 15 second squares
tagged by the DMS representation of the SW corner. The tags of the tile
at 38:59:45N 077:02:00W and its 8 neighbors are then given by
t=0:0:15
for y in -$t +0 +$t; do
for x in -$t +0 +$t; do
echo 38:59:45N$y 077:02:00W$x
done
done | GeoConvert -: -p -1 | tr -d ': '
=>
385930N0770215W
385930N0770200W
385930N0770145W
385945N0770215W
385945N0770200W
385945N0770145W
390000N0770215W
390000N0770200W
390000N0770145W
=head1 ERRORS
An illegal line of input will print an error message to standard output
beginning with C<ERROR:> and causes B<GeoConvert> to return an exit code
of 1. However, an error does not cause B<GeoConvert> to terminate;
following lines will be converted.
=head1 ABBREVIATIONS
=over
=item B<UTM>
Universal Transverse Mercator,
L<https://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system>.
=item B<UPS>
Universal Polar Stereographic,
L<https://en.wikipedia.org/wiki/Universal_Polar_Stereographic>.
=item B<MGRS>
Military Grid Reference System,
L<https://en.wikipedia.org/wiki/Military_grid_reference_system>.
=item B<WGS84>
World Geodetic System 1984,
L<https://en.wikipedia.org/wiki/WGS84>.
=back
=head1 SEE ALSO
An online version of this utility is availbable at
L<https://geographiclib.sourceforge.io/cgi-bin/GeoConvert>.
The algorithms for the transverse Mercator projection are described in
C. F. F. Karney, I<Transverse Mercator with an accuracy of a few
nanometers>, J. Geodesy B<85>(8), 475-485 (Aug. 2011); DOI
L<https://doi.org/10.1007/s00190-011-0445-3>; preprint
L<https://arxiv.org/abs/1002.1417>.
=head1 AUTHOR
B<GeoConvert> was written by Charles Karney.
=head1 HISTORY
B<GeoConvert> was added to GeographicLib,
L<https://geographiclib.sourceforge.io>, in 2009-01.

399
libs/geographiclib/man/GeodSolve.pod Normal file
View File

@@ -0,0 +1,399 @@
=head1 NAME
GeodSolve -- perform geodesic calculations
=head1 SYNOPSIS
B<GeodSolve>
[ B<-i> | B<-L> I<lat1> I<lon1> I<azi1> |
B<-D> I<lat1> I<lon1> I<azi1> I<s13> | B<-I> I<lat1> I<lon1> I<lat3> I<lon3> ]
[ B<-a> ] [ B<-e> I<a> I<f> ] [ B<-u> ] [ B<-F> ]
[ B<-d> | B<-:> ] [ B<-w> ] [ B<-b> ] [ B<-f> ] [ B<-p> I<prec> ] [ B<-E> ]
[ 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 shortest path between two points on the ellipsoid at (I<lat1>,
I<lon1>) and (I<lat2>, I<lon2>) is called the geodesic. Its length is
I<s12> and the geodesic from point 1 to point 2 has forward azimuths
I<azi1> and I<azi2> at the two end points.
B<GeodSolve> operates in one of three modes:
=over
=item 1.
By default, B<GeodSolve> accepts lines on the standard input containing
I<lat1> I<lon1> I<azi1> I<s12> and prints I<lat2> I<lon2> I<azi2>
on standard output. This is the direct geodesic calculation.
=item 2.
With the B<-i> command line argument, B<GeodSolve> performs the inverse
geodesic calculation. It reads lines containing I<lat1> I<lon1> I<lat2>
I<lon2> and prints the corresponding values of I<azi1> I<azi2> I<s12>.
=item 3.
Command line arguments B<-L> I<lat1> I<lon1> I<azi1> specify a geodesic
line. B<GeodSolve> then accepts a sequence of I<s12> values (one per
line) on standard input and prints I<lat2> I<lon2> I<azi2> for each.
This generates a sequence of points on a single geodesic. Command line
arguments B<-D> and B<-I> work similarly with the geodesic line defined
in terms of a direct or inverse geodesic calculation, respectively.
=back
=head1 OPTIONS
=over
=item B<-i>
perform an inverse geodesic calculation (see 2 above).
=item B<-L> I<lat1> I<lon1> I<azi1>
line mode (see 3 above); generate a sequence of points along the
geodesic specified by I<lat1> I<lon1> I<azi1>. 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<-D> I<lat1> I<lon1> I<azi1> I<s13>
line mode (see 3 above); generate a sequence of points along the
geodesic specified by I<lat1> I<lon1> I<azi1> I<s13>. The B<-w> flag
can be used to swap the default order of the 2 geographic coordinates,
provided that it appears before B<-D>. Similarly, the B<-a> flag can be
used to change the interpretation of I<s13> to I<a13>, provided that it
appears before B<-D>.
=item B<-I> I<lat1> I<lon1> I<lat3> I<lon3>
line mode (see 3 above); generate a sequence of points along the
geodesic specified by I<lat1> I<lon1> I<lat3> I<lon3>. The B<-w> flag
can be used to swap the default order of the 2 geographic coordinates,
provided that it appears before B<-I>.
=item B<-a>
toggle the arc mode flag (it starts off); if this flag is on, then on
input I<and> output I<s12> is replaced by I<a12> the arc length (in
degrees) on the auxiliary sphere. See L</AUXILIARY SPHERE>.
=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<-u>
unroll the longitude. Normally, on output longitudes are reduced to lie
in [-180deg,180deg). However with this option, the returned longitude
I<lon2> is "unrolled" so that I<lon2> - I<lon1> indicates how often and
in what sense the geodesic has encircled the earth. Use the B<-f>
option, to get both longitudes printed.
=item B<-F>
fractional mode. This only has any effect with the B<-D> and B<-I>
options (and is otherwise ignored). The values read on standard input
are interpreted as fractional distances to point 3, i.e., as
I<s12>/I<s13> instead of I<s12>. If arc mode is in effect, then the
values denote fractional arc length, i.e., I<a12>/I<a13>. The
fractional distances can be entered as a simple fraction, e.g., 3/4.
=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>
toggle the longitude first flag (it starts off); if the flag is on, then
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<-b>
report the I<back> azimuth at point 2 instead of the forward azimuth.
=item B<-f>
full output; each line of output consists of 12 quantities: I<lat1>
I<lon1> I<azi1> I<lat2> I<lon2> I<azi2> I<s12> I<a12> I<m12> I<M12>
I<M21> I<S12>. I<a12> is described in L</AUXILIARY SPHERE>. The four
quantities I<m12>, I<M12>, I<M21>, and I<S12> are described in
L</ADDITIONAL QUANTITIES>.
=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<-E>
use "exact" algorithms (based on elliptic integrals) for the geodesic
calculations. These are more accurate than the (default) series
expansions for |I<f>| E<gt> 0.02.
=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<GeodSolve> measures all angles in degrees and 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 AUXILIARY SPHERE
Geodesics on the ellipsoid can be transferred to the I<auxiliary sphere>
on which the distance is measured in terms of the arc length I<a12>
(measured in degrees) instead of I<s12>. In terms of I<a12>, 180
degrees is the distance from one equator crossing to the next or from
the minimum latitude to the maximum latitude. Geodesics with I<a12>
E<gt> 180 degrees do not correspond to shortest paths. With the B<-a>
flag, I<s12> (on both input and output) is replaced by I<a12>. The
B<-a> flag does I<not> affect the full output given by the B<-f> flag
(which always includes both I<s12> and I<a12>).
=head1 ADDITIONAL QUANTITIES
The B<-f> flag reports four additional quantities.
The reduced length of the geodesic, I<m12>, is defined such that if the
initial azimuth is perturbed by dI<azi1> (radians) then the second point
is displaced by I<m12> dI<azi1> in the direction perpendicular to the
geodesic. I<m12> is given in meters. On a curved surface the
reduced length obeys a symmetry relation, I<m12> + I<m21> = 0. On a
flat surface, we have I<m12> = I<s12>.
I<M12> and I<M21> are geodesic scales. If two geodesics are parallel at
point 1 and separated by a small distance I<dt>, then they are separated
by a distance I<M12> I<dt> at point 2. I<M21> is defined similarly
(with the geodesics being parallel to one another at point 2). I<M12>
and I<M21> are dimensionless quantities. On a flat surface, we have
I<M12> = I<M21> = 1.
If points 1, 2, and 3 lie on a single geodesic, then the following
addition rules hold:
s13 = s12 + s23,
a13 = a12 + a23,
S13 = S12 + S23,
m13 = m12 M23 + m23 M21,
M13 = M12 M23 - (1 - M12 M21) m23 / m12,
M31 = M32 M21 - (1 - M23 M32) m12 / m23.
Finally, I<S12> is the area between the geodesic 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>). It is given in meters^2.
=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<GeodSolve> to return an exit code
of 1. However, an error does not cause B<GeodSolve> to terminate;
following lines will be converted.
=head1 ACCURACY
Using the (default) series solution, GeodSolve is accurate to about 15
nm (15 nanometers) for the WGS84 ellipsoid. The approximate maximum
error (expressed as a distance) for an ellipsoid with the same equatorial
radius as the WGS84 ellipsoid and different values of the flattening is
|f| error
0.01 25 nm
0.02 30 nm
0.05 10 um
0.1 1.5 mm
0.2 300 mm
If B<-E> is specified, GeodSolve is accurate to about 40 nm (40
nanometers) for the WGS84 ellipsoid. The approximate maximum error
(expressed as a distance) for an ellipsoid with a quarter meridian of
10000 km and different values of the I<a/b> = 1 - I<f> is
1-f error (nm)
1/128 387
1/64 345
1/32 269
1/16 210
1/8 115
1/4 69
1/2 36
1 15
2 25
4 96
8 318
16 985
32 2352
64 6008
128 19024
=head1 MULTIPLE SOLUTIONS
The shortest distance returned for the inverse problem is (obviously)
uniquely defined. However, in a few special cases there are multiple
azimuths which yield the same shortest distance. Here is a catalog of
those cases:
=over
=item I<lat1> = -I<lat2> (with neither point at a pole)
If I<azi1> = I<azi2>, the geodesic is unique. Otherwise there are two
geodesics and the second one is obtained by setting [I<azi1>,I<azi2>] =
[I<azi2>,I<azi1>], [I<M12>,I<M21>] = [I<M21>,I<M12>], I<S12> = -I<S12>.
(This occurs when the longitude difference is near +/-180 for oblate
ellipsoids.)
=item I<lon2> = I<lon1> +/- 180 (with neither point at a pole)
If I<azi1> = 0 or +/-180, the geodesic is unique. Otherwise there are
two geodesics and the second one is obtained by setting
[I<azi1>,I<azi2>] = [-I<azi1>,-I<azi2>], I<S12> = -I<S12>. (This occurs
when I<lat2> is near -I<lat1> for prolate ellipsoids.)
=item Points 1 and 2 at opposite poles
There are infinitely many geodesics which can be generated by setting
[I<azi1>,I<azi2>] = [I<azi1>,I<azi2>] + [I<d>,-I<d>], for arbitrary
I<d>. (For spheres, this prescription applies when points 1 and 2 are
antipodal.)
=item I<s12> = 0 (coincident points)
There are infinitely many geodesics which can be generated by setting
[I<azi1>,I<azi2>] = [I<azi1>,I<azi2>] + [I<d>,I<d>], for arbitrary I<d>.
=back
=head1 EXAMPLES
Route from JFK Airport to Singapore Changi Airport:
echo 40:38:23N 073:46:44W 01:21:33N 103:59:22E |
GeodSolve -i -: -p 0
003:18:29.9 177:29:09.2 15347628
Equally spaced waypoints on the route:
for ((i = 0; i <= 10; ++i)); do echo $i/10; done |
GeodSolve -I 40:38:23N 073:46:44W 01:21:33N 103:59:22E -F -: -p 0
40:38:23.0N 073:46:44.0W 003:18:29.9
54:24:51.3N 072:25:39.6W 004:18:44.1
68:07:37.7N 069:40:42.9W 006:44:25.4
81:38:00.4N 058:37:53.9W 017:28:52.7
83:43:26.0N 080:37:16.9E 156:26:00.4
70:20:29.2N 097:01:29.4E 172:31:56.4
56:38:36.0N 100:14:47.6E 175:26:10.5
42:52:37.1N 101:43:37.2E 176:34:28.6
29:03:57.0N 102:39:34.8E 177:07:35.2
15:13:18.6N 103:22:08.0E 177:23:44.7
01:21:33.0N 103:59:22.0E 177:29:09.2
=head1 SEE ALSO
GeoConvert(1).
An online version of this utility is availbable at
L<https://geographiclib.sourceforge.io/cgi-bin/GeodSolve>.
The algorithms are described in C. F. F. Karney,
I<Algorithms for geodesics>, J. Geodesy 87, 43-55 (2013); DOI:
L<https://doi.org/10.1007/s00190-012-0578-z>;
addenda: L<https://geographiclib.sourceforge.io/geod-addenda.html>.
The Wikipedia page, Geodesics on an ellipsoid,
L<https://en.wikipedia.org/wiki/Geodesics_on_an_ellipsoid>.
=head1 AUTHOR
B<GeodSolve> was written by Charles Karney.
=head1 HISTORY
B<GeodSolve> was added to GeographicLib,
L<https://geographiclib.sourceforge.io>, in 2009-03. Prior to version
1.30, it was called B<Geod>. (The name was changed to avoid a conflict
with the B<geod> utility in I<proj.4>.)

162
libs/geographiclib/man/GeodesicProj.pod Normal file
View File

@@ -0,0 +1,162 @@
=head1 NAME
GeodesicProj -- perform projections based on geodesics
=head1 SYNOPSIS
B<GeodesicProj> ( B<-z> | B<-c> | B<-g> ) I<lat0> I<lon0> [ B<-r> ]
[ B<-e> I<a> I<f> ] [ B<-w> ] [ B<-p> I<prec> ]
[ 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
Perform projections based on geodesics. Convert geodetic coordinates to
either azimuthal equidistant, Cassini-Soldner, or gnomonic coordinates.
The center of the projection (I<lat0>, I<lon0>) is specified by either
the B<-c> option (for Cassini-Soldner), the B<-z> option (for azimuthal
equidistant), or the B<-g> option (for gnomonic). At least one of these
options must be given (the last one given is used).
Geodetic coordinates are provided on standard input as a set of lines
containing (blank separated) I<latitude> and I<longitude> (decimal
degrees or degrees, minutes, seconds); for details on the allowed
formats for latitude and longitude, see the C<GEOGRAPHIC COORDINATES>
section of GeoConvert(1). For each set of geodetic coordinates, the
corresponding projected coordinates I<x>, I<y> (meters) are printed on
standard output together with the azimuth I<azi> (degrees) and
reciprocal scale I<rk>. For Cassini-Soldner, I<azi> is the bearing of
the easting direction and the scale in the easting direction is 1 and
the scale in the northing direction is 1/I<rk>. For azimuthal
equidistant and gnomonic, I<azi> is the bearing of the radial direction
and the scale in the azimuthal direction is 1/I<rk>. For azimuthal
equidistant and gnomonic, the scales in the radial direction are 1 and
1/I<rk>^2, respectively.
=head1 OPTIONS
=over
=item B<-z> I<lat0> I<lon0>
use the azimuthal equidistant projection centered at latitude = I<lat0>,
longitude = I<lon0>. The B<-w> flag can be used to swap the default
order of the 2 coordinates, provided that it appears before B<-z>.
=item B<-c> I<lat0> I<lon0>
use the Cassini-Soldner projection centered at latitude = I<lat0>,
longitude = I<lon0>. The B<-w> flag can be used to swap the default
order of the 2 coordinates, provided that it appears before B<-c>.
=item B<-g> I<lat0> I<lon0>
use the ellipsoidal gnomonic projection centered at latitude = I<lat0>,
longitude = I<lon0>. The B<-w> flag can be used to swap the default
order of the 2 coordinates, provided that it appears before B<-g>.
=item B<-r>
perform the reverse projection. I<x> and I<y> are given on standard
input and each line of standard output gives I<latitude>, I<longitude>,
I<azi>, and I<rk>.
=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<-w>
toggle the longitude first flag (it starts off); if the flag is on, then
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 6). I<prec> is the number
of digits after the decimal point for lengths (in meters). For
latitudes, longitudes, and azimuths (in degrees), the number of digits
after the decimal point is I<prec> + 5. For the scale, the number of
digits after the decimal point is I<prec> + 6.
=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 EXAMPLES
echo 48.648 -2.007 | GeodesicProj -c 48.836 2.337
=> -319919 -11791 86.7 0.999
echo -319919 -11791 | GeodesicProj -c 48.836 2.337 -r
=> 48.648 -2.007 86.7 0.999
=head1 ERRORS
An illegal line of input will print an error message to standard output
beginning with C<ERROR:> and causes B<GeodesicProj> to return an exit
code of 1. However, an error does not cause B<GeodesicProj> to
terminate; following lines will be converted.
=head1 SEE ALSO
The ellipsoidal gnomonic projection is derived in Section 8 of
C. F. F. Karney, I<Algorithms for geodesics>, J. Geodesy 87, 43-55 (2013); DOI
L<https://doi.org/10.1007/s00190-012-0578-z>;
addenda: L<https://geographiclib.sourceforge.io/geod-addenda.html>.
=head1 AUTHOR
B<GeodesicProj> was written by Charles Karney.
=head1 HISTORY
B<GeodesicProj> was added to GeographicLib,
L<https://geographiclib.sourceforge.io>, in 2009-08.
Prior to version 1.9 it was called EquidistantTest.

322
libs/geographiclib/man/GeoidEval.pod Normal file
View File

@@ -0,0 +1,322 @@
=head1 NAME
GeoidEval -- look up geoid heights
=head1 SYNOPSIS
B<GeoidEval> [ B<-n> I<name> ] [ B<-d> I<dir> ] [ B<-l> ]
[ B<-a> | B<-c> I<south> I<west> I<north> I<east> ] [ B<-w> ]
[ B<-z> I<zone> ] [ B<--msltohae> ] [ B<--haetomsl> ]
[ B<-v> ]
[ 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
B<GeoidEval> reads in positions on standard input and prints out the
corresponding heights of the geoid model above the WGS84 ellipsoid on
standard output.
Positions are given as latitude and longitude, UTM/UPS, or MGRS, in any
of the formats accepted by GeoConvert(1). (MGRS coordinates signify the
I<center> of the corresponding MGRS square.) If the B<-z> option is
specified then the specified zone is prepended to each line of input
(which must be in UTM/UPS coordinates). This allows a file with UTM
eastings and northings in a single zone to be used as standard input.
More accurate results for the geoid height are provided by Gravity(1).
This utility can also compute the direction of gravity accurately.
The height of the geoid above the ellipsoid, I<N>, is sometimes called
the geoid undulation. It can be used to convert a height above the
ellipsoid, I<h>, to the corresponding height above the geoid (the
orthometric height, roughly the height above mean sea level), I<H>,
using the relations
=over
I<h> = I<N> + I<H>, E<nbsp>E<nbsp>I<H> = -I<N> + I<h>.
=back
=head1 OPTIONS
=over
=item B<-n> I<name>
use I<name> for the geoid model instead of the default C<egm96-5>. See
L</GEOIDS>.
=item B<-d> I<dir>
read geoid data from I<dir> instead of the default. See
L</GEOIDS>.
=item B<-l>
use bilinear interpolation instead of cubic. See
L</INTERPOLATION>.
=item B<-a>
cache the entire data set in memory. See L</CACHE>.
=item B<-c> I<south> I<west> I<north> I<east>
cache the data bounded by I<south> I<west> I<north> I<east> in memory.
The first two arguments specify the SW corner of the cache and the last
two arguments specify the NE corner. The B<-w> flag specifies that
longitude precedes latitude for these corners, provided that it appears
before B<-c>. See L</CACHE>.
=item B<-w>
toggle the longitude first flag (it starts off); if the flag is on, then
when reading geographic coordinates, longitude precedes latitude (this
can be overridden by a hemisphere designator, I<N>, I<S>, I<E>, I<W>).
=item B<-z> I<zone>
prefix each line of input by I<zone>, e.g., C<38n>. This should be used
when the input consists of UTM/UPS eastings and northings.
=item B<--msltohae>
standard input should include a final token on each line which is
treated as a height (in meters) above the geoid and the output echoes
the input line with the height converted to height above ellipsoid
(HAE). If B<-z> I<zone> is specified then the I<third> token is treated
as the height; this makes it possible to convert LIDAR data where each
line consists of: easting northing height intensity.
=item B<--haetomsl>
this is similar to B<--msltohae> except that the height token is treated
as a height (in meters) above the ellipsoid and the output echoes the
input line with the height converted to height above the geoid (MSL).
=item B<-v>
print information about the geoid model on standard error before
processing the input.
=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, the default path and name for geoid models, 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 GEOIDS
B<GeoidEval> computes geoid heights by interpolating on the data in a
regularly spaced table (see L</INTERPOLATION>). The following geoid
grids are available (however, some may not be installed):
bilinear error cubic error
name geoid grid max rms max rms
egm84-30 EGM84 30' 1.546 m 70 mm 0.274 m 14 mm
egm84-15 EGM84 15' 0.413 m 18 mm 0.021 m 1.2 mm
egm96-15 EGM96 15' 1.152 m 40 mm 0.169 m 7.0 mm
egm96-5 EGM96 5' 0.140 m 4.6 mm .0032 m 0.7 mm
egm2008-5 EGM2008 5' 0.478 m 12 mm 0.294 m 4.5 mm
egm2008-2_5 EGM2008 2.5' 0.135 m 3.2 mm 0.031 m 0.8 mm
egm2008-1 EGM2008 1' 0.025 m 0.8 mm .0022 m 0.7 mm
By default, the C<egm96-5> geoid model is used. This may changed by
setting the environment variable C<GEOGRAPHICLIB_GEOID_NAME> or with
the B<-n> option. The errors listed here are estimates of the
quantization and interpolation errors in the reported heights compared
to the specified geoid.
The geoid model data will be loaded from a directory specified at
compile time. This may changed by setting the environment variables
C<GEOGRAPHICLIB_GEOID_PATH> or C<GEOGRAPHICLIB_DATA>, or with the
B<-d> option. The B<-h> option prints the default geoid path and
name. Use the B<-v> option to ascertain the full path name of the
data file.
Instructions for downloading and installing geoid data are available at
L<https://geographiclib.sourceforge.io/C++/doc/geoid.html#geoidinst>.
B<NOTE>: all the geoids above apply to the WGS84 ellipsoid (I<a> =
6378137 m, I<f> = 1/298.257223563) only.
=head1 INTERPOLATION
Cubic interpolation is used to compute the geoid height unless B<-l> is
specified in which case bilinear interpolation is used. The cubic
interpolation is based on a least-squares fit of a cubic polynomial to a
12-point stencil
. 1 1 .
1 2 2 1
1 2 2 1
. 1 1 .
The cubic is constrained to be independent of longitude when evaluating
the height at one of the poles. Cubic interpolation is considerably
more accurate than bilinear; however it results in small discontinuities
in the returned height on cell boundaries.
=head1 CACHE
By default, the data file is randomly read to compute the geoid heights
at the input positions. Usually this is sufficient for interactive use.
If many heights are to be computed, use B<-c> I<south> I<west> I<north>
I<east> to notify B<GeoidEval> to read a rectangle of data into memory;
heights within the this rectangle can then be computed without any disk
access. If B<-a> is specified all the geoid data is read; in the case
of C<egm2008-1>, this requires about 0.5 GB of RAM. The evaluation of
heights outside the cached area causes the necessary data to be read
from disk. Use the B<-v> option to verify the size of the cache.
Regardless of whether any cache is requested (with the B<-a> or B<-c>
options), the data for the last grid cell in cached. This allows
the geoid height along a continuous path to be returned with little
disk overhead.
=head1 ENVIRONMENT
=over
=item B<GEOGRAPHICLIB_GEOID_NAME>
Override the compile-time default geoid name of C<egm96-5>. The B<-h>
option reports the value of B<GEOGRAPHICLIB_GEOID_NAME>, if defined,
otherwise it reports the compile-time value. If the B<-n> I<name>
option is used, then I<name> takes precedence.
=item B<GEOGRAPHICLIB_GEOID_PATH>
Override the compile-time default geoid path. This is typically
C</usr/local/share/GeographicLib/geoids> on Unix-like systems and
C<C:/ProgramData/GeographicLib/geoids> on Windows systems. The B<-h>
option reports the value of B<GEOGRAPHICLIB_GEOID_PATH>, if defined,
otherwise it reports the compile-time value. If the B<-d> I<dir> option
is used, then I<dir> takes precedence.
=item B<GEOGRAPHICLIB_DATA>
Another way of overriding the compile-time default geoid path. If it
is set (and if B<GEOGRAPHICLIB_GEOID_PATH> is not set), then
$B<GEOGRAPHICLIB_DATA>/geoids is used.
=back
=head1 ERRORS
An illegal line of input will print an error message to standard output
beginning with C<ERROR:> and causes B<GeoidEval> to return an exit code
of 1. However, an error does not cause B<GeoidEval> to terminate;
following lines will be converted.
=head1 ABBREVIATIONS
The geoid is usually approximated by an "earth gravity model". The
models published by the NGA are:
=over
=item B<EGM84>
An earth gravity model published by the NGA in 1984,
L<https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm84>.
=item B<EGM96>
An earth gravity model published by the NGA in 1996,
L<https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm96>.
=item B<EGM2008>
An earth gravity model published by the NGA in 2008,
L<https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm2008>.
=item B<WGS84>
World Geodetic System 1984,
L<https://en.wikipedia.org/wiki/WGS84>.
=item B<HAE>
Height above the WGS84 ellipsoid.
=item B<MSL>
Mean sea level, used as a convenient short hand for the geoid.
(However, typically, the geoid differs by a few meters from mean sea
level.)
=back
=head1 EXAMPLES
The height of the EGM96 geoid at Timbuktu
echo 16:46:33N 3:00:34W | GeoidEval
=> 28.7068 -0.02e-6 -1.73e-6
The first number returned is the height of the geoid and the 2nd and 3rd
are its slopes in the northerly and easterly directions.
Convert a point in UTM zone 18n from MSL to HAE
echo 531595 4468135 23 | GeoidEval --msltohae -z 18n
=> 531595 4468135 -10.842
=head1 SEE ALSO
GeoConvert(1), Gravity(1), geographiclib-get-geoids(8).
An online version of this utility is availbable at
L<https://geographiclib.sourceforge.io/cgi-bin/GeoidEval>.
=head1 AUTHOR
B<GeoidEval> was written by Charles Karney.
=head1 HISTORY
B<GeoidEval> was added to GeographicLib,
L<https://geographiclib.sourceforge.io>, in 2009-09.

250
libs/geographiclib/man/Gravity.pod Normal file
View File

@@ -0,0 +1,250 @@
=head1 NAME
Gravity -- compute the earth's gravity field
=head1 SYNOPSIS
B<Gravity> [ B<-n> I<name> ] [ B<-d> I<dir> ]
[ B<-N> I<Nmax> ] [ B<-M> I<Mmax> ]
[ B<-G> | B<-D> | B<-A> | B<-H> ] [ B<-c> I<lat> I<h> ]
[ B<-w> ] [ B<-p> I<prec> ]
[ B<-v> ]
[ 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
B<Gravity> reads in positions on standard input and prints out the
gravitational field on standard output.
The input line is of the form I<lat> I<lon> I<h>. I<lat> and I<lon> are
the latitude and longitude expressed as decimal degrees or degrees,
minutes, and seconds; for details on the allowed formats for latitude
and longitude, see the C<GEOGRAPHIC COORDINATES> section of
GeoConvert(1). I<h> is the height above the ellipsoid in meters; this
quantity is optional and defaults to 0. Alternatively, the gravity
field can be computed at various points on a circle of latitude
(constant I<lat> and I<h>) via the B<-c> option; in this case only the
longitude should be given on the input lines. The quantities printed
out are governed by the B<-G> (default), B<-D>, B<-A>, or B<-H> options.
All the supported gravity models, except for grs80, use WGS84 as the
reference ellipsoid I<a> = 6378137 m, I<f> = 1/298.257223563, I<omega> =
7292115e-11 rad/s, and I<GM> = 3986004.418e8 m^3/s^2.
=head1 OPTIONS
=over
=item B<-n> I<name>
use gravity field model I<name> instead of the default C<egm96>. See
L</MODELS>.
=item B<-d> I<dir>
read gravity models from I<dir> instead of the default. See
L</MODELS>.
=item B<-N> I<Nmax>
limit the degree of the model to I<Nmax>.
=item B<-M> I<Mmax>
limit the order of the model to I<Mmax>.
=item B<-G>
compute the acceleration due to gravity (including the centrifugal
acceleration due the the earth's rotation) B<g>. The output consists of
I<gx> I<gy> I<gz> (all in m/s^2), where the I<x>, I<y>, and I<z>
components are in easterly, northerly, and up directions, respectively.
Usually I<gz> is negative.
=item B<-D>
compute the gravity disturbance B<delta> = B<g> - B<gamma>, where
B<gamma> is the "normal" gravity due to the reference ellipsoid . The
output consists of I<deltax> I<deltay> I<deltaz> (all in mGal, 1 mGal =
10^-5 m/s^2), where the I<x>, I<y>, and I<z> components are in easterly,
northerly, and up directions, respectively. Note that I<deltax> =
I<gx>, because I<gammax> = 0.
=item B<-A>
computes the gravitational anomaly. The output consists of 3 items
I<Dg01> I<xi> I<eta>, where I<Dg01> is in mGal (1 mGal = 10^-5 m/s^2)
and I<xi> and I<eta> are in arcseconds. The gravitational anomaly
compares the gravitational field B<g> at I<P> with the normal gravity
B<gamma> at I<Q> where the I<P> is vertically above I<Q> and the
gravitational potential at I<P> equals the normal potential at I<Q>.
I<Dg01> gives the difference in the magnitudes of these two vectors and
I<xi> and I<eta> give the difference in their directions (as northerly
and easterly components). The calculation uses a spherical
approximation to match the results of the NGA's synthesis programs.
=item B<-H>
compute the height of the geoid above the reference ellipsoid (in
meters). In this case, I<h> should be zero. The results accurately
match the results of the NGA's synthesis programs. GeoidEval(1) can
compute geoid heights much more quickly by interpolating on a grid of
precomputed results; however the results from GeoidEval(1) are only
accurate to a few millimeters.
=item B<-c> I<lat> I<h>
evaluate the field on a circle of latitude given by I<lat> and I<h>
instead of reading these quantities from the input lines. In this case,
B<Gravity> can calculate the field considerably more quickly. If geoid
heights are being computed (the B<-H> option), then I<h> must be zero.
=item B<-w>
toggle the longitude first flag (it starts off); if the flag is on, then
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>. By default I<prec> is 5 for
acceleration due to gravity, 3 for the gravity disturbance and anomaly,
and 4 for the geoid height.
=item B<-v>
print information about the gravity model on standard error before
processing the input.
=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, the default gravity path and name, 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 MODELS
B<Gravity> computes the gravity field using one of the following models
egm84, earth gravity model 1984. See
https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm84
egm96, earth gravity model 1996. See
https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm96
egm2008, earth gravity model 2008. See
https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm2008
wgs84, world geodetic system 1984. This returns the normal
gravity for the WGS84 ellipsoid.
grs80, geodetic reference system 1980. This returns the normal
gravity for the GRS80 ellipsoid.
These models approximate the gravitation field above the surface of the
earth. By default, the C<egm96> gravity model is used. This may
changed by setting the environment variable
C<GEOGRAPHICLIB_GRAVITY_NAME> or with the B<-n> option.
The gravity models will be loaded from a directory specified at compile
time. This may changed by setting the environment variables
C<GEOGRAPHICLIB_GRAVITY_PATH> or C<GEOGRAPHICLIB_DATA>, or with the
B<-d> option. The B<-h> option prints the default gravity path and
name. Use the B<-v> option to ascertain the full path name of the data
file.
Instructions for downloading and installing gravity models are available
at L<https://geographiclib.sourceforge.io/C++/doc/gravity.html#gravityinst>.
=head1 ENVIRONMENT
=over
=item B<GEOGRAPHICLIB_GRAVITY_NAME>
Override the compile-time default gravity name of C<egm96>. The B<-h>
option reports the value of B<GEOGRAPHICLIB_GRAVITY_NAME>, if defined,
otherwise it reports the compile-time value. If the B<-n> I<name>
option is used, then I<name> takes precedence.
=item B<GEOGRAPHICLIB_GRAVITY_PATH>
Override the compile-time default gravity path. This is typically
C</usr/local/share/GeographicLib/gravity> on Unix-like systems and
C<C:/ProgramData/GeographicLib/gravity> on Windows systems. The B<-h>
option reports the value of B<GEOGRAPHICLIB_GRAVITY_PATH>, if defined,
otherwise it reports the compile-time value. If the B<-d> I<dir> option
is used, then I<dir> takes precedence.
=item B<GEOGRAPHICLIB_DATA>
Another way of overriding the compile-time default gravity path. If it
is set (and if B<GEOGRAPHICLIB_GRAVITY_PATH> is not set), then
$B<GEOGRAPHICLIB_DATA>/gravity is used.
=back
=head1 ERRORS
An illegal line of input will print an error message to standard output
beginning with C<ERROR:> and causes B<Gravity> to return an exit
code of 1. However, an error does not cause B<Gravity> to
terminate; following lines will be converted.
=head1 EXAMPLES
The gravity field from EGM2008 at the top of Mount Everest
echo 27:59:17N 86:55:32E 8820 | Gravity -n egm2008
=> -0.00001 0.00103 -9.76782
=head1 SEE ALSO
GeoConvert(1), GeoidEval(1), geographiclib-get-gravity(8).
=head1 AUTHOR
B<Gravity> was written by Charles Karney.
=head1 HISTORY
B<Gravity> was added to GeographicLib, L<https://geographiclib.sourceforge.io>,
in version 1.16.

282
libs/geographiclib/man/MagneticField.pod Normal file
View File

@@ -0,0 +1,282 @@
=head1 NAME
MagneticField -- compute the earth's magnetic field
=head1 SYNOPSIS
B<MagneticField> [ B<-n> I<name> ] [ B<-d> I<dir> ]
[ B<-N> I<Nmax> ] [ B<-M> I<Mmax> ]
[ B<-t> I<time> | B<-c> I<time> I<lat> I<h> ]
[ B<-r> ] [ B<-w> ] [ B<-T> I<tguard> ] [ B<-H> I<hguard> ] [ B<-p> I<prec> ]
[ B<-v> ]
[ 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
B<MagneticField> reads in times and positions on standard input and
prints out the geomagnetic field on standard output and, optionally, its
rate of change.
The input line is of the form I<time> I<lat> I<lon> I<h>. I<time> is a
date of the form 2012-11-25 (yyyy-mm-dd or yyyy-mm), a fractional year
such as 2012.9, or the string "now". I<lat> and I<lon> are the
latitude and longitude expressed as decimal degrees or degrees,
minutes, and seconds; for details on the allowed formats for latitude
and longitude, see the C<GEOGRAPHIC COORDINATES> section of
GeoConvert(1). I<h> is the height above the ellipsoid in meters; this
is optional and defaults to zero. Alternatively, I<time> can be given
on the command line as the argument to the B<-t> option, in which case
it should not be included on the input lines. Finally, the magnetic
field can be computed at various points on a circle of latitude
(constant I<time>, I<lat>, and I<h>) via the B<-c> option; in this
case only the longitude should be given on the input lines.
The output consists of the following 7 items:
the declination (the direction of the horizontal component of
the magnetic field measured clockwise from north) in degrees,
the inclination (the direction of the magnetic field measured
down from the horizontal) in degrees,
the horizontal field in nanotesla (nT),
the north component of the field in nT,
the east component of the field in nT,
the vertical component of the field in nT (down is positive),
the total field in nT.
If the B<-r> option is given, a second line is printed giving the rates
of change of these quantities in degrees/yr and nT/yr.
The WGS84 ellipsoid is used, I<a> = 6378137 m, I<f> = 1/298.257223563.
=head1 OPTIONS
=over
=item B<-n> I<name>
use magnetic field model I<name> instead of the default C<wmm2020>. See
L</MODELS>.
=item B<-d> I<dir>
read magnetic models from I<dir> instead of the default. See
L</MODELS>.
=item B<-N> I<Nmax>
limit the degree of the model to I<Nmax>.
=item B<-M> I<Mmax>
limit the order of the model to I<Mmax>.
=item B<-t> I<time>
evaluate the field at I<time> instead of reading the time from the input
lines.
=item B<-c> I<time> I<lat> I<h>
evaluate the field on a circle of latitude given by I<time>, I<lat>,
I<h> instead of reading these quantities from the input lines. In this
case, B<MagneticField> can calculate the field considerably more
quickly.
=item B<-r>
toggle whether to report the rates of change of the field.
=item B<-w>
toggle the longitude first flag (it starts off); if the flag is on, then
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<-T> I<tguard>
signal an error if I<time> lies I<tguard> years (default 50 yr) beyond
the range for the model.
=item B<-H> I<hguard>
signal an error if I<h> lies I<hguard> meters (default 500000 m) beyond
the range for the model.
=item B<-p> I<prec>
set the output precision to I<prec> (default 1). Fields are printed
with precision with I<prec> decimal places; angles use I<prec> + 1
places.
=item B<-v>
print information about the magnetic model on standard error before
processing the input.
=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, the default magnetic path and name, 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 MODELS
B<MagneticField> computes the geomagnetic field using one of the
following models
wmm2010, the World Magnetic Model 2010, which approximates the
main magnetic field for the period 2010-2015. See
https://ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml
wmm2015v2, the World Magnetic Model 2015, which approximates the
main magnetic field for the period 2015-2020. See
https://ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml
wmm2015, a deprecated version of wmm2015v2
wmm2020, the World Magnetic Model 2020, which approximates the
main magnetic field for the period 2020-2025. See
https://ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml
igrf11, the International Geomagnetic Reference Field (11th
generation), which approximates the main magnetic field for
the period 1900-2015. See
https://ngdc.noaa.gov/IAGA/vmod/igrf.html
igrf12, the International Geomagnetic Reference Field (12th
generation), which approximates the main magnetic field for
the period 1900-2020. See
https://ngdc.noaa.gov/IAGA/vmod/igrf.html
igrf13, the International Geomagnetic Reference Field (13th
generation), which approximates the main magnetic field for
the period 1900-2025. See
https://ngdc.noaa.gov/IAGA/vmod/igrf.html
emm2010, the Enhanced Magnetic Model 2010, which approximates
the main and crustal magnetic fields for the period 2010-2015.
See https://ngdc.noaa.gov/geomag/EMM/index.html
emm2015, the Enhanced Magnetic Model 2015, which approximates
the main and crustal magnetic fields for the period 2000-2020.
See https://ngdc.noaa.gov/geomag/EMM/index.html
emm2017, the Enhanced Magnetic Model 2017, which approximates
the main and crustal magnetic fields for the period 2000-2022.
See https://ngdc.noaa.gov/geomag/EMM/index.html
These models approximate the magnetic field due to the earth's core and
(in the case of emm20xx) its crust. They neglect magnetic fields due to
the ionosphere, the magnetosphere, nearby magnetized materials,
electrical machinery, etc.
By default, the C<wmm2020> magnetic model is used. This may changed by
setting the environment variable C<GEOGRAPHICLIB_MAGNETIC_NAME> or with
the B<-n> option.
The magnetic models will be loaded from a directory specified at compile
time. This may changed by setting the environment variables
C<GEOGRAPHICLIB_MAGNETIC_PATH> or C<GEOGRAPHICLIB_DATA>, or with the
B<-d> option. The B<-h> option prints the default magnetic path and
name. Use the B<-v> option to ascertain the full path name of the data
file.
Instructions for downloading and installing magnetic models are
available at
L<https://geographiclib.sourceforge.io/C++/doc/magnetic.html#magneticinst>.
=head1 ENVIRONMENT
=over
=item B<GEOGRAPHICLIB_MAGNETIC_NAME>
Override the compile-time default magnetic name of C<wmm2020>. The
B<-h> option reports the value of B<GEOGRAPHICLIB_MAGNETIC_NAME>, if
defined, otherwise it reports the compile-time value. If the B<-n>
I<name> option is used, then I<name> takes precedence.
=item B<GEOGRAPHICLIB_MAGNETIC_PATH>
Override the compile-time default magnetic path. This is typically
C</usr/local/share/GeographicLib/magnetic> on Unix-like systems and
C<C:/ProgramData/GeographicLib/magnetic> on Windows systems. The B<-h>
option reports the value of B<GEOGRAPHICLIB_MAGNETIC_PATH>, if defined,
otherwise it reports the compile-time value. If the B<-d> I<dir> option
is used, then I<dir> takes precedence.
=item B<GEOGRAPHICLIB_DATA>
Another way of overriding the compile-time default magnetic path. If it
is set (and if B<GEOGRAPHICLIB_MAGNETIC_PATH> is not set), then
$B<GEOGRAPHICLIB_DATA>/magnetic is used.
=back
=head1 ERRORS
An illegal line of input will print an error message to standard output
beginning with C<ERROR:> and causes B<MagneticField> to return an exit
code of 1. However, an error does not cause B<MagneticField> to
terminate; following lines will be converted. If I<time> or I<h> are
outside the recommended ranges for the model (but inside the ranges
increase by I<tguard> and I<hguard>), a warning is printed on standard
error and the field (which may be inaccurate) is returned in the normal
way.
=head1 EXAMPLES
The magnetic field from WMM2020 in Timbuktu on 2020-12-25
echo 2020-12-25 16:46:33N 3:00:34W 300 | MagneticField -r
=> -1.47 11.98 33994.9 33983.7 -871.7 7214.7 34752.1
0.13 -0.02 21.9 23.9 77.9 -8.4 19.7
The first two numbers returned are the declination and inclination of
the field. The second line gives the annual change.
=head1 SEE ALSO
GeoConvert(1), geographiclib-get-magnetic(8).
=head1 AUTHOR
B<MagneticField> was written by Charles Karney.
=head1 HISTORY
B<MagneticField> was added to GeographicLib,
L<https://geographiclib.sourceforge.io>, in version 1.15.

78
libs/geographiclib/man/Makefile.am Normal file
View File

@@ -0,0 +1,78 @@
#
# Makefile.am
#
# Copyright (C) 2011-2022, Charles Karney <charles@karney.com>
USAGE = \
CartConvert.usage \
ConicProj.usage \
GeodesicProj.usage \
GeoConvert.usage \
GeodSolve.usage \
GeoidEval.usage \
Gravity.usage \
MagneticField.usage \
Planimeter.usage \
RhumbSolve.usage \
TransverseMercatorProj.usage
MANPAGES = \
CartConvert.1 \
ConicProj.1 \
GeodesicProj.1 \
GeoConvert.1 \
GeodSolve.1 \
GeoidEval.1 \
Gravity.1 \
MagneticField.1 \
Planimeter.1 \
RhumbSolve.1 \
TransverseMercatorProj.1
HTMLMAN = \
CartConvert.1.html \
ConicProj.1.html \
GeodesicProj.1.html \
GeoConvert.1.html \
GeodSolve.1.html \
GeoidEval.1.html \
Gravity.1.html \
MagneticField.1.html \
Planimeter.1.html \
RhumbSolve.1.html \
TransverseMercatorProj.1.html
SYSMANPAGES = geographiclib-get-geoids.8 \
geographiclib-get-gravity.8 \
geographiclib-get-magnetic.8
man1_MANS = $(MANPAGES)
man8_MANS = $(SYSMANPAGES)
SUFFIXES = .1 .usage .1.html .8
all: man
man: manpages usage htmlman sysmanpages
manpages: $(MANPAGES)
usage: $(USAGE)
htmlman: $(HTMLMAN)
sysmanpages: $(SYSMANPAGES)
geographiclib_data = $(datadir)/GeographicLib
SCRIPTMANCMD = sed -e "s/@SCRIPT@/$*/g" \
-e "s/@DATA@/`echo $* | cut -f3 -d-`/g" \
-e "s%@GEOGRAPHICLIB_DATA@%$(geographiclib_data)%g" \
$(srcdir)/script.8.in > $@
geographiclib-get-geoids.8:
$(SCRIPTMANCMD)
geographiclib-get-gravity.8:
$(SCRIPTMANCMD)
geographiclib-get-magnetic.8:
$(SCRIPTMANCMD)
EXTRA_DIST = CMakeLists.txt $(MANPAGES) $(USAGE) $(HTMLMAN) script.8.in
maintainer-clean-local:
rm -rf *.8

248
libs/geographiclib/man/Planimeter.pod Normal file
View File

@@ -0,0 +1,248 @@
=head1 NAME
Planimeter -- compute the area of geodesic polygons
=head1 SYNOPSIS
B<Planimeter> [ B<-r> ] [ B<-s> ] [ B<-l> ] [ B<-e> I<a> I<f> ]
[ B<-w> ] [ B<-p> I<prec> ] [ B<-G> | B<-E> | B<-Q> | B<-R> ]
[ B<--geoconvert-input> ]
[ 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
Measure the area of a geodesic polygon. Reads polygon vertices from
standard input, one per line. Vertices are be given as latitude and
longitude. By default latitude precedes longitude, however this
convention is reversed with the B<-w> flag and a hemisphere designator
(I<N>, I<S>, I<E>, I<W>) can be used to disambiguate the coordinates.
The end of input, a blank line, or a line which can't be interpreted
as a vertex signals the end of one polygon and the start of the next.
For each polygon print a summary line with the number of points, the
perimeter (in meters), and the area (in meters^2).
The edges of the polygon are given by the I<shortest> geodesic (or
rhumb line) between consecutive vertices. In certain cases, there may
be two or many such shortest path, and in that case, the polygon is
not uniquely specified by its vertices. For geodesics, this only
happens with very long edges (for the WGS84 ellipsoid, any edge
shorter than 19970 km is uniquely specified by its end points). In
such cases, insert an additional vertex near the middle of the long
edge to define the boundary of the polygon.
By default, polygons traversed in a counter-clockwise direction return a
positive area and those traversed in a clockwise direction return a
negative area. This sign convention is reversed if the B<-r> option is
given.
Of course, encircling an area in the clockwise direction is equivalent
to encircling the rest of the ellipsoid in the counter-clockwise
direction. The default interpretation used by B<Planimeter> is the one
that results in a smaller magnitude of area; i.e., the magnitude of the
area is less than or equal to one half the total area of the ellipsoid.
If the B<-s> option is given, then the interpretation used is the one
that results in a positive area; i.e., the area is positive and less
than the total area of the ellipsoid.
Arbitrarily complex polygons are allowed. In the case of
self-intersecting polygons the area is accumulated "algebraically",
e.g., the areas of the 2 loops in a figure-8 polygon will partially
cancel. Polygons may include one or both poles. There is no need to
close the polygon.
=head1 OPTIONS
=over
=item B<-r>
toggle whether counter-clockwise traversal of the polygon returns a
positive (the default) or negative result.
=item B<-s>
toggle whether to return a signed result (the default) or not.
=item B<-l>
toggle whether the vertices represent a polygon (the default) or a
polyline. For a polyline, the number of points and the length of the
path joining them is returned; the path is not closed and the area is
not reported.
=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. If entering vertices as UTM/UPS or
MGRS coordinates, use the default ellipsoid, since the conversion of
these coordinates to latitude and longitude always uses the WGS84
parameters.
=item B<-w>
toggle the longitude first flag (it starts off); if the flag is on, then
when reading geographic coordinates, longitude precedes latitude (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 6); the perimeter is given
(in meters) with I<prec> digits after the decimal point; the area is
given (in meters^2) with (I<prec> - 5) digits after the decimal point.
=item B<-G>
use the series formulation for the geodesics. This is the default
option and is recommended for terrestrial applications. This option,
B<-G>, and the following three options, B<-E>, B<-Q>, and B<-R>, are
mutually exclusive.
=item B<-E>
use "exact" algorithms (based on elliptic integrals) for the geodesic
calculations; the area is computed by applying discrete sine
transforms to the integrand in the expression for the area. These are
more accurate, albeit slower, than the (default) series expansions for
|I<f>| E<gt> 0.02 and will give high accuracy for -99 E<le> I<f> E<le>
0.99.
=item B<-Q>
perform the calculation on the authalic sphere. The area calculation is
accurate even if the flattening is large, I<provided> the edges are
sufficiently short. The perimeter calculation is not accurate.
=item B<-R>
The lines joining the vertices are rhumb lines instead of geodesics.
=item B<--geoconvert-input>
The input lines are interpreted in the same way as GeoConvert(1)
allowing the coordinates for the vertices to be given as UTM/UPS or
MGRS coordinates, as well as latitude and longitude. B<CAUTION>:
GeoConvert assumes the coordinates refer to the WGS84 ellipsoid
(disregarding the B<-e> flag) and MGRS coordinates signify the center
of the corresponding MGRS square.
=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. For a given polygon, the last such string found will be
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 EXAMPLES
Example (the area of the 100km MGRS square 18SWK)
Planimeter --geoconvert-input <<EOF
18n 500000 4400000
18n 600000 4400000
18n 600000 4500000
18n 500000 4500000
EOF
=> 4 400139.532959 10007388597.2
The following code takes the output from gdalinfo and reports the area
covered by the data (assuming the edges of the image are geodesics).
#! /bin/sh
egrep '^((Upper|Lower) (Left|Right)|Center) ' |
sed -e 's/d /d/g' -e "s/' /'/g" | tr -s '(),\r\t' ' ' | awk '{
if ($1 $2 == "UpperLeft")
ul = $6 " " $5;
else if ($1 $2 == "LowerLeft")
ll = $6 " " $5;
else if ($1 $2 == "UpperRight")
ur = $6 " " $5;
else if ($1 $2 == "LowerRight")
lr = $6 " " $5;
else if ($1 == "Center") {
printf "%s\n%s\n%s\n%s\n\n", ul, ll, lr, ur;
ul = ll = ur = lr = "";
}
}
' | Planimeter | cut -f3 -d' '
=head1 ACCURACY
Using the B<-G> option (the default), the accuracy was estimated by
computing the error in the area for 10^7 approximately regular
polygons on the WGS84 ellipsoid. The centers and the orientations of
the polygons were uniformly distributed, the number of vertices was
log-uniformly distributed in [3, 300], and the center to vertex
distance log-uniformly distributed in [0.1 m, 9000 km].
The maximum error in the perimeter was 200 nm, and the maximum error
in the area was
0.0013 m^2 for perimeter < 10 km
0.0070 m^2 for perimeter < 100 km
0.070 m^2 for perimeter < 1000 km
0.11 m^2 for all perimeters
=head1 SEE ALSO
GeoConvert(1), GeodSolve(1).
An online version of this utility is availbable at
L<https://geographiclib.sourceforge.io/cgi-bin/Planimeter>.
The algorithm for the area of geodesic polygon is
given in Section 6 of C. F. F. Karney, I<Algorithms for geodesics>,
J. Geodesy 87, 43-55 (2013);
DOI L<https://doi.org/10.1007/s00190-012-0578-z>;
addenda: L<https://geographiclib.sourceforge.io/geod-addenda.html>.
=head1 AUTHOR
B<Planimeter> was written by Charles Karney.
=head1 HISTORY
B<Planimeter> was added to GeographicLib,
L<https://geographiclib.sourceforge.io>, in version 1.4.

253
libs/geographiclib/man/RhumbSolve.pod Normal file
View File

@@ -0,0 +1,253 @@
=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.

173
libs/geographiclib/man/TransverseMercatorProj.pod Normal file
View File

@@ -0,0 +1,173 @@
=head1 NAME
TransverseMercatorProj -- perform transverse Mercator projection
=head1 SYNOPSIS
B<TransverseMercatorProj> [ B<-s> | B<-t> ]
[ B<-l> I<lon0> ] [ B<-k> I<k0> ] [ B<-r> ]
[ B<-e> I<a> I<f> ] [ B<-w> ] [ B<-p> I<prec> ]
[ 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
Perform the transverse Mercator projections. Convert geodetic
coordinates to transverse Mercator coordinates. The central meridian is
given by I<lon0>. The longitude of origin is the equator. The scale on
the central meridian is I<k0>. By default an implementation of the
exact transverse Mercator projection is used.
Geodetic coordinates are provided on standard input as a set of lines
containing (blank separated) I<latitude> and I<longitude> (decimal
degrees or degrees, minutes, seconds); for detils on the allowed
formats for latitude and longitude, see the C<GEOGRAPHIC COORDINATES>
section of GeoConvert(1). For each set of geodetic coordinates, the
corresponding projected easting, I<x>, and northing, I<y>, (meters) are
printed on standard output together with the meridian convergence
I<gamma> (degrees) and scale I<k>. The meridian convergence is the
bearing of grid north (the I<y> axis) measured clockwise from true north.
=head1 OPTIONS
=over
=item B<-s>
use the sixth-order Krueger series approximation to the transverse
Mercator projection instead of the exact projection.
=item B<-t>
use the exact algorithm with the L</EXTENDED DOMAIN>; this is the
default.
=item B<-l> I<lon0>
specify the longitude of origin I<lon0> (degrees, default 0).
=item B<-k> I<k0>
specify the scale I<k0> on the central meridian (default 0.9996).
=item B<-r>
perform the reverse projection. I<x> and I<y> are given on standard
input and each line of standard output gives I<latitude>, I<longitude>,
I<gamma>, and I<k>.
=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. If the exact algorithm is used, I<f>
must be positive.
=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 6). I<prec> is the number
of digits after the decimal point for lengths (in meters). For
latitudes and longitudes (in degrees), the number of digits after the
decimal point is I<prec> + 5. For the convergence (in degrees) and
scale, the number of digits after the decimal point is I<prec> + 6.
=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 EXTENDED DOMAIN
The exact transverse Mercator projection has a I<branch point> on the
equator at longitudes (relative to I<lon0>) of +/- (1 - I<e>) 90 =
82.636..., where I<e> is the eccentricity of the ellipsoid. The
standard convention for handling this branch point is to map positive
(negative) latitudes into positive (negative) northings I<y>; i.e., a
branch cut is placed on the equator. With the I<extended> domain, the
northern sheet of the projection is extended into the south hemisphere
by pushing the branch cut south from the branch points. See the
reference below for details.
=head1 EXAMPLES
echo 0 90 | TransverseMercatorProj
=> 25953592.84 9997964.94 90 18.40
echo 260e5 100e5 | TransverseMercatorProj -r
=> -0.02 90.00 90.01 18.48
=head1 ERRORS
An illegal line of input will print an error message to standard output
beginning with C<ERROR:> and causes B<TransverseMercatorProj> to return an exit
code of 1. However, an error does not cause B<TransverseMercatorProj> to
terminate; following lines will be converted.
=head1 AUTHOR
B<TransverseMercatorProj> was written by Charles Karney.
=head1 SEE ALSO
The algorithms for the transverse Mercator projection are described in
C. F. F. Karney, I<Transverse Mercator with an accuracy of a few
nanometers>, J. Geodesy B<85>(8), 475-485 (Aug. 2011); DOI
L<https://doi.org/10.1007/s00190-011-0445-3>; preprint
L<https://arxiv.org/abs/1002.1417>. The explanation of the extended
domain of the projection with the B<-t> option is given in Section 5 of
this paper.
=head1 HISTORY
B<TransverseMercatorProj> was added to GeographicLib,
L<https://geographiclib.sourceforge.io>, in 2009-01.
Prior to version 1.9 it was called TransverseMercatorTest (and its
interface was slightly different).

23
libs/geographiclib/man/dummy.1.html.in Normal file
View File

@@ -0,0 +1,23 @@
<html>
<head>
<title>@TOOL@ -- a GeographicLib utility</title>
<meta HTTP-EQUIV="Refresh"
CONTENT="0; URL=https://geographiclib.sourceforge.io/C++/@PROJECT_VERSION@/@TOOL@.1.html">
</head>
<body topmargin=10 leftmargin=10>
<h3>
<blockquote>
<em>
Online documentation for the @TOOL@ utility is available at
<center>
<a href="https://geographiclib.sourceforge.io/C++/@PROJECT_VERSION@/@TOOL@.1.html">
https://geographiclib.sourceforge.io/C++/@PROJECT_VERSION@/@TOOL@.1.html</a>.
</center>
<br>
You will be redirected there. Click on the link to go there
directly.
</em>
</blockquote>
</h3>
</body>
</html>

9
libs/geographiclib/man/dummy.1.in Normal file
View File

@@ -0,0 +1,9 @@
.TH @TOOL@ 1 "" "GeographicLib Utilities" "GeographicLib Utilities"
.SH NAME
@TOOL@ \-\- a GeographicLib utility
.SH DESCRIPTION
.B @TOOL@
is part of GeographicLib, <https://geographiclib.sourceforge.io>. For
documentation, see
.PP
https://geographiclib.sourceforge.io/C++/@PROJECT_VERSION@/@TOOL@.1.html

8
libs/geographiclib/man/dummy.usage.in Normal file
View File

@@ -0,0 +1,8 @@
// Dummy usage file to be used when the man page isn't available
int usage(int retval, bool /* brief */) {
( retval ? std::cerr : std::cout )
<< "For full documentation on @TOOL@, see\n"
<< " https://geographiclib.sourceforge.io/C++/@PROJECT_VERSION@/@TOOL@.1.html\n";
return retval;
}

37
libs/geographiclib/man/makeusage.sh Normal file
View File

@@ -0,0 +1,37 @@
#! /bin/sh
# Convert a pod file into a usage function for the GeographicLib utilities.
SOURCE=$1
NAME=`basename $SOURCE .pod`
VERSION=$2
(
cat<<EOF
int usage(int retval, bool brief) {
if (brief)
( retval ? std::cerr : std::cout ) << "Usage:\n\\
EOF
$POD2MAN $SOURCE | nroff -c -man 2>/dev/null | $COL -b -x |
sed -e 1,/SYNOPSIS/d -e '/^$/,$d' -e 's/ / /g' -e 's/$/\\n\\/' -e 's/"/\\"/g'
cat <<EOF
\n\\
For full documentation type:\n\\
$NAME --help\n\\
or visit:\n\\
https://geographiclib.sourceforge.io/C++/$VERSION/$NAME.1.html\n";
else
( retval ? std::cerr : std::cout ) << "Man page:\n\\
EOF
$POD2MAN $SOURCE | nroff -c -man 2>/dev/null | $COL -b -x | head --lines -4 |
tail --lines +5 | sed -e 's/\\/\\\\/g' -e 's/$/\\n\\/' -e 's/"/\\"/g'
cat <<EOF
";
return retval;
}
EOF
) | # Break long strings assuming that files don't contain the ~ character
tr '\n' '~' | sed -e's/\\~/"~"/g' -e's/""//g' | tr '~' '\n'

15
libs/geographiclib/man/script.8.in Normal file
View File

@@ -0,0 +1,15 @@
.TH @SCRIPT@ 8 "" GeographicLib GeographicLib
.SH NAME
@SCRIPT@ \-\- a GeographicLib administrative tool
.SH DESCRIPTION
.B @SCRIPT@
downloads and installs the @DATA@ datasets used by GeographicLib,
<https://geographiclib.sourceforge.io>. For documentation, supply the
.B \-h
option:
.PP
@SCRIPT@ \-h
.PP
By default, the datasets are installed in
.I @GEOGRAPHICLIB_DATA@/@DATA@
and the script requires write access to this directory.