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

Model of the earth's gravity field. More...

#include <GravityModel.hpp>

Public Types

enum  mask {
  NONE, GRAVITY, DISTURBANCE, DISTURBING_POTENTIAL,
  SPHERICAL_ANOMALY, GEOID_HEIGHT, ALL
}
 

Public Member Functions

Setting up the gravity model
 GravityModel (const std::string &name, const std::string &path="")
 
Compute gravity in geodetic coordinates
Math::real Gravity (real lat, real lon, real h, real &gx, real &gy, real &gz) const
 
Math::real Disturbance (real lat, real lon, real h, real &deltax, real &deltay, real &deltaz) const
 
Math::real GeoidHeight (real lat, real lon) const
 
void SphericalAnomaly (real lat, real lon, real h, real &Dg01, real &xi, real &eta) const
 
Compute gravity in geocentric coordinates
Math::real W (real X, real Y, real Z, real &gX, real &gY, real &gZ) const
 
Math::real V (real X, real Y, real Z, real &GX, real &GY, real &GZ) const
 
Math::real T (real X, real Y, real Z, real &deltaX, real &deltaY, real &deltaZ) const
 
Math::real T (real X, real Y, real Z) const
 
Math::real U (real X, real Y, real Z, real &gammaX, real &gammaY, real &gammaZ) const
 
Math::real Phi (real X, real Y, real &fX, real &fY) const
 
Compute gravity on a circle of constant latitude
GravityCircle Circle (real lat, real h, unsigned caps=ALL) const
 
Inspector functions
const NormalGravityReferenceEllipsoid () const
 
const std::string & Description () const
 
const std::string & DateTime () const
 
const std::string & GravityFile () const
 
const std::string & GravityModelName () const
 
const std::string & GravityModelDirectory () const
 
Math::real MajorRadius () const
 
Math::real MassConstant () const
 
Math::real ReferenceMassConstant () const
 
Math::real AngularVelocity () const
 
Math::real Flattening () const
 

Static Public Member Functions

static std::string DefaultGravityName ()
 
static std::string DefaultGravityPath ()
 

Private Types

enum  captype {
  CAP_NONE = 0U, CAP_G = 1U<<0, CAP_T = 1U<<1, CAP_DELTA = 1U<<2 | CAP_T,
  CAP_C = 1U<<3, CAP_GAMMA0 = 1U<<4, CAP_GAMMA = 1U<<5, CAP_ALL = 0x3FU
}
 
typedef Math::real real
 

Private Member Functions

 GravityModel (const GravityModel &)
 
Math::real InternalT (real X, real Y, real Z, real &deltaX, real &deltaY, real &deltaZ, bool gradp, bool correct) const
 
GravityModeloperator= (const GravityModel &)
 
void ReadMetadata (const std::string &name)
 

Private Attributes

real _amodel
 
std::vector< real_CC
 
SphericalHarmonic _correction
 
real _corrmult
 
std::vector< real_CS
 
std::vector< real_Cx
 
std::string _date
 
std::string _description
 
std::string _dir
 
SphericalHarmonic1 _disturbing
 
real _dzonal0
 
NormalGravity _earth
 
std::string _filename
 
real _GMmodel
 
SphericalHarmonic _gravitational
 
std::string _id
 
std::string _name
 
SphericalHarmonic::normalization _norm
 
std::vector< real_Sx
 
real _zeta0
 
std::vector< real_zonal
 

Static Private Attributes

static const int idlength_ = 8
 

Friends

class GravityCircle
 

Detailed Description

Model of the earth's gravity field.

Evaluate the earth's gravity field according to a model. The supported models treat only the gravitational field exterior to the mass of the earth. When computing the field at points near (but above) the surface of the earth a small correction can be applied to account for the mass of the atmosphere above the point in question; see gravityatmos. Determining the height of the geoid above the ellipsoid entails correcting for the mass of the earth above the geoid. The egm96 and egm2008 include separate correction terms to account for this mass.

Definitions and terminology (from Heiskanen and Moritz, Sec 2-13):

See gravity for details of how to install the gravity models and the data format.

References:

Example of use:

// Example of using the GeographicLib::GravityModel class
#include <iostream>
#include <exception>
using namespace std;
using namespace GeographicLib;
int main() {
try {
GravityModel grav("egm96");
double lat = 27.99, lon = 86.93, h = 8820; // Mt Everest
double gx, gy, gz;
grav.Gravity(lat,lon, h, gx, gy, gz);
cout << gx << " " << gy << " " << gz << "\n";
}
catch (const exception& e) {
cerr << "Caught exception: " << e.what() << "\n";
return 1;
}
}

Gravity is a command-line utility providing access to the functionality of GravityModel and GravityCircle.

Definition at line 83 of file GravityModel.hpp.

Member Typedef Documentation

◆ real

Definition at line 85 of file GravityModel.hpp.

Member Enumeration Documentation

◆ captype

Enumerator
CAP_NONE 
CAP_G 
CAP_T 
CAP_DELTA 
CAP_C 
CAP_GAMMA0 
CAP_GAMMA 
CAP_ALL 

Definition at line 104 of file GravityModel.hpp.

◆ mask

Bit masks for the capabilities to be given to the GravityCircle object produced by Circle.

Enumerator
NONE 

No capabilities.

GRAVITY 

Allow calls to GravityCircle::Gravity, GravityCircle::W, and GravityCircle::V.

DISTURBANCE 

Allow calls to GravityCircle::Disturbance and GravityCircle::T.

DISTURBING_POTENTIAL 

Allow calls to GravityCircle::T(real lon) (i.e., computing the disturbing potential and not the gravity disturbance vector).

SPHERICAL_ANOMALY 

Allow calls to GravityCircle::SphericalAnomaly.

GEOID_HEIGHT 

Allow calls to GravityCircle::GeoidHeight.

ALL 

All capabilities.

Definition at line 121 of file GravityModel.hpp.

Constructor & Destructor Documentation

◆ GravityModel() [1/2]

GeographicLib::GravityModel::GravityModel ( const GravityModel )
private

◆ GravityModel() [2/2]

GeographicLib::GravityModel::GravityModel ( const std::string &  name,
const std::string &  path = "" 
)
explicit

Construct a gravity model.

Parameters
[in]namethe name of the model.
[in]path(optional) directory for data file.
Exceptions
GeographicErrif the data file cannot be found, is unreadable, or is corrupt.
std::bad_allocif the memory necessary for storing the model can't be allocated.

A filename is formed by appending ".egm" (World Gravity Model) 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 DefaultGravityPath().

This file contains the metadata which specifies the properties of the model. The coefficients for the spherical harmonic sums are obtained from a file obtained by appending ".cof" to metadata file (so the filename ends in ".egm.cof").

Definition at line 37 of file src/GravityModel.cpp.

Member Function Documentation

◆ AngularVelocity()

Math::real GeographicLib::GravityModel::AngularVelocity ( ) const
inline
Returns
ω the angular velocity of the model and the ReferenceEllipsoid() (rad s−1).

Definition at line 483 of file GravityModel.hpp.

◆ Circle()

GravityCircle GeographicLib::GravityModel::Circle ( real  lat,
real  h,
unsigned  caps = ALL 
) const

Create a GravityCircle object to allow the gravity field at many points with constant lat and h and varying lon to be computed efficiently.

Parameters
[in]latlatitude of the point (degrees).
[in]hthe height of the point above the ellipsoid (meters).
[in]capsbitor'ed combination of GravityModel::mask values specifying the capabilities of the resulting GravityCircle object.
Exceptions
std::bad_allocif the memory necessary for creating a GravityCircle can't be allocated.
Returns
a GravityCircle object whose member functions computes the gravitational field at a particular values of lon.

The GravityModel::mask values are

The default value of caps is GravityModel::ALL which turns on all the capabilities. If an unsupported function is invoked, it will return NaNs. Note that GravityModel::GEOID_HEIGHT will only be honored if h = 0.

If the field at several points on a circle of latitude need to be calculated then creating a GravityCircle object and using its member functions will be substantially faster, especially for high-degree models. See gravityparallel for an example of using GravityCircle (together with OpenMP) to speed up the computation of geoid heights.

Definition at line 307 of file src/GravityModel.cpp.

◆ DateTime()

const std::string& GeographicLib::GravityModel::DateTime ( ) const
inline
Returns
date of the model; if absent, return "UNKNOWN".

Definition at line 441 of file GravityModel.hpp.

◆ DefaultGravityName()

std::string GeographicLib::GravityModel::DefaultGravityName ( )
static
Returns
the default name for the gravity model.

This is the value of the environment variable GEOGRAPHICLIB_GRAVITY_NAME, if set; otherwise, it is "egm96". The GravityModel class does not use this function; it is just provided as a convenience for a calling program when constructing a GravityModel object.

Definition at line 354 of file src/GravityModel.cpp.

◆ DefaultGravityPath()

std::string GeographicLib::GravityModel::DefaultGravityPath ( )
static
Returns
the default path for gravity model data files.

This is the value of the environment variable GEOGRAPHICLIB_GRAVITY_PATH, if set; otherwise, it is $GEOGRAPHICLIB_DATA/gravity if the environment variable GEOGRAPHICLIB_DATA is set; otherwise, it is a compile-time default (/usr/local/share/GeographicLib/gravity on non-Windows systems and C:/ProgramData/GeographicLib/gravity on Windows systems).

Definition at line 341 of file src/GravityModel.cpp.

◆ Description()

const std::string& GeographicLib::GravityModel::Description ( ) const
inline
Returns
the description of the gravity model, if available, in the data file; if absent, return "NONE".

Definition at line 436 of file GravityModel.hpp.

◆ Disturbance()

Math::real GeographicLib::GravityModel::Disturbance ( real  lat,
real  lon,
real  h,
real deltax,
real deltay,
real deltaz 
) const

Evaluate the gravity disturbance vector at an arbitrary point above (or below) the ellipsoid.

Parameters
[in]latthe geographic latitude (degrees).
[in]lonthe geographic longitude (degrees).
[in]hthe height above the ellipsoid (meters).
[out]deltaxthe easterly component of the disturbance vector (m s−2).
[out]deltaythe northerly component of the disturbance vector (m s−2).
[out]deltazthe upward component of the disturbance vector (m s−2).
Returns
T the corresponding disturbing potential (m2 s−2).

Definition at line 297 of file src/GravityModel.cpp.

◆ Flattening()

Math::real GeographicLib::GravityModel::Flattening ( ) const
inline
Returns
f the flattening of the ellipsoid.

Definition at line 489 of file GravityModel.hpp.

◆ GeoidHeight()

Math::real GeographicLib::GravityModel::GeoidHeight ( real  lat,
real  lon 
) const

Evaluate the geoid height.

Parameters
[in]latthe geographic latitude (degrees).
[in]lonthe geographic longitude (degrees).
Returns
N the height of the geoid above the ReferenceEllipsoid() (meters).

This calls NormalGravity::U for ReferenceEllipsoid(). Some approximations are made in computing the geoid height so that the results of the NGA codes are reproduced accurately. Details are given in gravitygeoid.

Definition at line 275 of file src/GravityModel.cpp.

◆ Gravity()

Math::real GeographicLib::GravityModel::Gravity ( real  lat,
real  lon,
real  h,
real gx,
real gy,
real gz 
) const

Evaluate the gravity at an arbitrary point above (or below) the ellipsoid.

Parameters
[in]latthe geographic latitude (degrees).
[in]lonthe geographic longitude (degrees).
[in]hthe height above the ellipsoid (meters).
[out]gxthe easterly component of the acceleration (m s−2).
[out]gythe northerly component of the acceleration (m s−2).
[out]gzthe upward component of the acceleration (m s−2); this is usually negative.
Returns
W the sum of the gravitational and centrifugal potentials (m2 s−2).

The function includes the effects of the earth's rotation.

Definition at line 289 of file src/GravityModel.cpp.

◆ GravityFile()

const std::string& GeographicLib::GravityModel::GravityFile ( ) const
inline
Returns
full file name used to load the gravity model.

Definition at line 446 of file GravityModel.hpp.

◆ GravityModelDirectory()

const std::string& GeographicLib::GravityModel::GravityModelDirectory ( ) const
inline
Returns
directory used to load the gravity model.

Definition at line 457 of file GravityModel.hpp.

◆ GravityModelName()

const std::string& GeographicLib::GravityModel::GravityModelName ( ) const
inline
Returns
"name" used to load the gravity model (from the first argument of the constructor, but this may be overridden by the model file).

Definition at line 452 of file GravityModel.hpp.

◆ InternalT()

Math::real GeographicLib::GravityModel::InternalT ( real  X,
real  Y,
real  Z,
real deltaX,
real deltaY,
real deltaZ,
bool  gradp,
bool  correct 
) const
private

Definition at line 198 of file src/GravityModel.cpp.

◆ MajorRadius()

Math::real GeographicLib::GravityModel::MajorRadius ( ) const
inline
Returns
a the equatorial radius of the ellipsoid (meters).

Definition at line 462 of file GravityModel.hpp.

◆ MassConstant()

Math::real GeographicLib::GravityModel::MassConstant ( ) const
inline
Returns
GM the mass constant of the model (m3 s−2); this is the product of G the gravitational constant and M the mass of the earth (usually including the mass of the earth's atmosphere).

Definition at line 470 of file GravityModel.hpp.

◆ operator=()

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

◆ Phi()

Math::real GeographicLib::GravityModel::Phi ( real  X,
real  Y,
real fX,
real fY 
) const
inline

Evaluate the centrifugal acceleration in geocentric coordinates.

Parameters
[in]Xgeocentric coordinate of point (meters).
[in]Ygeocentric coordinate of point (meters).
[out]fXthe X component of the centrifugal acceleration (m s−2).
[out]fYthe Y component of the centrifugal acceleration (m s−2).
Returns
Φ the centrifugal potential (m2 s−2).

This calls NormalGravity::Phi for ReferenceEllipsoid().

Definition at line 381 of file GravityModel.hpp.

◆ ReadMetadata()

void GeographicLib::GravityModel::ReadMetadata ( const std::string &  name)
private

Definition at line 119 of file src/GravityModel.cpp.

◆ ReferenceEllipsoid()

const NormalGravity& GeographicLib::GravityModel::ReferenceEllipsoid ( ) const
inline
Returns
the NormalGravity object for the reference ellipsoid.

Definition at line 430 of file GravityModel.hpp.

◆ ReferenceMassConstant()

Math::real GeographicLib::GravityModel::ReferenceMassConstant ( ) const
inline
Returns
GM the mass constant of the ReferenceEllipsoid() (m3 s−2).

Definition at line 476 of file GravityModel.hpp.

◆ SphericalAnomaly()

void GeographicLib::GravityModel::SphericalAnomaly ( real  lat,
real  lon,
real  h,
real Dg01,
real xi,
real eta 
) const

Evaluate the components of the gravity anomaly vector using the spherical approximation.

Parameters
[in]latthe geographic latitude (degrees).
[in]lonthe geographic longitude (degrees).
[in]hthe height above the ellipsoid (meters).
[out]Dg01the gravity anomaly (m s−2).
[out]xithe northerly component of the deflection of the vertical (degrees).
[out]etathe easterly component of the deflection of the vertical (degrees).

The spherical approximation (see Heiskanen and Moritz, Sec 2-14) is used so that the results of the NGA codes are reproduced accurately. approximations used here. Details are given in gravitygeoid.

Definition at line 249 of file src/GravityModel.cpp.

◆ T() [1/2]

Math::real GeographicLib::GravityModel::T ( real  X,
real  Y,
real  Z,
real deltaX,
real deltaY,
real deltaZ 
) const
inline

Evaluate the components of the gravity disturbance in geocentric coordinates.

Parameters
[in]Xgeocentric coordinate of point (meters).
[in]Ygeocentric coordinate of point (meters).
[in]Zgeocentric coordinate of point (meters).
[out]deltaXthe X component of the gravity disturbance (m s−2).
[out]deltaYthe Y component of the gravity disturbance (m s−2).
[out]deltaZthe Z component of the gravity disturbance (m s−2).
Returns
T = W - U the disturbing potential (also called the anomalous potential) (m2 s−2).

Definition at line 326 of file GravityModel.hpp.

◆ T() [2/2]

Math::real GeographicLib::GravityModel::T ( real  X,
real  Y,
real  Z 
) const
inline

Evaluate disturbing potential in geocentric coordinates.

Parameters
[in]Xgeocentric coordinate of point (meters).
[in]Ygeocentric coordinate of point (meters).
[in]Zgeocentric coordinate of point (meters).
Returns
T = W - U the disturbing potential (also called the anomalous potential) (m2 s−2).

Definition at line 339 of file GravityModel.hpp.

◆ U()

Math::real GeographicLib::GravityModel::U ( real  X,
real  Y,
real  Z,
real gammaX,
real gammaY,
real gammaZ 
) const
inline

Evaluate the components of the acceleration due to normal gravity and the centrifugal acceleration in geocentric coordinates.

Parameters
[in]Xgeocentric coordinate of point (meters).
[in]Ygeocentric coordinate of point (meters).
[in]Zgeocentric coordinate of point (meters).
[out]gammaXthe X component of the normal acceleration (m s−2).
[out]gammaYthe Y component of the normal acceleration (m s−2).
[out]gammaZthe Z component of the normal acceleration (m s−2).
Returns
U = V0 + Φ the sum of the normal gravitational and centrifugal potentials (m2 s−2).

This calls NormalGravity::U for ReferenceEllipsoid().

Definition at line 363 of file GravityModel.hpp.

◆ V()

Math::real GeographicLib::GravityModel::V ( real  X,
real  Y,
real  Z,
real GX,
real GY,
real GZ 
) const

Evaluate the components of the acceleration due to gravity in geocentric coordinates.

Parameters
[in]Xgeocentric coordinate of point (meters).
[in]Ygeocentric coordinate of point (meters).
[in]Zgeocentric coordinate of point (meters).
[out]GXthe X component of the acceleration (m s−2).
[out]GYthe Y component of the acceleration (m s−2).
[out]GZthe Z component of the acceleration (m s−2).
Returns
V = W - Φ the gravitational potential (m2 s−2).

Definition at line 228 of file src/GravityModel.cpp.

◆ W()

Math::real GeographicLib::GravityModel::W ( real  X,
real  Y,
real  Z,
real gX,
real gY,
real gZ 
) const

Evaluate the components of the acceleration due to gravity and the centrifugal acceleration in geocentric coordinates.

Parameters
[in]Xgeocentric coordinate of point (meters).
[in]Ygeocentric coordinate of point (meters).
[in]Zgeocentric coordinate of point (meters).
[out]gXthe X component of the acceleration (m s−2).
[out]gYthe Y component of the acceleration (m s−2).
[out]gZthe Z component of the acceleration (m s−2).
Returns
W = V + Φ the sum of the gravitational and centrifugal potentials (m2 s−2).

This calls NormalGravity::U for ReferenceEllipsoid().

Definition at line 240 of file src/GravityModel.cpp.

Friends And Related Function Documentation

◆ GravityCircle

friend class GravityCircle
friend

Definition at line 86 of file GravityModel.hpp.

Member Data Documentation

◆ _amodel

real GeographicLib::GravityModel::_amodel
private

Definition at line 89 of file GravityModel.hpp.

◆ _CC

std::vector<real> GeographicLib::GravityModel::_CC
private

Definition at line 92 of file GravityModel.hpp.

◆ _correction

SphericalHarmonic GeographicLib::GravityModel::_correction
private

Definition at line 96 of file GravityModel.hpp.

◆ _corrmult

real GeographicLib::GravityModel::_corrmult
private

Definition at line 89 of file GravityModel.hpp.

◆ _CS

std::vector<real> GeographicLib::GravityModel::_CS
private

Definition at line 92 of file GravityModel.hpp.

◆ _Cx

std::vector<real> GeographicLib::GravityModel::_Cx
private

Definition at line 92 of file GravityModel.hpp.

◆ _date

std::string GeographicLib::GravityModel::_date
private

Definition at line 88 of file GravityModel.hpp.

◆ _description

std::string GeographicLib::GravityModel::_description
private

Definition at line 88 of file GravityModel.hpp.

◆ _dir

std::string GeographicLib::GravityModel::_dir
private

Definition at line 88 of file GravityModel.hpp.

◆ _disturbing

SphericalHarmonic1 GeographicLib::GravityModel::_disturbing
private

Definition at line 95 of file GravityModel.hpp.

◆ _dzonal0

real GeographicLib::GravityModel::_dzonal0
private

Definition at line 93 of file GravityModel.hpp.

◆ _earth

NormalGravity GeographicLib::GravityModel::_earth
private

Definition at line 91 of file GravityModel.hpp.

◆ _filename

std::string GeographicLib::GravityModel::_filename
private

Definition at line 88 of file GravityModel.hpp.

◆ _GMmodel

real GeographicLib::GravityModel::_GMmodel
private

Definition at line 89 of file GravityModel.hpp.

◆ _gravitational

SphericalHarmonic GeographicLib::GravityModel::_gravitational
private

Definition at line 94 of file GravityModel.hpp.

◆ _id

std::string GeographicLib::GravityModel::_id
private

Definition at line 88 of file GravityModel.hpp.

◆ _name

std::string GeographicLib::GravityModel::_name
private

Definition at line 88 of file GravityModel.hpp.

◆ _norm

SphericalHarmonic::normalization GeographicLib::GravityModel::_norm
private

Definition at line 90 of file GravityModel.hpp.

◆ _Sx

std::vector<real> GeographicLib::GravityModel::_Sx
private

Definition at line 92 of file GravityModel.hpp.

◆ _zeta0

real GeographicLib::GravityModel::_zeta0
private

Definition at line 89 of file GravityModel.hpp.

◆ _zonal

std::vector<real> GeographicLib::GravityModel::_zonal
private

Definition at line 92 of file GravityModel.hpp.

◆ idlength_

const int GeographicLib::GravityModel::idlength_ = 8
staticprivate

Definition at line 87 of file GravityModel.hpp.


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


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