1GEOIDEVAL(1)                GeographicLib Utilities               GEOIDEVAL(1)
2
3
4

NAME

6       GeoidEval -- look up geoid heights
7

SYNOPSIS

9       GeoidEval [ -n name ] [ -d dir ] [ -l ] [ -a | -c south west north east
10       ] [ -w ] [ -z zone ] [ --msltohae ] [ --haetomsl ] [ -v ] [
11       --comment-delimiter commentdelim ] [ --version | -h | --help ] [
12       --input-file infile | --input-string instring ] [ --line-separator
13       linesep ] [ --output-file outfile ]
14

DESCRIPTION

16       GeoidEval reads in positions on standard input and prints out the
17       corresponding heights of the geoid above the WGS84 ellipsoid on
18       standard output.
19
20       Positions are given as latitude and longitude, UTM/UPS, or MGRS, in any
21       of the formats accepted by GeoConvert(1).  (MGRS coordinates signify
22       the center of the corresponding MGRS square.)  If the -z option is
23       specified then the specified zone is prepended to each line of input
24       (which must be in UTM/UPS coordinates).  This allows a file with UTM
25       eastings and northings in a single zone to be used as standard input.
26
27       More accurate results for the geoid height are provided by Gravity(1).
28       This utility can also compute the direction of gravity accurately.
29
30       The height of the geoid above the ellipsoid, N, is sometimes called the
31       geoid undulation.  It can be used to convert a height above the
32       ellipsoid, h, to the corresponding height above the geoid (the
33       orthometric height, roughly the height above mean sea level), H, using
34       the relations
35
36           h = N + H,   H = -N + h.
37

OPTIONS

39       -n name
40           use geoid name instead of the default "egm96-5".  See "GEOIDS".
41
42       -d dir
43           read geoid data from dir instead of the default.  See "GEOIDS".
44
45       -l  use bilinear interpolation instead of cubic.  See "INTERPOLATION".
46
47       -a  cache the entire data set in memory.  See "CACHE".
48
49       -c south west north east
50           cache the data bounded by south west north east in memory.  The
51           first two arguments specify the SW corner of the cache and the last
52           two arguments specify the NE corner.  The -w flag specifies that
53           longitude precedes latitude for these corners, provided that it
54           appears before -c.  See "CACHE".
55
56       -w  toggle the longitude first flag (it starts off); if the flag is on,
57           then when reading geographic coordinates, longitude precedes
58           latitude (this can be overridden by a hemisphere designator, N, S,
59           E, W).
60
61       -z zone
62           prefix each line of input by zone, e.g., "38n".  This should be
63           used when the input consists of UTM/UPS eastings and northings.
64
65       --msltohae
66           standard input should include a final token on each line which is
67           treated as a height (in meters) above the geoid and the output
68           echoes the input line with the height converted to height above
69           ellipsoid (HAE).  If -z zone is specified then the third token is
70           treated as the height; this makes it possible to convert LIDAR data
71           where each line consists of: easting northing height intensity.
72
73       --haetomsl
74           this is similar to --msltohae except that the height token is
75           treated as a height (in meters) above the ellipsoid and the output
76           echoes the input line with the height converted to height above the
77           geoid (MSL).
78
79       -v  print information about the geoid on standard error before
80           processing the input.
81
82       --comment-delimiter commentdelim
83           set the comment delimiter to commentdelim (e.g., "#" or "//").  If
84           set, the input lines will be scanned for this delimiter and, if
85           found, the delimiter and the rest of the line will be removed prior
86           to processing and subsequently appended to the output line
87           (separated by a space).
88
89       --version
90           print version and exit.
91
92       -h  print usage, the default geoid path and name, and exit.
93
94       --help
95           print full documentation and exit.
96
97       --input-file infile
98           read input from the file infile instead of from standard input; a
99           file name of "-" stands for standard input.
100
101       --input-string instring
102           read input from the string instring instead of from standard input.
103           All occurrences of the line separator character (default is a
104           semicolon) in instring are converted to newlines before the reading
105           begins.
106
107       --line-separator linesep
108           set the line separator character to linesep.  By default this is a
109           semicolon.
110
111       --output-file outfile
112           write output to the file outfile instead of to standard output; a
113           file name of "-" stands for standard output.
114

GEOIDS

116       GeoidEval computes geoid heights by interpolating on the data in a
117       regularly spaced table (see "INTERPOLATION").  The following geoid
118       tables are available (however, some may not be installed):
119
120                                         bilinear error    cubic error
121          name         geoid    grid     max      rms      max      rms
122          egm84-30     EGM84    30'      1.546 m  70 mm    0.274 m  14 mm
123          egm84-15     EGM84    15'      0.413 m  18 mm    0.021 m  1.2 mm
124          egm96-15     EGM96    15'      1.152 m  40 mm    0.169 m  7.0 mm
125          egm96-5      EGM96     5'      0.140 m  4.6 mm   .0032 m  0.7 mm
126          egm2008-5    EGM2008   5'      0.478 m  12 mm    0.294 m  4.5 mm
127          egm2008-2_5  EGM2008   2.5'    0.135 m  3.2 mm   0.031 m  0.8 mm
128          egm2008-1    EGM2008   1'      0.025 m  0.8 mm   .0022 m  0.7 mm
129
130       By default, the "egm96-5" geoid is used.  This may changed by setting
131       the environment variable "GEOGRAPHICLIB_GEOID_NAME" or with the -n
132       option.  The errors listed here are estimates of the quantization and
133       interpolation errors in the reported heights compared to the specified
134       geoid.
135
136       The geoid data will be loaded from a directory specified at compile
137       time.  This may changed by setting the environment variables
138       "GEOGRAPHICLIB_GEOID_PATH" or "GEOGRAPHICLIB_DATA", or with the -d
139       option.  The -h option prints the default geoid path and name.  Use the
140       -v option to ascertain the full path name of the data file.
141
142       Instructions for downloading and installing geoid data are available at
143       <https://geographiclib.sourceforge.io/html/geoid.html#geoidinst>.
144
145       NOTE: all the geoids above apply to the WGS84 ellipsoid (a = 6378137 m,
146       f = 1/298.257223563) only.
147

INTERPOLATION

149       Cubic interpolation is used to compute the geoid height unless -l is
150       specified in which case bilinear interpolation is used.  The cubic
151       interpolation is based on a least-squares fit of a cubic polynomial to
152       a 12-point stencil
153
154          . 1 1 .
155          1 2 2 1
156          1 2 2 1
157          . 1 1 .
158
159       The cubic is constrained to be independent of longitude when evaluating
160       the height at one of the poles.  Cubic interpolation is considerably
161       more accurate than bilinear; however it results in small
162       discontinuities in the returned height on cell boundaries.
163

CACHE

165       By default, the data file is randomly read to compute the geoid heights
166       at the input positions.  Usually this is sufficient for interactive
167       use.  If many heights are to be computed, use -c south west north east
168       to notify GeoidEval to read a rectangle of data into memory; heights
169       within the this rectangle can then be computed without any disk access.
170       If -a is specified all the geoid data is read; in the case of
171       "egm2008-1", this requires about 0.5 GB of RAM.  The evaluation of
172       heights outside the cached area causes the necessary data to be read
173       from disk.  Use the -v option to verify the size of the cache.
174
175       Regardless of whether any cache is requested (with the -a or -c
176       options), the data for the last grid cell in cached.  This allows the
177       geoid height along a continuous path to be returned with little disk
178       overhead.
179

ENVIRONMENT

181       GEOGRAPHICLIB_GEOID_NAME
182           Override the compile-time default geoid name of "egm96-5".  The -h
183           option reports the value of GEOGRAPHICLIB_GEOID_NAME, if defined,
184           otherwise it reports the compile-time value.  If the -n name option
185           is used, then name takes precedence.
186
187       GEOGRAPHICLIB_GEOID_PATH
188           Override the compile-time default geoid path.  This is typically
189           "/usr/local/share/GeographicLib/geoids" on Unix-like systems and
190           "C:/ProgramData/GeographicLib/geoids" on Windows systems.  The -h
191           option reports the value of GEOGRAPHICLIB_GEOID_PATH, if defined,
192           otherwise it reports the compile-time value.  If the -d dir option
193           is used, then dir takes precedence.
194
195       GEOGRAPHICLIB_DATA
196           Another way of overriding the compile-time default geoid path.  If
197           it is set (and if GEOGRAPHICLIB_GEOID_PATH is not set), then
198           $GEOGRAPHICLIB_DATA/geoids is used.
199

ERRORS

201       An illegal line of input will print an error message to standard output
202       beginning with "ERROR:" and causes GeoidEval to return an exit code of
203       1.  However, an error does not cause GeoidEval to terminate; following
204       lines will be converted.
205

ABBREVIATIONS

207       The geoid is usually approximated by an "earth gravity model". The
208       models published by the NGA are:
209
210       EGM84
211           An earth gravity model published by the NGA in 1984,
212           <http://earth-info.nga.mil/GandG/wgs84/gravitymod/wgs84_180/wgs84_180.html>.
213
214       EGM96
215           An earth gravity model published by the NGA in 1996,
216           <http://earth-info.nga.mil/GandG/wgs84/gravitymod/egm96/egm96.html>.
217
218       EGM2008
219           An earth gravity model published by the NGA in 2008,
220           <http://earth-info.nga.mil/GandG/wgs84/gravitymod/egm2008>.
221
222       WGS84
223           World Geodetic System 1984, <https://en.wikipedia.org/wiki/WGS84>.
224
225       HAE Height above the WGS84 ellipsoid.
226
227       MSL Mean sea level, used as a convenient short hand for the geoid.
228           (However, typically, the geoid differs by a few meters from mean
229           sea level.)
230

EXAMPLES

232       The height of the EGM96 geoid at Timbuktu
233
234           echo 16:46:33N 3:00:34W | GeoidEval
235           => 28.7068 -0.02e-6 -1.73e-6
236
237       The first number returned is the height of the geoid and the 2nd and
238       3rd are its slopes in the northerly and easterly directions.
239
240       Convert a point in UTM zone 18n from MSL to HAE
241
242          echo 531595 4468135 23 | GeoidEval --msltohae -z 18n
243          => 531595 4468135 -10.842
244

SEE ALSO

246       GeoConvert(1), Gravity(1), geographiclib-get-geoids(8).
247
248       An online version of this utility is availbable at
249       <https://geographiclib.sourceforge.io/cgi-bin/GeoidEval>.
250

AUTHOR

252       GeoidEval was written by Charles Karney.
253

HISTORY

255       GeoidEval was added to GeographicLib,
256       <https://geographiclib.sourceforge.io>, in 2009-09.
257
258
259
260GeographicLib 1.50.1              2019-12-12                      GEOIDEVAL(1)
Impressum