1=head1 NAME 2 3GeoidEval -- look up geoid heights 4 5=head1 SYNOPSIS 6 7B<GeoidEval> [ B<-n> I<name> ] [ B<-d> I<dir> ] [ B<-l> ] 8[ B<-a> | B<-c> I<south> I<west> I<north> I<east> ] [ B<-w> ] 9[ B<-z> I<zone> ] [ B<--msltohae> ] [ B<--haetomsl> ] 10[ B<-v> ] 11[ B<--comment-delimiter> I<commentdelim> ] 12[ B<--version> | B<-h> | B<--help> ] 13[ B<--input-file> I<infile> | B<--input-string> I<instring> ] 14[ B<--line-separator> I<linesep> ] 15[ B<--output-file> I<outfile> ] 16 17=head1 DESCRIPTION 18 19B<GeoidEval> reads in positions on standard input and prints out the 20corresponding heights of the geoid above the WGS84 ellipsoid on standard 21output. 22 23Positions are given as latitude and longitude, UTM/UPS, or MGRS, in any 24of the formats accepted by GeoConvert(1). (MGRS coordinates signify the 25I<center> of the corresponding MGRS square.) If the B<-z> option is 26specified then the specified zone is prepended to each line of input 27(which must be in UTM/UPS coordinates). This allows a file with UTM 28eastings and northings in a single zone to be used as standard input. 29 30More accurate results for the geoid height are provided by Gravity(1). 31This utility can also compute the direction of gravity accurately. 32 33The height of the geoid above the ellipsoid, I<N>, is sometimes called 34the geoid undulation. It can be used to convert a height above the 35ellipsoid, I<h>, to the corresponding height above the geoid (the 36orthometric height, roughly the height above mean sea level), I<H>, 37using the relations 38 39=over 40 41I<h> = I<N> + I<H>, E<nbsp>E<nbsp>I<H> = -I<N> + I<h>. 42 43=back 44 45=head1 OPTIONS 46 47=over 48 49=item B<-n> I<name> 50 51use geoid I<name> instead of the default C<egm96-5>. See 52L</GEOIDS>. 53 54=item B<-d> I<dir> 55 56read geoid data from I<dir> instead of the default. See 57L</GEOIDS>. 58 59=item B<-l> 60 61use bilinear interpolation instead of cubic. See 62L</INTERPOLATION>. 63 64=item B<-a> 65 66cache the entire data set in memory. See L</CACHE>. 67 68=item B<-c> I<south> I<west> I<north> I<east> 69 70cache the data bounded by I<south> I<west> I<north> I<east> in memory. 71The first two arguments specify the SW corner of the cache and the last 72two arguments specify the NE corner. The B<-w> flag specifies that 73longitude precedes latitude for these corners, provided that it appears 74before B<-c>. See L</CACHE>. 75 76=item B<-w> 77 78toggle the longitude first flag (it starts off); if the flag is on, then 79when reading geographic coordinates, longitude precedes latitude (this 80can be overridden by a hemisphere designator, I<N>, I<S>, I<E>, I<W>). 81 82=item B<-z> I<zone> 83 84prefix each line of input by I<zone>, e.g., C<38n>. This should be used 85when the input consists of UTM/UPS eastings and northings. 86 87=item B<--msltohae> 88 89standard input should include a final token on each line which is 90treated as a height (in meters) above the geoid and the output echoes 91the input line with the height converted to height above ellipsoid 92(HAE). If B<-z> I<zone> is specified then the I<third> token is treated 93as the height; this makes it possible to convert LIDAR data where each 94line consists of: easting northing height intensity. 95 96=item B<--haetomsl> 97 98this is similar to B<--msltohae> except that the height token is treated 99as a height (in meters) above the ellipsoid and the output echoes the 100input line with the height converted to height above the geoid (MSL). 101 102=item B<-v> 103 104print information about the geoid on standard error before processing 105the input. 106 107=item B<--comment-delimiter> I<commentdelim> 108 109set the comment delimiter to I<commentdelim> (e.g., "#" or "//"). If 110set, the input lines will be scanned for this delimiter and, if found, 111the delimiter and the rest of the line will be removed prior to 112processing and subsequently appended to the output line (separated by a 113space). 114 115=item B<--version> 116 117print version and exit. 118 119=item B<-h> 120 121print usage, the default geoid path and name, and exit. 122 123=item B<--help> 124 125print full documentation and exit. 126 127=item B<--input-file> I<infile> 128 129read input from the file I<infile> instead of from standard input; a file 130name of "-" stands for standard input. 131 132=item B<--input-string> I<instring> 133 134read input from the string I<instring> instead of from standard input. 135All occurrences of the line separator character (default is a semicolon) 136in I<instring> are converted to newlines before the reading begins. 137 138=item B<--line-separator> I<linesep> 139 140set the line separator character to I<linesep>. By default this is a 141semicolon. 142 143=item B<--output-file> I<outfile> 144 145write output to the file I<outfile> instead of to standard output; a 146file name of "-" stands for standard output. 147 148=back 149 150=head1 GEOIDS 151 152B<GeoidEval> computes geoid heights by interpolating on the data in a 153regularly spaced table (see L</INTERPOLATION>). The following geoid 154tables are available (however, some may not be installed): 155 156 bilinear error cubic error 157 name geoid grid max rms max rms 158 egm84-30 EGM84 30' 1.546 m 70 mm 0.274 m 14 mm 159 egm84-15 EGM84 15' 0.413 m 18 mm 0.021 m 1.2 mm 160 egm96-15 EGM96 15' 1.152 m 40 mm 0.169 m 7.0 mm 161 egm96-5 EGM96 5' 0.140 m 4.6 mm .0032 m 0.7 mm 162 egm2008-5 EGM2008 5' 0.478 m 12 mm 0.294 m 4.5 mm 163 egm2008-2_5 EGM2008 2.5' 0.135 m 3.2 mm 0.031 m 0.8 mm 164 egm2008-1 EGM2008 1' 0.025 m 0.8 mm .0022 m 0.7 mm 165 166By default, the C<egm96-5> geoid is used. This may changed by setting 167the environment variable C<GEOGRAPHICLIB_GEOID_NAME> or with the B<-n> 168option. The errors listed here are estimates of the quantization and 169interpolation errors in the reported heights compared to the specified 170geoid. 171 172The geoid data will be loaded from a directory specified at compile 173time. This may changed by setting the environment variables 174C<GEOGRAPHICLIB_GEOID_PATH> or C<GEOGRAPHICLIB_DATA>, or with the B<-d> 175option. The B<-h> option prints the default geoid path and name. Use 176the B<-v> option to ascertain the full path name of the data file. 177 178Instructions for downloading and installing geoid data are available at 179L<https://geographiclib.sourceforge.io/html/geoid.html#geoidinst>. 180 181B<NOTE>: all the geoids above apply to the WGS84 ellipsoid (I<a> = 1826378137 m, I<f> = 1/298.257223563) only. 183 184=head1 INTERPOLATION 185 186Cubic interpolation is used to compute the geoid height unless B<-l> is 187specified in which case bilinear interpolation is used. The cubic 188interpolation is based on a least-squares fit of a cubic polynomial to a 18912-point stencil 190 191 . 1 1 . 192 1 2 2 1 193 1 2 2 1 194 . 1 1 . 195 196The cubic is constrained to be independent of longitude when evaluating 197the height at one of the poles. Cubic interpolation is considerably 198more accurate than bilinear; however it results in small discontinuities 199in the returned height on cell boundaries. 200 201=head1 CACHE 202 203By default, the data file is randomly read to compute the geoid heights 204at the input positions. Usually this is sufficient for interactive use. 205If many heights are to be computed, use B<-c> I<south> I<west> I<north> 206I<east> to notify B<GeoidEval> to read a rectangle of data into memory; 207heights within the this rectangle can then be computed without any disk 208access. If B<-a> is specified all the geoid data is read; in the case 209of C<egm2008-1>, this requires about 0.5 GB of RAM. The evaluation of 210heights outside the cached area causes the necessary data to be read 211from disk. Use the B<-v> option to verify the size of the cache. 212 213Regardless of whether any cache is requested (with the B<-a> or B<-c> 214options), the data for the last grid cell in cached. This allows 215the geoid height along a continuous path to be returned with little 216disk overhead. 217 218=head1 ENVIRONMENT 219 220=over 221 222=item B<GEOGRAPHICLIB_GEOID_NAME> 223 224Override the compile-time default geoid name of C<egm96-5>. The B<-h> 225option reports the value of B<GEOGRAPHICLIB_GEOID_NAME>, if defined, 226otherwise it reports the compile-time value. If the B<-n> I<name> 227option is used, then I<name> takes precedence. 228 229=item B<GEOGRAPHICLIB_GEOID_PATH> 230 231Override the compile-time default geoid path. This is typically 232C</usr/local/share/GeographicLib/geoids> on Unix-like systems and 233C<C:/ProgramData/GeographicLib/geoids> on Windows systems. The B<-h> 234option reports the value of B<GEOGRAPHICLIB_GEOID_PATH>, if defined, 235otherwise it reports the compile-time value. If the B<-d> I<dir> option 236is used, then I<dir> takes precedence. 237 238=item B<GEOGRAPHICLIB_DATA> 239 240Another way of overriding the compile-time default geoid path. If it 241is set (and if B<GEOGRAPHICLIB_GEOID_PATH> is not set), then 242$B<GEOGRAPHICLIB_DATA>/geoids is used. 243 244=back 245 246=head1 ERRORS 247 248An illegal line of input will print an error message to standard output 249beginning with C<ERROR:> and causes B<GeoidEval> to return an exit code 250of 1. However, an error does not cause B<GeoidEval> to terminate; 251following lines will be converted. 252 253=head1 ABBREVIATIONS 254 255The geoid is usually approximated by an "earth gravity model". The 256models published by the NGA are: 257 258=over 259 260=item B<EGM84> 261 262An earth gravity model published by the NGA in 1984, 263L<https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm84>. 264 265=item B<EGM96> 266 267An earth gravity model published by the NGA in 1996, 268L<https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm96>. 269 270=item B<EGM2008> 271 272An earth gravity model published by the NGA in 2008, 273L<https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm2008>. 274 275=item B<WGS84> 276 277World Geodetic System 1984, 278L<https://en.wikipedia.org/wiki/WGS84>. 279 280=item B<HAE> 281 282Height above the WGS84 ellipsoid. 283 284=item B<MSL> 285 286Mean sea level, used as a convenient short hand for the geoid. 287(However, typically, the geoid differs by a few meters from mean sea 288level.) 289 290=back 291 292=head1 EXAMPLES 293 294The height of the EGM96 geoid at Timbuktu 295 296 echo 16:46:33N 3:00:34W | GeoidEval 297 => 28.7068 -0.02e-6 -1.73e-6 298 299The first number returned is the height of the geoid and the 2nd and 3rd 300are its slopes in the northerly and easterly directions. 301 302Convert a point in UTM zone 18n from MSL to HAE 303 304 echo 531595 4468135 23 | GeoidEval --msltohae -z 18n 305 => 531595 4468135 -10.842 306 307=head1 SEE ALSO 308 309GeoConvert(1), Gravity(1), geographiclib-get-geoids(8). 310 311An online version of this utility is availbable at 312L<https://geographiclib.sourceforge.io/cgi-bin/GeoidEval>. 313 314=head1 AUTHOR 315 316B<GeoidEval> was written by Charles Karney. 317 318=head1 HISTORY 319 320B<GeoidEval> was added to GeographicLib, 321L<https://geographiclib.sourceforge.io>, in 2009-09. 322