NETGeographicLib  1.43
Public Types | Public Member Functions | Static Public Member Functions | List of all members
NETGeographicLib::GravityModel Class Reference

.NET wrapper for GeographicLib::GravityModel. More...

#include <NETGeographicLib/GravityModel.h>

Public Types

enum  Mask {
  Mask::NONE, Mask::GRAVITY, Mask::DISTURBANCE, Mask::DISTURBING_POTENTIAL,
  Mask::SPHERICAL_ANOMALY, Mask::GEOID_HEIGHT, Mask::ALL
}
 

Public Member Functions

 ~GravityModel ()
 
Setting up the gravity model
 GravityModel (System::String^ name, System::String^ path)
 
Compute gravity in geodetic coordinates
double Gravity (double lat, double lon, double h, [System::Runtime::InteropServices::Out] double% gx, [System::Runtime::InteropServices::Out] double% gy, [System::Runtime::InteropServices::Out] double% gz)
 
double Disturbance (double lat, double lon, double h, [System::Runtime::InteropServices::Out] double% deltax, [System::Runtime::InteropServices::Out] double% deltay, [System::Runtime::InteropServices::Out] double% deltaz)
 
double GeoidHeight (double lat, double lon)
 
void SphericalAnomaly (double lat, double lon, double h, [System::Runtime::InteropServices::Out] double% Dg01, [System::Runtime::InteropServices::Out] double% xi, [System::Runtime::InteropServices::Out] double% eta)
 
Compute gravity in geocentric coordinates
double W (double X, double Y, double Z, [System::Runtime::InteropServices::Out] double% gX, [System::Runtime::InteropServices::Out] double% gY, [System::Runtime::InteropServices::Out] double% gZ)
 
double V (double X, double Y, double Z, [System::Runtime::InteropServices::Out] double% GX, [System::Runtime::InteropServices::Out] double% GY, [System::Runtime::InteropServices::Out] double% GZ)
 
double T (double X, double Y, double Z, [System::Runtime::InteropServices::Out] double% deltaX, [System::Runtime::InteropServices::Out] double% deltaY, [System::Runtime::InteropServices::Out] double% deltaZ)
 
double T (double X, double Y, double Z)
 
double U (double X, double Y, double Z, [System::Runtime::InteropServices::Out] double% gammaX, [System::Runtime::InteropServices::Out] double% gammaY, [System::Runtime::InteropServices::Out] double% gammaZ)
 
double Phi (double X, double Y, [System::Runtime::InteropServices::Out] double% fX, [System::Runtime::InteropServices::Out] double% fY)
 
Compute gravity on a circle of constant latitude
GravityCircleCircle (double lat, double h, Mask caps)
 

Static Public Member Functions

static System::String^ DefaultGravityPath ()
 
static System::String^ DefaultGravityName ()
 

Inspector functions

System::String^  Description [get]
 
System::String^  DateTime [get]
 
System::String^  GravityFile [get]
 
System::String^  GravityModelName [get]
 
System::String^  GravityModelDirectory [get]
 
double MajorRadius [get]
 
double MassConstant [get]
 
double ReferenceMassConstant [get]
 
double AngularVelocity [get]
 
double Flattening [get]
 
NormalGravityReferenceEllipsoid ()
 

Detailed Description

.NET wrapper for GeographicLib::GravityModel.

This class allows .NET applications to access GeographicLib::GravityModel.

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 atomsphere above the point in question; see The effect of the mass of the atmosphere. Determining the geoid height 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 models for details of how to install the gravity model and the data format.

References:

C# Example:

using System;
namespace example_GravityModel
{
class Program
{
static void Main(string[] args)
{
try {
GravityModel grav = new GravityModel("egm96","");
double lat = 27.99, lon = 86.93, h = 8820; // Mt Everest
double gx, gy, gz;
grav.Gravity(lat, lon, h, out gx, out gy, out gz);
Console.WriteLine(String.Format("{0} {1} {2}", gx, gy, gz));
}
catch (GeographicErr e) {
Console.WriteLine(String.Format("Caught exception: {0}", e.Message));
}
}
}
}

Managed C++ Example:

using namespace System;
using namespace NETGeographicLib;
int main(array<System::String ^> ^/*args*/)
{
try {
GravityModel^ grav = gcnew GravityModel("egm96","");
double lat = 27.99, lon = 86.93, h = 8820; // Mt Everest
double gx, gy, gz;
grav->Gravity(lat, lon, h, gx, gy, gz);
Console::WriteLine(String::Format("{0} {1} {2}", gx, gy, gz));
}
catch (GeographicErr^ e) {
Console::WriteLine(String::Format("Caught exception: {0}", e->Message));
return -1;
}
return 0;
}

Visual Basic Example:

Imports NETGeographicLib
Module example_GravityModel
Sub Main()
Try
Dim grav As GravityModel = New GravityModel("egm96", "")
Dim lat As Double = 27.99, lon = 86.93, h = 8820 ' Mt Everest
Dim gx, gy, gz As Double
grav.Gravity(lat, lon, h, gx, gy, gz)
Console.WriteLine(String.Format("{0} {1} {2}", gx, gy, gz))
Catch ex As GeographicErr
Console.WriteLine(String.Format("Caught exception: {0}", ex.Message))
End Try
End Sub
End Module

INTERFACE DIFFERENCES:
The following functions are implemented as properties: Description, DateTime, GravityFile, GravityModelName, GravityModelDirectory, MajorRadius, MassConstant, ReferenceMassConstant, AngularVelocity, and Flattening.

The Circle function accepts the "capabilities mask" as a NETGeographicLib::GravityModel::Mask rather than an unsigned.

Definition at line 83 of file GravityModel.h.

Member Enumeration Documentation

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(double 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 109 of file GravityModel.h.

Constructor & Destructor Documentation

NETGeographicLib::GravityModel::GravityModel ( System::String^  name,
System::String^  path 
)

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").

Referenced by ~GravityModel().

NETGeographicLib::GravityModel::~GravityModel ( )
inline

The destructor calls the finalizer.

Definition at line 177 of file GravityModel.h.

References Circle(), Disturbance(), GeoidHeight(), Gravity(), GravityModel(), Phi(), ReferenceEllipsoid(), SphericalAnomaly(), T(), U(), V(), and W().

Member Function Documentation

double NETGeographicLib::GravityModel::Gravity ( double  lat,
double  lon,
double  h,
[System::Runtime::InteropServices::Out] double%  gx,
[System::Runtime::InteropServices::Out] double%  gy,
[System::Runtime::InteropServices::Out] double%  gz 
)

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.

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

Referenced by ~GravityModel().

double NETGeographicLib::GravityModel::Disturbance ( double  lat,
double  lon,
double  h,
[System::Runtime::InteropServices::Out] double%  deltax,
[System::Runtime::InteropServices::Out] double%  deltay,
[System::Runtime::InteropServices::Out] double%  deltaz 
)

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.

Referenced by ~GravityModel().

double NETGeographicLib::GravityModel::GeoidHeight ( double  lat,
double  lon 
)

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 Details of the geoid height and anomaly calculations.

Referenced by ~GravityModel().

void NETGeographicLib::GravityModel::SphericalAnomaly ( double  lat,
double  lon,
double  h,
[System::Runtime::InteropServices::Out] double%  Dg01,
[System::Runtime::InteropServices::Out] double%  xi,
[System::Runtime::InteropServices::Out] double%  eta 
)

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 Details of the geoid height and anomaly calculations.

Referenced by ~GravityModel().

double NETGeographicLib::GravityModel::W ( double  X,
double  Y,
double  Z,
[System::Runtime::InteropServices::Out] double%  gX,
[System::Runtime::InteropServices::Out] double%  gY,
[System::Runtime::InteropServices::Out] double%  gZ 
)

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().

Referenced by ~GravityModel().

double NETGeographicLib::GravityModel::V ( double  X,
double  Y,
double  Z,
[System::Runtime::InteropServices::Out] double%  GX,
[System::Runtime::InteropServices::Out] double%  GY,
[System::Runtime::InteropServices::Out] double%  GZ 
)

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).

Referenced by ~GravityModel().

double NETGeographicLib::GravityModel::T ( double  X,
double  Y,
double  Z,
[System::Runtime::InteropServices::Out] double%  deltaX,
[System::Runtime::InteropServices::Out] double%  deltaY,
[System::Runtime::InteropServices::Out] double%  deltaZ 
)

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).

Referenced by ~GravityModel().

double NETGeographicLib::GravityModel::T ( double  X,
double  Y,
double  Z 
)

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).
double NETGeographicLib::GravityModel::U ( double  X,
double  Y,
double  Z,
[System::Runtime::InteropServices::Out] double%  gammaX,
[System::Runtime::InteropServices::Out] double%  gammaY,
[System::Runtime::InteropServices::Out] double%  gammaZ 
)

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().

Referenced by ~GravityModel().

double NETGeographicLib::GravityModel::Phi ( double  X,
double  Y,
[System::Runtime::InteropServices::Out] double%  fX,
[System::Runtime::InteropServices::Out] double%  fY 
)

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().

Referenced by ~GravityModel().

GravityCircle ^ NETGeographicLib::GravityModel::Circle ( double  lat,
double  h,
Mask  caps 
)

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

  • caps |= GravityModel::GRAVITY
  • caps |= GravityModel::DISTURBANCE
  • caps |= GravityModel::DISTURBING_POTENTIAL
  • caps |= GravityModel::SPHERICAL_ANOMALY
  • caps |= GravityModel::GEOID_HEIGHT

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 Geoid heights on a multi-processor system for an example of using GravityCircle (together with OpenMP) to speed up the computation of geoid heights.

Referenced by ~GravityModel().

NormalGravity ^ NETGeographicLib::GravityModel::ReferenceEllipsoid ( )
Returns
the NormalGravity object for the reference ellipsoid.

Referenced by ~GravityModel().

static System::String ^ NETGeographicLib::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).

static System::String ^ NETGeographicLib::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.

Property Documentation

System:: String^ NETGeographicLib::GravityModel::Description
get
Returns
the description of the gravity model, if available, in the data file; if absent, return "NONE".

Definition at line 436 of file GravityModel.h.

System:: String^ NETGeographicLib::GravityModel::DateTime
get
Returns
date of the model; if absent, return "UNKNOWN".

Definition at line 441 of file GravityModel.h.

System:: String^ NETGeographicLib::GravityModel::GravityFile
get
Returns
full file name used to load the gravity model.

Definition at line 446 of file GravityModel.h.

System:: String^ NETGeographicLib::GravityModel::GravityModelName
get
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.h.

System:: String^ NETGeographicLib::GravityModel::GravityModelDirectory
get
Returns
directory used to load the gravity model.

Definition at line 457 of file GravityModel.h.

double NETGeographicLib::GravityModel::MajorRadius
get
Returns
a the equatorial radius of the ellipsoid (meters).

Definition at line 463 of file GravityModel.h.

double NETGeographicLib::GravityModel::MassConstant
get
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 471 of file GravityModel.h.

double NETGeographicLib::GravityModel::ReferenceMassConstant
get
Returns
GM the mass constant of the ReferenceEllipsoid() (m3 s−2).

Definition at line 477 of file GravityModel.h.

double NETGeographicLib::GravityModel::AngularVelocity
get
Returns
ω the angular velocity of the model and the ReferenceEllipsoid() (rad s−1).

Definition at line 483 of file GravityModel.h.

double NETGeographicLib::GravityModel::Flattening
get
Returns
f the flattening of the ellipsoid.

Definition at line 488 of file GravityModel.h.


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