251 lines
8.5 KiB
Plaintext
251 lines
8.5 KiB
Plaintext
=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.
|