GeographicLib  1.35
Public Types | Static Public Member Functions | List of all members
GeographicLib::Geoid Class Reference

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 throw ()
 
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 throw ()
 
const std::string & DateTime () const throw ()
 
const std::string & GeoidFile () const throw ()
 
const std::string & GeoidName () const throw ()
 
const std::string & GeoidDirectory () const throw ()
 
const std::string Interpolation () const
 
Math::real MaxError () const throw ()
 
Math::real RMSError () const throw ()
 
Math::real Offset () const throw ()
 
Math::real Scale () const throw ()
 
bool ThreadSafe () const throw ()
 
bool Cache () const throw ()
 
Math::real CacheWest () const throw ()
 
Math::real CacheEast () const throw ()
 
Math::real CacheNorth () const throw ()
 
Math::real CacheSouth () const throw ()
 
Math::real MajorRadius () const throw ()
 
Math::real Flattening () const throw ()
 

Static Public Member Functions

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

Detailed Description

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.

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.

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>
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;
}
return 0;
}

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

Definition at line 83 of file Geoid.hpp.

Member Enumeration Documentation

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

Constructor & Destructor Documentation

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

Construct a geoid.

Parameters
[in]namethe 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
GeographicErrif the data file cannot be found, is unreadable, or is corrupt.
GeographicErrif 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 Geoid.cpp.

References CacheAll(), DefaultGeoidPath(), and STATIC_ASSERT.

Member Function Documentation

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

Set up a cache.

Parameters
[in]southlatitude (degrees) of the south edge of the cached area.
[in]westlongitude (degrees) of the west edge of the cached area.
[in]northlatitude (degrees) of the north edge of the cached area.
[in]eastlongitude (degrees) of the east edge of the cached area.
Exceptions
GeographicErrif 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).
GeographicErrif there's a problem reading the data.
GeographicErrif 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 441 of file Geoid.cpp.

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

Referenced by main().

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

Cache all the data.

Exceptions
GeographicErrif 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).
GeographicErrif there's a problem reading the data.
GeographicErrif 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.

Referenced by Geoid(), and main().

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

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

Definition at line 428 of file Geoid.cpp.

Referenced by CacheArea().

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

Compute the geoid height at a point

Parameters
[in]latlatitude of the point (degrees).
[in]lonlongitude of the point (degrees).
Exceptions
GeographicErrif there's a problem reading the data; this never happens if (lat, lon) is within a successfully cached area.
Returns
geoid height (meters).

The latitude should be in [−90°, 90°] and longitude should be in [−540°, 540°).

Definition at line 288 of file Geoid.hpp.

Math::real GeographicLib::Geoid::operator() ( real  lat,
real  lon,
real &  gradn,
real &  grade 
) const
inline

Compute the geoid height and gradient at a point

Parameters
[in]latlatitude of the point (degrees).
[in]lonlongitude of the point (degrees).
[out]gradnnortherly gradient (dimensionless).
[out]gradeeasterly gradient (dimensionless).
Exceptions
GeographicErrif there's a problem reading the data; this never happens if (lat, lon) is within a successfully cached area.
Returns
geoid height (meters).

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. If you need to compute the direction of the acceleration due to gravity accurately, you should use GravityModel::Gravity.

Definition at line 312 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]latlatitude of the point (degrees).
[in]lonlongitude of the point (degrees).
[in]hheight of the point (degrees).
[in]da 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
GeographicErrif 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 331 of file Geoid.hpp.

const std::string& GeographicLib::Geoid::Description ( ) const throw ()
inline
Returns
geoid description, if available, in the data file; if absent, return "NONE".

Definition at line 346 of file Geoid.hpp.

Referenced by main().

const std::string& GeographicLib::Geoid::DateTime ( ) const throw ()
inline
Returns
date of the data file; if absent, return "UNKNOWN".

Definition at line 351 of file Geoid.hpp.

Referenced by main().

const std::string& GeographicLib::Geoid::GeoidFile ( ) const throw ()
inline
Returns
full file name used to load the geoid data.

Definition at line 356 of file Geoid.hpp.

Referenced by main().

const std::string& GeographicLib::Geoid::GeoidName ( ) const throw ()
inline
Returns
"name" used to load the geoid data (from the first argument of the constructor).

Definition at line 362 of file Geoid.hpp.

const std::string& GeographicLib::Geoid::GeoidDirectory ( ) const throw ()
inline
Returns
directory used to load the geoid data.

Definition at line 367 of file Geoid.hpp.

const std::string GeographicLib::Geoid::Interpolation ( ) const
inline
Returns
interpolation method ("cubic" or "bilinear").

Definition at line 372 of file Geoid.hpp.

Referenced by main().

Math::real GeographicLib::Geoid::MaxError ( ) const throw ()
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 382 of file Geoid.hpp.

Referenced by main().

Math::real GeographicLib::Geoid::RMSError ( ) const throw ()
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 391 of file Geoid.hpp.

Referenced by main().

Math::real GeographicLib::Geoid::Offset ( ) const throw ()
inline
Returns
offset (meters).

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

Definition at line 399 of file Geoid.hpp.

Referenced by main().

Math::real GeographicLib::Geoid::Scale ( ) const throw ()
inline
Returns
scale (meters).

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

Definition at line 407 of file Geoid.hpp.

Referenced by main().

bool GeographicLib::Geoid::ThreadSafe ( ) const throw ()
inline
Returns
true if the object is constructed to be thread safe.

Definition at line 412 of file Geoid.hpp.

bool GeographicLib::Geoid::Cache ( ) const throw ()
inline
Returns
true if a data cache is active.

Definition at line 417 of file Geoid.hpp.

Referenced by main().

Math::real GeographicLib::Geoid::CacheWest ( ) const throw ()
inline
Returns
west edge of the cached area; the cache includes this edge.

Definition at line 422 of file Geoid.hpp.

Referenced by main().

Math::real GeographicLib::Geoid::CacheEast ( ) const throw ()
inline
Returns
east edge of the cached area; the cache excludes this edge.

Definition at line 431 of file Geoid.hpp.

Referenced by main().

Math::real GeographicLib::Geoid::CacheNorth ( ) const throw ()
inline
Returns
north edge of the cached area; the cache includes this edge.

Definition at line 441 of file Geoid.hpp.

Referenced by main().

Math::real GeographicLib::Geoid::CacheSouth ( ) const throw ()
inline
Returns
south edge of the cached area; the cache excludes this edge unless it's the south pole.

Definition at line 449 of file Geoid.hpp.

Referenced by main().

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

Math::real GeographicLib::Geoid::Flattening ( ) const throw ()
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 468 of file Geoid.hpp.

std::string GeographicLib::Geoid::DefaultGeoidPath ( )
static
Returns
the default path for geoid data files.

This is the value of the environment variable 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:/Documents and Settings/All Users/Application Data/GeographicLib/geoids on Windows systems).

Definition at line 520 of file Geoid.cpp.

References GEOGRAPHICLIB_DATA.

Referenced by Geoid(), and main().

std::string GeographicLib::Geoid::DefaultGeoidName ( )
static
Returns
the default name for the geoid.

This is the value of the environment variable 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 533 of file Geoid.cpp.

References GEOID_DEFAULT_NAME.

Referenced by main().


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