Looking up the height of the geoid above the ellipsoid. More...

#include <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	MajorRadius () const

Math::real	Flattening () const

Static Public Member Functions
static std::string	DefaultGeoidName ()

static std::string	DefaultGeoidPath ()

Private Types
typedef unsigned short	pixel_t

typedef Math::real	real

Private Member Functions
void	filepos (int ix, int iy) const

	Geoid (const Geoid &)

real	height (real lat, real lon) const

Geoid &	operator= (const Geoid &)

real	rawval (int ix, int iy) const

Private Attributes
const real	_a

bool	_cache

const bool	_cubic

std::vector< std::vector< pixel_t > >	_data

unsigned long long	_datastart

std::string	_datetime

const real	_degree

std::string	_description

std::string	_dir

const real	_e2

const real	_eps

std::ifstream	_file

std::string	_filename

int	_height

int	_ix

int	_iy

real	_maxerror

std::string	_name

real	_offset

real	_rlatres

real	_rlonres

real	_rmserror

real	_scale

unsigned long long	_swidth

real	_t [nterms_]

bool	_threadsafe

real	_v00

real	_v01

real	_v10

real	_v11

int	_width

int	_xoffset

int	_xsize

int	_yoffset

int	_ysize

Static Private Attributes
static const int	c0_ = 240

static const int	c0n_ = 372

static const int	c0s_ = 372

static const int	c3_ [stencilsize_ *nterms_]

static const int	c3n_ [stencilsize_ *nterms_]

static const int	c3s_ [stencilsize_ *nterms_]

static const unsigned	nterms_ = ((3 + 1) * (3 + 2))/2

static const unsigned	pixel_max_ = 0xffffu

static const unsigned	pixel_size_ = 2

static const unsigned	stencilsize_ = 12

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

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 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
#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;
  }
}

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

Definition at line 82 of file Geoid.hpp.

Member Typedef Documentation

typedef unsigned short GeographicLib::Geoid::pixel_t

private

Definition at line 86 of file Geoid.hpp.

typedef Math::real GeographicLib::Geoid::real

private

Definition at line 84 of file Geoid.hpp.

Member Enumeration Documentation

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 geoid to heights above the ellipsoid.
NONE	No conversion.
GEOIDTOELLIPSOID	The multiplier for converting from heights above the ellipsoid to heights above the geoid.

Definition at line 182 of file Geoid.hpp.

Constructor & Destructor Documentation

GeographicLib::Geoid::Geoid ( const Geoid & )

private

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 200 of file src/Geoid.cpp.

Member Function Documentation

bool GeographicLib::Geoid::Cache ( ) const

inline

Returns: true if a data cache is active.

Definition at line 393 of file Geoid.hpp.

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 262 of file Geoid.hpp.

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 407 of file src/Geoid.cpp.

void GeographicLib::Geoid::CacheClear ( ) const

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

Definition at line 394 of file src/Geoid.cpp.

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

inline

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

Definition at line 407 of file Geoid.hpp.

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

inline

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

Definition at line 417 of file Geoid.hpp.

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 425 of file Geoid.hpp.

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

inline

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

Definition at line 398 of file Geoid.hpp.

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 308 of file Geoid.hpp.

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

inline

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

Definition at line 327 of file Geoid.hpp.

std::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 501 of file src/Geoid.cpp.

std::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 488 of file src/Geoid.cpp.

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

inline

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

Definition at line 322 of file Geoid.hpp.

void GeographicLib::Geoid::filepos	(	int	ix,
		int	iy
	)		const

inlineprivate

Definition at line 122 of file Geoid.hpp.

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 444 of file Geoid.hpp.

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

inline

Returns: directory used to load the geoid data.

Definition at line 343 of file Geoid.hpp.

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

inline

Returns: full file name used to load the geoid data.

Definition at line 332 of file Geoid.hpp.

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 338 of file Geoid.hpp.

Math::real GeographicLib::Geoid::height	(	real	lat,
		real	lon
	)		const

private

Definition at line 306 of file src/Geoid.cpp.

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

inline

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

Definition at line 348 of file Geoid.hpp.

Math::real GeographicLib::Geoid::MajorRadius ( ) 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 435 of file Geoid.hpp.

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 358 of file Geoid.hpp.

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 375 of file Geoid.hpp.

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 288 of file Geoid.hpp.

Geoid& GeographicLib::Geoid::operator= ( const Geoid & )

private

real GeographicLib::Geoid::rawval	(	int	ix,
		int	iy
	)		const

inlineprivate

Definition at line 131 of file Geoid.hpp.

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 367 of file Geoid.hpp.

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 383 of file Geoid.hpp.

bool GeographicLib::Geoid::ThreadSafe ( ) const

inline

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

Definition at line 388 of file Geoid.hpp.

Member Data Documentation

const real GeographicLib::Geoid::_a

private

Definition at line 105 of file Geoid.hpp.

bool GeographicLib::Geoid::_cache

mutableprivate

Definition at line 115 of file Geoid.hpp.

const bool GeographicLib::Geoid::_cubic

private

Definition at line 104 of file Geoid.hpp.

std::vector< std::vector<pixel_t> > GeographicLib::Geoid::_data

mutableprivate

Definition at line 114 of file Geoid.hpp.

unsigned long long GeographicLib::Geoid::_datastart

private

Definition at line 111 of file Geoid.hpp.

std::string GeographicLib::Geoid::_datetime

private

Definition at line 108 of file Geoid.hpp.

const real GeographicLib::Geoid::_degree

private

Definition at line 105 of file Geoid.hpp.

std::string GeographicLib::Geoid::_description

private

Definition at line 108 of file Geoid.hpp.

std::string GeographicLib::Geoid::_dir

private

Definition at line 103 of file Geoid.hpp.

const real GeographicLib::Geoid::_e2

private

Definition at line 105 of file Geoid.hpp.

const real GeographicLib::Geoid::_eps

private

Definition at line 105 of file Geoid.hpp.

std::ifstream GeographicLib::Geoid::_file

mutableprivate

Definition at line 106 of file Geoid.hpp.

std::string GeographicLib::Geoid::_filename

private

Definition at line 103 of file Geoid.hpp.

int GeographicLib::Geoid::_height

private

Definition at line 110 of file Geoid.hpp.

int GeographicLib::Geoid::_ix

mutableprivate

Definition at line 119 of file Geoid.hpp.

int GeographicLib::Geoid::_iy

mutableprivate

Definition at line 119 of file Geoid.hpp.

real GeographicLib::Geoid::_maxerror

private

Definition at line 109 of file Geoid.hpp.

std::string GeographicLib::Geoid::_name

private

Definition at line 103 of file Geoid.hpp.

real GeographicLib::Geoid::_offset

private

Definition at line 109 of file Geoid.hpp.

real GeographicLib::Geoid::_rlatres

private

Definition at line 107 of file Geoid.hpp.

real GeographicLib::Geoid::_rlonres

private

Definition at line 107 of file Geoid.hpp.

real GeographicLib::Geoid::_rmserror

private

Definition at line 109 of file Geoid.hpp.

real GeographicLib::Geoid::_scale

private

Definition at line 109 of file Geoid.hpp.

unsigned long long GeographicLib::Geoid::_swidth

private

Definition at line 111 of file Geoid.hpp.

real GeographicLib::Geoid::_t[nterms_]

mutableprivate

Definition at line 121 of file Geoid.hpp.

bool GeographicLib::Geoid::_threadsafe

private

Definition at line 112 of file Geoid.hpp.

real GeographicLib::Geoid::_v00

mutableprivate

Definition at line 120 of file Geoid.hpp.

real GeographicLib::Geoid::_v01

mutableprivate

Definition at line 120 of file Geoid.hpp.

real GeographicLib::Geoid::_v10

mutableprivate

Definition at line 120 of file Geoid.hpp.

real GeographicLib::Geoid::_v11

mutableprivate

Definition at line 120 of file Geoid.hpp.

int GeographicLib::Geoid::_width

private

Definition at line 110 of file Geoid.hpp.

int GeographicLib::Geoid::_xoffset

mutableprivate

Definition at line 117 of file Geoid.hpp.

int GeographicLib::Geoid::_xsize

mutableprivate

Definition at line 117 of file Geoid.hpp.

int GeographicLib::Geoid::_yoffset

mutableprivate

Definition at line 117 of file Geoid.hpp.

int GeographicLib::Geoid::_ysize

mutableprivate

Definition at line 117 of file Geoid.hpp.

const int GeographicLib::Geoid::c0_ = 240

staticprivate

Definition at line 96 of file Geoid.hpp.

const int GeographicLib::Geoid::c0n_ = 372

staticprivate

Definition at line 97 of file Geoid.hpp.

const int GeographicLib::Geoid::c0s_ = 372

staticprivate

Definition at line 98 of file Geoid.hpp.

const int GeographicLib::Geoid::c3_

staticprivate

Initial value:

= {
      9, -18, -88,    0,  96,   90,   0,   0, -60, -20,
     -9,  18,   8,    0, -96,   30,   0,   0,  60, -20,
      9, -88, -18,   90,  96,    0, -20, -60,   0,   0,
    186, -42, -42, -150, -96, -150,  60,  60,  60,  60,
     54, 162, -78,   30, -24,  -90, -60,  60, -60,  60,
     -9, -32,  18,   30,  24,    0,  20, -60,   0,   0,
     -9,   8,  18,   30, -96,    0, -20,  60,   0,   0,
     54, -78, 162,  -90, -24,   30,  60, -60,  60, -60,
    -54,  78,  78,   90, 144,   90, -60, -60, -60, -60,
      9,  -8, -18,  -30, -24,    0,  20,  60,   0,   0,
     -9,  18, -32,    0,  24,   30,   0,   0, -60,  20,
      9, -18,  -8,    0, -24,  -30,   0,   0,  60,  20,
  }

Definition at line 99 of file Geoid.hpp.

const int GeographicLib::Geoid::c3n_

staticprivate

Initial value:

= {
      0, 0, -131, 0,  138,  144, 0,   0, -102, -31,
      0, 0,    7, 0, -138,   42, 0,   0,  102, -31,
     62, 0,  -31, 0,    0,  -62, 0,   0,    0,  31,
    124, 0,  -62, 0,    0, -124, 0,   0,    0,  62,
    124, 0,  -62, 0,    0, -124, 0,   0,    0,  62,
     62, 0,  -31, 0,    0,  -62, 0,   0,    0,  31,
      0, 0,   45, 0, -183,   -9, 0,  93,   18,   0,
      0, 0,  216, 0,   33,   87, 0, -93,   12, -93,
      0, 0,  156, 0,  153,   99, 0, -93,  -12, -93,
      0, 0,  -45, 0,   -3,    9, 0,  93,  -18,   0,
      0, 0,  -55, 0,   48,   42, 0,   0,  -84,  31,
      0, 0,   -7, 0,  -48,  -42, 0,   0,   84,  31,
  }

Definition at line 100 of file Geoid.hpp.

const int GeographicLib::Geoid::c3s_

staticprivate

Initial value:

= {
     18,  -36, -122,   0,  120,  135, 0,   0,  -84, -31,
    -18,   36,   -2,   0, -120,   51, 0,   0,   84, -31,
     36, -165,  -27,  93,  147,   -9, 0, -93,   18,   0,
    210,   45, -111, -93,  -57, -192, 0,  93,   12,  93,
    162,  141,  -75, -93, -129, -180, 0,  93,  -12,  93,
    -36,  -21,   27,  93,   39,    9, 0, -93,  -18,   0,
      0,    0,   62,   0,    0,   31, 0,   0,    0, -31,
      0,    0,  124,   0,    0,   62, 0,   0,    0, -62,
      0,    0,  124,   0,    0,   62, 0,   0,    0, -62,
      0,    0,   62,   0,    0,   31, 0,   0,    0, -31,
    -18,   36,  -64,   0,   66,   51, 0,   0, -102,  31,
     18,  -36,    2,   0,  -66,  -51, 0,   0,  102,  31,
  }

Definition at line 101 of file Geoid.hpp.

const unsigned GeographicLib::Geoid::nterms_ = ((3 + 1) * (3 + 2))/2

staticprivate

Definition at line 95 of file Geoid.hpp.

const unsigned GeographicLib::Geoid::pixel_max_ = 0xffffu

staticprivate

Definition at line 88 of file Geoid.hpp.

const unsigned GeographicLib::Geoid::pixel_size_ = 2

staticprivate

Definition at line 87 of file Geoid.hpp.

const unsigned GeographicLib::Geoid::stencilsize_ = 12

staticprivate

Definition at line 94 of file Geoid.hpp.

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

Public Types

Public Member Functions

Static Public Member Functions

Private Types

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation