1GEOIDEVAL(1) GeographicLib Utilities GEOIDEVAL(1)
2
6 GeoidEval -- look up geoid heights
7
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
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 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 More accurate results for the geoid height are provided by Gravity(1).
28 This utility can also compute the direction of gravity accurately.
29 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 h = N + H, H = -N + h.
37
39 -n name
40 use geoid name instead of the default "egm96-5". See "GEOIDS".
41 -d dir
43 read geoid data from dir instead of the default. See "GEOIDS".
44 -l use bilinear interpolation instead of cubic. See "INTERPOLATION".
46 -a cache the entire data set in memory. See "CACHE".
48 -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 -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 -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 --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 --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 -v print information about the geoid on standard error before
80 processing the input.
81 --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 --version
90 print version and exit.
91 -h print usage, the default geoid path and name, and exit.
93 --help
95 print full documentation and exit.
96 --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 --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 --line-separator linesep
108 set the line separator character to linesep. By default this is a
109 semicolon.
110 --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
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 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 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 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 Instructions for downloading and installing geoid data are available at
143 <https://geographiclib.sourceforge.io/html/geoid.html#geoidinst>.
144 NOTE: all the geoids above apply to the WGS84 ellipsoid (a = 6378137 m,
146 f = 1/298.257223563) only.
147
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 . 1 1 .
155 1 2 2 1
156 1 2 2 1
157 . 1 1 .
158 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
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 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
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 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 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
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
207 The geoid is usually approximated by an "earth gravity model". The
208 models published by the NGA are:
209 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 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 EGM2008
219 An earth gravity model published by the NGA in 2008,
220 <http://earth-info.nga.mil/GandG/wgs84/gravitymod/egm2008>.
221 WGS84
223 World Geodetic System 1984, <https://en.wikipedia.org/wiki/WGS84>.
224 HAE Height above the WGS84 ellipsoid.
226 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
232 The height of the EGM96 geoid at Timbuktu
233 echo 16:46:33N 3:00:34W | GeoidEval
235 => 28.7068 -0.02e-6 -1.73e-6
236 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 Convert a point in UTM zone 18n from MSL to HAE
241 echo 531595 4468135 23 | GeoidEval --msltohae -z 18n
243 => 531595 4468135 -10.842
244
246 GeoConvert(1), Gravity(1), geographiclib-get-geoids(8).
247 An online version of this utility is availbable at
249 <https://geographiclib.sourceforge.io/cgi-bin/GeoidEval>.
250
252 GeoidEval was written by Charles Karney.
253
255 GeoidEval was added to GeographicLib,
256 <https://geographiclib.sourceforge.io>, in 2009-09.
257GeographicLib 1.50.1 2019-12-12 GEOIDEVAL(1)