323 lines
10 KiB
Plaintext
323 lines
10 KiB
Plaintext
=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.
|