ADD: new track message, Entity class and Position class
This commit is contained in:
Henry Winkel
250
libs/geographiclib/man/Gravity.pod
Normal file
250
libs/geographiclib/man/Gravity.pod
Normal 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.
|
||||
Reference in New Issue
Block a user