GeographicLib::Geoid Class Reference

Computing the height of the geoid. More...

#include <GeographicLib/Geoid.hpp>

List of all members.

Public Member Functions

 Geoid (const std::string &name, const std::string &path="", bool cubic=true)
void CacheArea (real south, real west, real north, real east) const
void CacheAll () const
void CacheClear () const throw ()
Math::real operator() (real lat, real lon) const
Math::real operator() (real lat, real lon, real &gradn, real &grade) const
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 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 DefaultPath ()
static std::string GeoidPath ()

Detailed Description

Computing 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 not thread safe in that a single instantiation cannot be safely used by multiple threads. If multiple threads need to calculate geoid heights they should all construct thread-local instantiations.

Definition at line 51 of file Geoid.hpp.


Constructor & Destructor Documentation

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

Create a Geoid loading the data for geoid name. 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). The final cubic argument specifies whether to use bilinear (cubic = false) or cubic (cubic = true, the default) interpolation. This may throw an error because the file does not exist, is unreadable, or is corrupt.

Definition at line 200 of file Geoid.cpp.

References DefaultPath(), and GeoidPath().


Member Function Documentation

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

Cache the data for the rectangular area defined by the four arguments south, west, north, east (all in degrees). 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].

Definition at line 404 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.

Definition at line 164 of file Geoid.hpp.

References CacheArea().

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

Clear the cache. This never throws an error.

Definition at line 393 of file Geoid.cpp.

Referenced by CacheArea().

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

Return the geoid height in meters for latitude lat (in [-90, 90]) and longitude lon (in [-180,360]), both in degrees. 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.

Definition at line 178 of file Geoid.hpp.

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

Return the geoid height in meters for latitude lat (in [-90, 90]) and longitude lon (in [-180,360]), both in degrees. In addition compute the gradient of the geoid height in the northerly gradn and easterly grade directions. 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.

Definition at line 190 of file Geoid.hpp.

const std::string& GeographicLib::Geoid::Description (  )  const throw () [inline]

Return the geoid description if available in the data file. If absent, return "NONE".

Definition at line 198 of file Geoid.hpp.

const std::string& GeographicLib::Geoid::DateTime (  )  const throw () [inline]

Return the date of the data file. If absent, return "UNKNOWN".

Definition at line 203 of file Geoid.hpp.

const std::string& GeographicLib::Geoid::GeoidFile (  )  const throw () [inline]

Return the full file name used to load the geoid data.

Definition at line 208 of file Geoid.hpp.

const std::string& GeographicLib::Geoid::GeoidName (  )  const throw () [inline]

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

Definition at line 214 of file Geoid.hpp.

const std::string& GeographicLib::Geoid::GeoidDirectory (  )  const throw () [inline]

Return the directory used to load the geoid data.

Definition at line 219 of file Geoid.hpp.

const std::string GeographicLib::Geoid::Interpolation (  )  const [inline]

Return the interpolation method (cubic or bilinear).

Definition at line 224 of file Geoid.hpp.

Math::real GeographicLib::Geoid::MaxError (  )  const throw () [inline]

Return a 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 232 of file Geoid.hpp.

Math::real GeographicLib::Geoid::RMSError (  )  const throw () [inline]

Return a 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 239 of file Geoid.hpp.

Math::real GeographicLib::Geoid::Offset (  )  const throw () [inline]

Return offset (meters) for converting pixel values to geoid heights.

Definition at line 244 of file Geoid.hpp.

Math::real GeographicLib::Geoid::Scale (  )  const throw () [inline]

Return scale (meters) for converting pixel values to geoid heights.

Definition at line 250 of file Geoid.hpp.

bool GeographicLib::Geoid::Cache (  )  const throw () [inline]

Is a data cache active?

Definition at line 255 of file Geoid.hpp.

Math::real GeographicLib::Geoid::CacheWest (  )  const throw () [inline]

Return the west edge of the cached area. The cache includes this edge.

Definition at line 260 of file Geoid.hpp.

Referenced by CacheEast().

Math::real GeographicLib::Geoid::CacheEast (  )  const throw () [inline]

Return the east edge of the cached area. The cache excludes this edge.

Definition at line 269 of file Geoid.hpp.

References CacheWest().

Math::real GeographicLib::Geoid::CacheNorth (  )  const throw () [inline]

Return the north edge of the cached area. The cache includes this edge.

Definition at line 279 of file Geoid.hpp.

Math::real GeographicLib::Geoid::CacheSouth (  )  const throw () [inline]

Return the south edge of the cached area. The cache excludes this edge unless it's the south pole.

Definition at line 287 of file Geoid.hpp.

Math::real GeographicLib::Geoid::MajorRadius (  )  const throw () [inline]

The major radius of the ellipsoid (meters). This is the value for the WGS84 ellipsoid because the supported geoid models are all based on this ellipsoid.

Definition at line 296 of file Geoid.hpp.

References GeographicLib::Constants::WGS84_a().

Math::real GeographicLib::Geoid::InverseFlattening (  )  const throw () [inline]

The inverse flattening of the ellipsoid. This is the value for the WGS84 ellipsoid because the supported geoid models are all based on this ellipsoid.

Definition at line 303 of file Geoid.hpp.

References GeographicLib::Constants::WGS84_r().

std::string GeographicLib::Geoid::DefaultPath (  )  [static]

Return the compile-time default path for the geoid data files.

Definition at line 485 of file Geoid.cpp.

References GEOID_DEFAULT_PATH.

Referenced by Geoid().

std::string GeographicLib::Geoid::GeoidPath (  )  [static]

Return the value of the environment variable GEOID_PATH.

Definition at line 489 of file Geoid.cpp.

Referenced by Geoid().


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

Generated on 21 May 2010 for GeographicLib by  doxygen 1.6.1