GeographicLib
1.42

Looking up the height of the geoid. More...
#include <GeographicLib/Geoid.hpp>
Public Types  
enum  convertflag { ELLIPSOIDTOGEOID = 1, NONE = 0, GEOIDTOELLIPSOID = 1 } 
Public Member Functions  
Setting up the geoid  
Geoid (const std::string &name, const std::string &path="", bool cubic=true, bool threadsafe=false)  
void  CacheArea (real south, real west, real north, real east) const 
void  CacheAll () const 
void  CacheClear () const 
Compute geoid heights  
Math::real  operator() (real lat, real lon) const 
Math::real  operator() (real lat, real lon, real &gradn, real &grade) const 
Math::real  ConvertHeight (real lat, real lon, real h, convertflag d) const 
Inspector functions  
const std::string &  Description () const 
const std::string &  DateTime () const 
const std::string &  GeoidFile () const 
const std::string &  GeoidName () const 
const std::string &  GeoidDirectory () const 
const std::string  Interpolation () const 
Math::real  MaxError () const 
Math::real  RMSError () const 
Math::real  Offset () const 
Math::real  Scale () const 
bool  ThreadSafe () const 
bool  Cache () const 
Math::real  CacheWest () const 
Math::real  CacheEast () const 
Math::real  CacheNorth () const 
Math::real  CacheSouth () const 
Math::real  MajorRadius () const 
Math::real  Flattening () const 
Static Public Member Functions  
static std::string  DefaultGeoidPath () 
static std::string  DefaultGeoidName () 
Looking up the height of the geoid.
This class evaluated the height of one of the standard geoids, EGM84, EGM96, or EGM2008 by bilinear or cubic interpolation into a rectangular grid of data. These geoid models are documented in
The geoids are defined in terms of spherical harmonics. However in order to provide a quick and flexible method of evaluating the geoid heights, this class evaluates the height by interpolation into a grid of precomputed values.
The geoid height, N, can be used to convert a height above the ellipsoid, h, to the corresponding height above the geoid (roughly the height above mean sea level), H, using the relations
h = N + H; H = −N + h.
See Geoid height for details of how to install the data sets, the data format, estimates of the interpolation errors, and how to use caching.
In addition to returning the geoid height, the gradient of the geoid can be calculated. The gradient is defined as the rate of change of the geoid as a function of position on the ellipsoid. This uses the parameters for the WGS84 ellipsoid. The gradient defined in terms of the interpolated heights. As a result of the way that the geoid data is stored, the calculation of gradients can result in large quantization errors. This is particularly acute for fine grids, at high latitudes, and for the easterly gradient. For this reason, the use of this facility is DEPRECATED. Instead, use the GravityModel class to evaluate the gravity vector.
This class is typically not thread safe in that a single instantiation cannot be safely used by multiple threads because of the way the object reads the data set and because it maintains a singlecell cache. If multiple threads need to calculate geoid heights they should all construct threadlocal instantiations. Alternatively, set the optional threadsafe parameter to true in the constructor. This causes the constructor to read all the data into memory and to turn off the singlecell caching which results in a Geoid object which is thread safe.
Example of use:
GeoidEval is a commandline utility providing access to the functionality of Geoid.
Flags indicating conversions between heights above the geoid and heights above the ellipsoid.

explicit 
Construct a geoid.
[in]  name  the name of the geoid. 
[in]  path  (optional) directory for data file. 
[in]  cubic  (optional) interpolation method; false means bilinear, true (the default) means cubic. 
[in]  threadsafe  (optional), if true, construct a thread safe object. The default is false 
GeographicErr  if the data file cannot be found, is unreadable, or is corrupt. 
GeographicErr  if threadsafe is true but the memory necessary for caching the data can't be allocated. 
The data file is formed by appending ".pgm" to the name. If path is specified (and is nonempty), then the file is loaded from directory, path. Otherwise the path is given by DefaultGeoidPath(). If the threadsafe parameter is true, the data set is read into memory, the data file is closed, and singlecell caching is turned off; this results in a Geoid object which is thread safe.
Definition at line 200 of file Geoid.cpp.
References CacheAll(), and DefaultGeoidPath().
void GeographicLib::Geoid::CacheArea  (  real  south, 
real  west,  
real  north,  
real  east  
)  const 
Set up a cache.
[in]  south  latitude (degrees) of the south edge of the cached area. 
[in]  west  longitude (degrees) of the west edge of the cached area. 
[in]  north  latitude (degrees) of the north edge of the cached area. 
[in]  east  longitude (degrees) of the east edge of the cached area. 
GeographicErr  if the memory necessary for caching the data can't be allocated (in this case, you will have no cache and can try again with a smaller area). 
GeographicErr  if there's a problem reading the data. 
GeographicErr  if this is called on a threadsafe Geoid. 
Cache the data for the specified "rectangular" area bounded by the parallels south and north and the meridians west and east. east is always interpreted as being east of west, if necessary by adding 360° to its value. south and north should be in the range [−90°, 90°]; west and east should be in the range [−540°, 540°).
Definition at line 442 of file Geoid.cpp.
References GeographicLib::Math::AngNormalize(), and CacheClear().
Referenced by main().

inline 
Cache all the data.
GeographicErr  if the memory necessary for caching the data can't be allocated (in this case, you will have no cache and can try again with a smaller area). 
GeographicErr  if there's a problem reading the data. 
GeographicErr  if this is called on a threadsafe Geoid. 
On most computers, this is fast for data sets with grid resolution of 5' or coarser. For a 1' grid, the required RAM is 450MB; a 2.5' grid needs 72MB; and a 5' grid needs 18MB.
void GeographicLib::Geoid::CacheClear  (  )  const 
Clear the cache. This never throws an error. (This does nothing with a thread safe Geoid.)
Definition at line 429 of file Geoid.cpp.
Referenced by CacheArea().

inline 
Compute the geoid height at a point
[in]  lat  latitude of the point (degrees). 
[in]  lon  longitude of the point (degrees). 
GeographicErr  if there's a problem reading the data; this never happens if (lat, lon) is within a successfully cached area. 
The latitude should be in [−90°, 90°] and longitude should be in [−540°, 540°).

inline 
Compute the geoid height and gradient at a point
[in]  lat  latitude of the point (degrees). 
[in]  lon  longitude of the point (degrees). 
[out]  gradn  northerly gradient (dimensionless). 
[out]  grade  easterly gradient (dimensionless). 
GeographicErr  if there's a problem reading the data; this never happens if (lat, lon) is within a successfully cached area. 
The latitude should be in [−90°, 90°] and longitude should be in [−540°, 540°). As a result of the way that the geoid data is stored, the calculation of gradients can result in large quantization errors. This is particularly acute for fine grids, at high latitudes, and for the easterly gradient. For this reason, the computation of the gradient is DEPRECATED. If you need to compute the direction of the acceleration due to gravity accurately, you should use GravityModel::Gravity.

inline 
Convert a height above the geoid to a height above the ellipsoid and vice versa.
[in]  lat  latitude of the point (degrees). 
[in]  lon  longitude of the point (degrees). 
[in]  h  height of the point (degrees). 
[in]  d  a Geoid::convertflag specifying the direction of the conversion; Geoid::GEOIDTOELLIPSOID means convert a height above the geoid to a height above the ellipsoid; Geoid::ELLIPSOIDTOGEOID means convert a height above the ellipsoid to a height above the geoid. 
GeographicErr  if there's a problem reading the data; this never happens if (lat, lon) is within a successfully cached area. 

inline 

inline 

inline 

inline 

inline 

inline 

inline 

inline 

inline 

inline 

inline 

inline 

inline 

inline 

inline 

inline 

inline 
(The WGS84 value is returned because the supported geoid models are all based on this ellipsoid.)
Definition at line 469 of file Geoid.hpp.
References GeographicLib::Constants::WGS84_a().

inline 
(The WGS84 value is returned because the supported geoid models are all based on this ellipsoid.)
Definition at line 478 of file Geoid.hpp.
References GeographicLib::Constants::WGS84_f().

static 
This is the value of the environment variable GEOGRAPHICLIB_GEOID_PATH, if set; otherwise, it is $GEOGRAPHICLIB_DATA/geoids if the environment variable GEOGRAPHICLIB_DATA is set; otherwise, it is a compiletime default (/usr/local/share/GeographicLib/geoids on nonWindows systems and C:/ProgramData/GeographicLib/geoids on Windows systems).
Definition at line 521 of file Geoid.cpp.
References GEOGRAPHICLIB_DATA.

static 
This is the value of the environment variable GEOGRAPHICLIB_GEOID_NAME, if set; otherwise, it is "egm965". The Geoid class does not use this function; it is just provided as a convenience for a calling program when constructing a Geoid object.
Definition at line 534 of file Geoid.cpp.
References GEOGRAPHICLIB_GEOID_DEFAULT_NAME.
Referenced by main().