GeographicLib::Geoid Class Reference

Looking up the height of the geoid above the ellipsoid. 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 | 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 | EquatorialRadius () const
Math::real | Flattening () const

## Static Public Member Functions

static std::string | DefaultGeoidPath ()
static std::string | DefaultGeoidName ()

## Detailed Description

Looking up the height of the geoid above the ellipsoid.

This class evaluates 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

- EGM84: https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm84
- EGM96: https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm96
- EGM2008: https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm2008

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

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.

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 single-cell cache. If multiple threads need to calculate geoid heights they should all construct thread-local 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 single-cell caching which results in a Geoid object which is thread safe.

Example of use:

// Example of using the GeographicLib::Geoid class
// This requires that the egm96-5 geoid model be installed; see
// https://geographiclib.sourceforge.io/C++/doc/geoid.html#geoidinst
#include <iostream>
#include <exception>
#include <GeographicLib/Geoid.hpp>
using namespace std;
using namespace GeographicLib;
int main() {
try {
Geoid egm96("egm96-5");
// Convert height above egm96 to height above the ellipsoid
double lat = 42, lon = -75, height_above_geoid = 20;
double
geoid_height = egm96(lat, lon),
height_above_ellipsoid = (height_above_geoid +
Geoid::GEOIDTOELLIPSOID * geoid_height);
cout << height_above_ellipsoid << "\n";
}
catch (const exception& e) {
cerr << "Caught exception: " << e.what() << "\n";
return 1;
}
}
main
int main(int argc, const char *const argv[])
Definition: CartConvert.cpp:29
Geoid.hpp
Header for GeographicLib::Geoid class.
GeographicLib::Geoid::GEOIDTOELLIPSOID
@ GEOIDTOELLIPSOID
Definition: Geoid.hpp:192
GeographicLib
Namespace for GeographicLib.
Definition: Accumulator.cpp:12
std
Definition: NearestNeighbor.hpp:812

GeoidEval is a command-line utility providing access to the functionality of Geoid.

Definition at line 82 of file Geoid.hpp.

## Member Enumeration Documentation

## convertflag

enum GeographicLib::Geoid::convertflag

Flags indicating conversions between heights above the geoid and heights above the ellipsoid.

Enumerator
ELLIPSOIDTOGEOID | The multiplier for converting from heights above the ellipsoid to heights above the geoid.
NONE | No conversion.
GEOIDTOELLIPSOID | The multiplier for converting from heights above the geoid to heights above the ellipsoid.

Definition at line 178 of file Geoid.hpp.

## Constructor & Destructor Documentation

## Geoid()

GeographicLib::Geoid::Geoid | ( | const std::string & | name,
|  | const std::string & | path = `""`,
|  | bool | cubic = `true`,
|  | bool | threadsafe = `false`
| ) |  |

explicit

Construct a geoid.

Parameters

  [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

Exceptions

  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 non-empty), 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 single-cell caching is turned off; this results in a Geoid object which is thread safe.

Definition at line 201 of file Geoid.cpp.

References CacheAll(), DefaultGeoidPath(), GeographicLib::Math::hd, and GeographicLib::Math::td.

## Member Function Documentation

## CacheArea()

void GeographicLib::Geoid::CacheArea | ( | real | south,
|  | real | west,
|  | real | north,
|  | real | east
| ) |  | const

Set up a cache.

Parameters

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

Exceptions

  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°].

Definition at line 408 of file Geoid.cpp.

References GeographicLib::Math::AngNormalize(), CacheClear(), GeographicLib::Math::LatFix(), and GeographicLib::Math::td.

Referenced by main().

## CacheAll()

void GeographicLib::Geoid::CacheAll | ( |  | ) | const

inline

Cache all the data.

Exceptions

  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.

Definition at line 258 of file Geoid.hpp.

References GeographicLib::Math::qd, and GeographicLib::Math::td.

Referenced by Geoid(), and main().

## CacheClear()

void GeographicLib::Geoid::CacheClear | ( |  | ) | const

Clear the cache. This never throws an error. (This does nothing with a thread safe Geoid.)

Definition at line 395 of file Geoid.cpp.

References std::swap().

Referenced by CacheArea().

## operator()()

Math::real GeographicLib::Geoid::operator() | ( | real | lat,
|  | real | lon
| ) |  | const

inline

Compute the geoid height at a point

Parameters

  [in] | lat | latitude of the point (degrees).
  [in] | lon | longitude of the point (degrees).

Exceptions

  GeographicErr | if there's a problem reading the data; this never happens if (lat, lon) is within a successfully cached area.

Returns
  the height of the geoid above the ellipsoid (meters).

The latitude should be in [−90°, 90°].

Definition at line 284 of file Geoid.hpp.

## ConvertHeight()

Math::real GeographicLib::Geoid::ConvertHeight | ( | real | lat,
|  | real | lon,
|  | real | h,
|  | convertflag | d
| ) |  | const

inline

Convert a height above the geoid to a height above the ellipsoid and vice versa.

Parameters

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

Exceptions

  GeographicErr | if there's a problem reading the data; this never happens if (lat, lon) is within a successfully cached area.

Returns
  converted height (meters).

Definition at line 304 of file Geoid.hpp.

## Description()

const std::string & GeographicLib::Geoid::Description | ( |  | ) | const

inline

Returns
  geoid description, if available, in the data file; if absent, return "NONE".

Definition at line 318 of file Geoid.hpp.

Referenced by main().

## DateTime()

const std::string & GeographicLib::Geoid::DateTime | ( |  | ) | const

inline

Returns
  date of the data file; if absent, return "UNKNOWN".

Definition at line 323 of file Geoid.hpp.

Referenced by main().

## GeoidFile()

const std::string & GeographicLib::Geoid::GeoidFile | ( |  | ) | const

inline

Returns
  full file name used to load the geoid data.

Definition at line 328 of file Geoid.hpp.

Referenced by main().

## GeoidName()

const std::string & GeographicLib::Geoid::GeoidName | ( |  | ) | const

inline

Returns
  "name" used to load the geoid data (from the first argument of the constructor).

Definition at line 334 of file Geoid.hpp.

## GeoidDirectory()

const std::string & GeographicLib::Geoid::GeoidDirectory | ( |  | ) | const

inline

Returns
  directory used to load the geoid data.

Definition at line 339 of file Geoid.hpp.

## Interpolation()

const std::string GeographicLib::Geoid::Interpolation | ( |  | ) | const

inline

Returns
  interpolation method ("cubic" or "bilinear").

Definition at line 344 of file Geoid.hpp.

Referenced by main().

## MaxError()

Math::real GeographicLib::Geoid::MaxError | ( |  | ) | const

inline

Returns
  estimate of the maximum interpolation and quantization error (meters).

This relies on the value being stored in the data file. If the value is absent, return −1.

Definition at line 354 of file Geoid.hpp.

Referenced by main().

## RMSError()

Math::real GeographicLib::Geoid::RMSError | ( |  | ) | const

inline

Returns
  estimate of the RMS interpolation and quantization error (meters).

This relies on the value being stored in the data file. If the value is absent, return −1.

Definition at line 363 of file Geoid.hpp.

Referenced by main().

## Offset()

Math::real GeographicLib::Geoid::Offset | ( |  | ) | const

inline

Returns
  offset (meters).

This in used in converting from the pixel values in the data file to geoid heights.

Definition at line 371 of file Geoid.hpp.

Referenced by main().

## Scale()

Math::real GeographicLib::Geoid::Scale | ( |  | ) | const

inline

Returns
  scale (meters).

This in used in converting from the pixel values in the data file to geoid heights.

Definition at line 379 of file Geoid.hpp.

Referenced by main().

## ThreadSafe()

bool GeographicLib::Geoid::ThreadSafe | ( |  | ) | const

inline

Returns
  true if the object is constructed to be thread safe.

Definition at line 384 of file Geoid.hpp.

## Cache()

bool GeographicLib::Geoid::Cache | ( |  | ) | const

inline

Returns
  true if a data cache is active.

Definition at line 389 of file Geoid.hpp.

Referenced by main().

## CacheWest()

Math::real GeographicLib::Geoid::CacheWest | ( |  | ) | const

inline

Returns
  west edge of the cached area; the cache includes this edge.

Definition at line 394 of file Geoid.hpp.

Referenced by main().

## CacheEast()

Math::real GeographicLib::Geoid::CacheEast | ( |  | ) | const

inline

Returns
  east edge of the cached area; the cache excludes this edge.

Definition at line 403 of file Geoid.hpp.

Referenced by main().

## CacheNorth()

Math::real GeographicLib::Geoid::CacheNorth | ( |  | ) | const

inline

Returns
  north edge of the cached area; the cache includes this edge.

Definition at line 413 of file Geoid.hpp.

References GeographicLib::Math::qd.

Referenced by main().

## CacheSouth()

Math::real GeographicLib::Geoid::CacheSouth | ( |  | ) | const

inline

Returns
  south edge of the cached area; the cache excludes this edge unless it's the south pole.

Definition at line 421 of file Geoid.hpp.

References GeographicLib::Math::qd.

Referenced by main().

## EquatorialRadius()

Math::real GeographicLib::Geoid::EquatorialRadius | ( |  | ) | const

inline

Returns
  a the equatorial radius of the WGS84 ellipsoid (meters).

(The WGS84 value is returned because the supported geoid models are all based on this ellipsoid.)

Definition at line 433 of file Geoid.hpp.

References GeographicLib::Constants::WGS84_a().

## Flattening()

Math::real GeographicLib::Geoid::Flattening | ( |  | ) | const

inline

Returns
  f the flattening of the WGS84 ellipsoid.

(The WGS84 value is returned because the supported geoid models are all based on this ellipsoid.)

Definition at line 442 of file Geoid.hpp.

References GeographicLib::Constants::WGS84_f().

## DefaultGeoidPath()

string GeographicLib::Geoid::DefaultGeoidPath | ( |  | ) |

static

Returns
  the default path for geoid data files.

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 compile-time default (/usr/local/share/GeographicLib/geoids on non-Windows systems and C:/ProgramData/GeographicLib/geoids on Windows systems).

Definition at line 489 of file Geoid.cpp.

References GEOGRAPHICLIB_DATA.

Referenced by Geoid().

## DefaultGeoidName()

string GeographicLib::Geoid::DefaultGeoidName | ( |  | ) |

static

Returns
  the default name for the geoid.

This is the value of the environment variable GEOGRAPHICLIB_GEOID_NAME, if set; otherwise, it is "egm96-5". 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 502 of file Geoid.cpp.

References GEOGRAPHICLIB_GEOID_DEFAULT_NAME.

The documentation for this class was generated from the following files:

- Geoid.hpp
- Geoid.cpp