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

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
 
Geoidoperator= (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>
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

◆ pixel_t

typedef unsigned short GeographicLib::Geoid::pixel_t
private

Definition at line 86 of file Geoid.hpp.

◆ real

Definition at line 84 of file Geoid.hpp.

Member Enumeration Documentation

◆ 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

◆ Geoid() [1/2]

GeographicLib::Geoid::Geoid ( const Geoid )
private

◆ Geoid() [2/2]

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

Member Function Documentation

◆ Cache()

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

Definition at line 393 of file Geoid.hpp.

◆ CacheAll()

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.

◆ CacheArea()

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

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

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

◆ CacheEast()

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.

◆ CacheNorth()

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.

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

◆ CacheWest()

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.

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

◆ DateTime()

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.

◆ DefaultGeoidName()

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.

◆ DefaultGeoidPath()

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.

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

◆ filepos()

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

Definition at line 122 of file Geoid.hpp.

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

◆ GeoidDirectory()

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

Definition at line 343 of file Geoid.hpp.

◆ GeoidFile()

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.

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

◆ height()

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

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

◆ Interpolation()

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

Definition at line 348 of file Geoid.hpp.

◆ MajorRadius()

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.

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

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

◆ operator()()

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
the height of the geoid above the ellipsoid (meters).

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

Definition at line 288 of file Geoid.hpp.

◆ operator=()

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

◆ rawval()

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

Definition at line 131 of file Geoid.hpp.

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

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

◆ ThreadSafe()

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

◆ _a

const real GeographicLib::Geoid::_a
private

Definition at line 105 of file Geoid.hpp.

◆ _cache

bool GeographicLib::Geoid::_cache
mutableprivate

Definition at line 115 of file Geoid.hpp.

◆ _cubic

const bool GeographicLib::Geoid::_cubic
private

Definition at line 104 of file Geoid.hpp.

◆ _data

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

Definition at line 114 of file Geoid.hpp.

◆ _datastart

unsigned long long GeographicLib::Geoid::_datastart
private

Definition at line 111 of file Geoid.hpp.

◆ _datetime

std::string GeographicLib::Geoid::_datetime
private

Definition at line 108 of file Geoid.hpp.

◆ _degree

const real GeographicLib::Geoid::_degree
private

Definition at line 105 of file Geoid.hpp.

◆ _description

std::string GeographicLib::Geoid::_description
private

Definition at line 108 of file Geoid.hpp.

◆ _dir

std::string GeographicLib::Geoid::_dir
private

Definition at line 103 of file Geoid.hpp.

◆ _e2

const real GeographicLib::Geoid::_e2
private

Definition at line 105 of file Geoid.hpp.

◆ _eps

const real GeographicLib::Geoid::_eps
private

Definition at line 105 of file Geoid.hpp.

◆ _file

std::ifstream GeographicLib::Geoid::_file
mutableprivate

Definition at line 106 of file Geoid.hpp.

◆ _filename

std::string GeographicLib::Geoid::_filename
private

Definition at line 103 of file Geoid.hpp.

◆ _height

int GeographicLib::Geoid::_height
private

Definition at line 110 of file Geoid.hpp.

◆ _ix

int GeographicLib::Geoid::_ix
mutableprivate

Definition at line 119 of file Geoid.hpp.

◆ _iy

int GeographicLib::Geoid::_iy
mutableprivate

Definition at line 119 of file Geoid.hpp.

◆ _maxerror

real GeographicLib::Geoid::_maxerror
private

Definition at line 109 of file Geoid.hpp.

◆ _name

std::string GeographicLib::Geoid::_name
private

Definition at line 103 of file Geoid.hpp.

◆ _offset

real GeographicLib::Geoid::_offset
private

Definition at line 109 of file Geoid.hpp.

◆ _rlatres

real GeographicLib::Geoid::_rlatres
private

Definition at line 107 of file Geoid.hpp.

◆ _rlonres

real GeographicLib::Geoid::_rlonres
private

Definition at line 107 of file Geoid.hpp.

◆ _rmserror

real GeographicLib::Geoid::_rmserror
private

Definition at line 109 of file Geoid.hpp.

◆ _scale

real GeographicLib::Geoid::_scale
private

Definition at line 109 of file Geoid.hpp.

◆ _swidth

unsigned long long GeographicLib::Geoid::_swidth
private

Definition at line 111 of file Geoid.hpp.

◆ _t

real GeographicLib::Geoid::_t[nterms_]
mutableprivate

Definition at line 121 of file Geoid.hpp.

◆ _threadsafe

bool GeographicLib::Geoid::_threadsafe
private

Definition at line 112 of file Geoid.hpp.

◆ _v00

real GeographicLib::Geoid::_v00
mutableprivate

Definition at line 120 of file Geoid.hpp.

◆ _v01

real GeographicLib::Geoid::_v01
mutableprivate

Definition at line 120 of file Geoid.hpp.

◆ _v10

real GeographicLib::Geoid::_v10
mutableprivate

Definition at line 120 of file Geoid.hpp.

◆ _v11

real GeographicLib::Geoid::_v11
mutableprivate

Definition at line 120 of file Geoid.hpp.

◆ _width

int GeographicLib::Geoid::_width
private

Definition at line 110 of file Geoid.hpp.

◆ _xoffset

int GeographicLib::Geoid::_xoffset
mutableprivate

Definition at line 117 of file Geoid.hpp.

◆ _xsize

int GeographicLib::Geoid::_xsize
mutableprivate

Definition at line 117 of file Geoid.hpp.

◆ _yoffset

int GeographicLib::Geoid::_yoffset
mutableprivate

Definition at line 117 of file Geoid.hpp.

◆ _ysize

int GeographicLib::Geoid::_ysize
mutableprivate

Definition at line 117 of file Geoid.hpp.

◆ c0_

const int GeographicLib::Geoid::c0_ = 240
staticprivate

Definition at line 96 of file Geoid.hpp.

◆ c0n_

const int GeographicLib::Geoid::c0n_ = 372
staticprivate

Definition at line 97 of file Geoid.hpp.

◆ c0s_

const int GeographicLib::Geoid::c0s_ = 372
staticprivate

Definition at line 98 of file Geoid.hpp.

◆ c3_

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.

◆ c3n_

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.

◆ c3s_

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.

◆ nterms_

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

Definition at line 95 of file Geoid.hpp.

◆ pixel_max_

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

Definition at line 88 of file Geoid.hpp.

◆ pixel_size_

const unsigned GeographicLib::Geoid::pixel_size_ = 2
staticprivate

Definition at line 87 of file Geoid.hpp.

◆ stencilsize_

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:


gtsam
Author(s):
autogenerated on Tue Jul 4 2023 02:46:12