Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GEOIDEVAL(1)		    GeographicLib Utilities		  GEOIDEVAL(1)

NAME
       GeoidEval -- look up geoid heights

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

DESCRIPTION
       GeoidEval reads in positions on standard	input and prints out the
       corresponding heights of	the geoid 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 center of the corresponding MGRS square.)  If the -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, N, is sometimes called the
       geoid undulation.  It can be used to convert a height above the
       ellipsoid, h, to	the corresponding height above the geoid (the
       orthometric height, roughly the height above mean sea level), H,	using
       the relations

	   h = N + H,	H = -N + h.

OPTIONS
       -n name
	   use geoid name instead of the default "egm96-5".  See "GEOIDS".

       -d dir
	   read	geoid data from	dir instead of the default.  See "GEOIDS".

       -l  use bilinear	interpolation instead of cubic.	 See "INTERPOLATION".

       -a  cache the entire data set in	memory.	 See "CACHE".

       -c south	west north east
	   cache the data bounded by south west	north east in memory.  The
	   first two arguments specify the SW corner of	the cache and the last
	   two arguments specify the NE	corner.	 The -w	flag specifies that
	   longitude precedes latitude for these corners, provided that	it
	   appears before -c.  See "CACHE".

       -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,	N, S,
	   E, W).

       -z zone
	   prefix each line of input by	zone, e.g., "38n".  This should	be
	   used	when the input consists	of UTM/UPS eastings and	northings.

       --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	-z zone	is specified then the third token is
	   treated as the height; this makes it	possible to convert LIDAR data
	   where each line consists of:	easting	northing height	intensity.

       --haetomsl
	   this	is similar to --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).

       -v  print information about the geoid on	standard error before
	   processing the input.

       --comment-delimiter commentdelim
	   set the comment delimiter to	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).

       --version
	   print version and exit.

       -h  print usage,	the default geoid path and name, and exit.

       --help
	   print full documentation and	exit.

       --input-file infile
	   read	input from the file infile instead of from standard input; a
	   file	name of	"-" stands for standard	input.

       --input-string instring
	   read	input from the string instring instead of from standard	input.
	   All occurrences of the line separator character (default is a
	   semicolon) in instring are converted	to newlines before the reading
	   begins.

       --line-separator	linesep
	   set the line	separator character to linesep.	 By default this is a
	   semicolon.

       --output-file outfile
	   write output	to the file outfile instead of to standard output; a
	   file	name of	"-" stands for standard	output.

GEOIDS
       GeoidEval computes geoid	heights	by interpolating on the	data in	a
       regularly spaced	table (see "INTERPOLATION").  The following geoid
       tables 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 "egm96-5" geoid is used.	 This may changed by setting
       the environment variable	"GEOGRAPHICLIB_GEOID_NAME" or with the -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 data will be loaded from a directory specified	at compile
       time.  This may changed by setting the environment variables
       "GEOGRAPHICLIB_GEOID_PATH" or "GEOGRAPHICLIB_DATA", or with the -d
       option.	The -h option prints the default geoid path and	name.  Use the
       -v option to ascertain the full path name of the	data file.

       Instructions for	downloading and	installing geoid data are available at
       <https://geographiclib.sourceforge.io/html/geoid.html#geoidinst>.

       NOTE: all the geoids above apply	to the WGS84 ellipsoid (a = 6378137 m,
       f = 1/298.257223563) only.

INTERPOLATION
       Cubic interpolation is used to compute the geoid	height unless -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.

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 -c	south west north east
       to notify GeoidEval to read a rectangle of data into memory; heights
       within the this rectangle can then be computed without any disk access.
       If -a is	specified all the geoid	data is	read; in the case of
       "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 -v option to	verify the size	of the cache.

       Regardless of whether any cache is requested (with the -a or -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.

ENVIRONMENT
       GEOGRAPHICLIB_GEOID_NAME
	   Override the	compile-time default geoid name	of "egm96-5".  The -h
	   option reports the value of GEOGRAPHICLIB_GEOID_NAME, if defined,
	   otherwise it	reports	the compile-time value.	 If the	-n name	option
	   is used, then name takes precedence.

       GEOGRAPHICLIB_GEOID_PATH
	   Override the	compile-time default geoid path.  This is typically
	   "/usr/local/share/GeographicLib/geoids" on Unix-like	systems	and
	   "C:/ProgramData/GeographicLib/geoids" on Windows systems.  The -h
	   option reports the value of GEOGRAPHICLIB_GEOID_PATH, if defined,
	   otherwise it	reports	the compile-time value.	 If the	-d dir option
	   is used, then dir takes precedence.

       GEOGRAPHICLIB_DATA
	   Another way of overriding the compile-time default geoid path.  If
	   it is set (and if GEOGRAPHICLIB_GEOID_PATH is not set), then
	   $GEOGRAPHICLIB_DATA/geoids is used.

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

ABBREVIATIONS
       The geoid is usually approximated by an "earth gravity model". The
       models published	by the NGA are:

       EGM84
	   An earth gravity model published by the NGA in 1984,
	   <http://earth-info.nga.mil/GandG/wgs84/gravitymod/wgs84_180/wgs84_180.html>.

       EGM96
	   An earth gravity model published by the NGA in 1996,
	   <http://earth-info.nga.mil/GandG/wgs84/gravitymod/egm96/egm96.html>.

       EGM2008
	   An earth gravity model published by the NGA in 2008,
	   <http://earth-info.nga.mil/GandG/wgs84/gravitymod/egm2008>.

       WGS84
	   World Geodetic System 1984, <https://en.wikipedia.org/wiki/WGS84>.

       HAE Height above	the WGS84 ellipsoid.

       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.)

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

SEE ALSO
       GeoConvert(1), Gravity(1), geographiclib-get-geoids(8).

       An online version of this utility is availbable at
       <https://geographiclib.sourceforge.io/cgi-bin/GeoidEval>.

AUTHOR
       GeoidEval was written by	Charles	Karney.

HISTORY
       GeoidEval was added to GeographicLib,
       <https://geographiclib.sourceforge.io>, in 2009-09.

GeographicLib 1.50.1		  2019-12-12			  GEOIDEVAL(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | GEOIDS | INTERPOLATION | CACHE | ENVIRONMENT | ERRORS | ABBREVIATIONS | EXAMPLES | SEE ALSO | AUTHOR | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=GeoidEval&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help