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 | InverseFlattening () const throw () |
Static Public Member Functions | |
static std::string | DefaultGeoidPath () |
static std::string | DefaultGeoidName () |
static std::string | DefaultPath () |
static std::string | GeoidPath () |
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 inot 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.
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 constuctor. 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.
Definition at line 58 of file Geoid.hpp.
Flags indicating conversions between heights above the geoid and heights above the ellipsoid.
GeographicLib::Geoid::Geoid | ( | const std::string & | name, | |
const std::string & | path = "" , |
|||
bool | cubic = true , |
|||
bool | threadsafe = false | |||
) | [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 |
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 the GEOID_PATH environment variable. If that is undefined, a compile-time default path is used (/usr/local/share/GeographicLib/geoids on non-Windows systems and C:/cygwin/usr/local/share/GeographicLib/geoids on Windows systems). This may throw an exception because the file does not exist, is unreadable, or is corrupt. If the threadsafe parameter is true, the data set is read into memory (which this may also cause an exception to be thrown), 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 204 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. |
Cache the data for the specified rectangular area . east is always interpreted as being east of west, if necessary by adding 360o to its value. This may throw an error because of insufficent memory or because of an error reading the data from the file. In this case, you can catch the error and either do nothing (you will have no cache in this case) or try again with a smaller area. south and north should be in the range [-90, 90]; west and east should be in the range [-180, 360]. An exception is thrown if this routine is called on a thread safe Geoid.
Definition at line 443 of file Geoid.cpp.
References CacheClear().
Referenced by CacheAll().
void GeographicLib::Geoid::CacheAll | ( | ) | const [inline] |
Cache all the data. 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. This may throw an error because of insufficent memory or because of an error reading the data from the file. In this case, you can catch the error and either do nothing (you will have no cache in this case) or try using Geoid::CacheArea on a specific area. An exception is thrown if this routine is called on a thread safe Geoid.
Definition at line 215 of file Geoid.hpp.
References CacheArea().
Referenced by Geoid().
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 430 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
[in] | lat | latitude of the point (degrees). |
[in] | lon | longitude of the point (degrees). |
The latitude should be in [-90, 90] and longitude should bein [-180,360]. This may throw an error because of an error reading data from disk. However, it will not throw if (lat, lon) is within a successfully cached area.
Math::real GeographicLib::Geoid::operator() | ( | real | lat, | |
real | lon, | |||
real & | gradn, | |||
real & | grade | |||
) | const [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). |
The latitude should be in [-90, 90] and longitude should be in [-180, 360]. This may throw an error because of an error reading data from disk. However, it will not throw if (lat, lon) is within a successfully cached area.
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.
[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. |
const std::string& GeographicLib::Geoid::Description | ( | ) | const throw () [inline] |
const std::string& GeographicLib::Geoid::DateTime | ( | ) | const throw () [inline] |
const std::string& GeographicLib::Geoid::GeoidFile | ( | ) | const throw () [inline] |
const std::string& GeographicLib::Geoid::GeoidName | ( | ) | const throw () [inline] |
const std::string& GeographicLib::Geoid::GeoidDirectory | ( | ) | const throw () [inline] |
const std::string GeographicLib::Geoid::Interpolation | ( | ) | const [inline] |
Math::real GeographicLib::Geoid::MaxError | ( | ) | const throw () [inline] |
Math::real GeographicLib::Geoid::RMSError | ( | ) | const throw () [inline] |
Math::real GeographicLib::Geoid::Offset | ( | ) | const throw () [inline] |
Math::real GeographicLib::Geoid::Scale | ( | ) | const throw () [inline] |
bool GeographicLib::Geoid::ThreadSafe | ( | ) | const throw () [inline] |
bool GeographicLib::Geoid::Cache | ( | ) | const throw () [inline] |
Math::real GeographicLib::Geoid::CacheWest | ( | ) | const throw () [inline] |
Definition at line 368 of file Geoid.hpp.
Referenced by CacheEast().
Math::real GeographicLib::Geoid::CacheEast | ( | ) | const throw () [inline] |
Definition at line 377 of file Geoid.hpp.
References CacheWest().
Math::real GeographicLib::Geoid::CacheNorth | ( | ) | const throw () [inline] |
Math::real GeographicLib::Geoid::CacheSouth | ( | ) | const throw () [inline] |
Math::real GeographicLib::Geoid::MajorRadius | ( | ) | const throw () [inline] |
Math::real GeographicLib::Geoid::InverseFlattening | ( | ) | const throw () [inline] |
std::string GeographicLib::Geoid::DefaultGeoidPath | ( | ) | [static] |
This is the value of the environment variable GEOID_PATH, if set, otherwise, it is a compile-time default.
Definition at line 538 of file Geoid.cpp.
References GEOID_DEFAULT_PATH.
Referenced by Geoid().
std::string GeographicLib::Geoid::DefaultGeoidName | ( | ) | [static] |
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 546 of file Geoid.cpp.
References GEOID_DEFAULT_NAME.
Referenced by main().
std::string GeographicLib::Geoid::DefaultPath | ( | ) | [static] |
DEPRECATED Return the compile-time default path for the geoid data files.
Definition at line 526 of file Geoid.cpp.
References GEOID_DEFAULT_PATH.
std::string GeographicLib::Geoid::GeoidPath | ( | ) | [static] |