NETGeographicLib::GravityModel Class Reference

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

#include <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
GravityCircle	Circle (double lat, double h, Mask caps)

Static Public Member Functions
static System::String	DefaultGravityName ()
static System::String	DefaultGravityPath ()

Private Types
enum	CapType {   CapType::CAP_NONE = 0U, CapType::CAP_G = 1U<<0, CapType::CAP_T = 1U<<1, CapType::CAP_DELTA = 1U<<2 | CapType::CAP_T,   CapType::CAP_C = 1U<<3, CapType::CAP_GAMMA0 = 1U<<4, CapType::CAP_GAMMA = 1U<<5, CapType::CAP_ALL = 0x3FU }

Private Member Functions
	!GravityModel (void)

Private Attributes
const GeographicLib::GravityModel *	m_pGravityModel

Inspector functions
property System::String	Description { System::String^ get()
property System::String	DateTime { System::String^ get()
property System::String	GravityFile { System::String^ get()
property System::String	GravityModelName { System::String^ get()
property System::String	GravityModelDirectory { System::String^ get()
property double	MajorRadius { double get()
property double	MassConstant { double get()
property double	ReferenceMassConstant { double get()
property double	AngularVelocity { double get()
property double	Flattening { double get()
NormalGravity	ReferenceEllipsoid ()

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

• V = gravitational potential;
• Φ = rotational potential;
• W = V + Φ = T + U = total potential;
• V₀ = normal gravitation potential;
• U = V₀ + Φ = total normal potential;
• T = W − U = V − V₀ = anomalous or disturbing potential;
• g = ∇W = γ + δ;
• f = ∇Φ;
• Γ = ∇V₀;
• γ = ∇U;
• δ = ∇T = gravity disturbance vector = g_P − γ_P;
• δg = gravity disturbance = g_P − γ_P;
• Δg = gravity anomaly vector = g_P − γ_Q; here the line PQ is perpendicular to ellipsoid and the potential at P equals the normal potential at Q;
• Δg = gravity anomaly = g_P − γ_Q;
• (ξ, η) deflection of the vertical, the difference in directions of g_P and γ_Q, ξ = NS, η = EW.
• X, Y, Z, geocentric coordinates;
• x, y, z, local cartesian coordinates used to denote the east, north and up directions.

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

References:

• W. A. Heiskanen and H. Moritz, Physical Geodesy (Freeman, San Francisco, 1967).

C# Example:

using System;
using NETGeographicLib;

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:

// Example of using the GeographicLib::GravityModel class

#include <iostream>
#include <exception>
#include <GeographicLib/GravityModel.hpp>

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;
  }
}

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

enum NETGeographicLib::GravityModel::CapType

strongprivate

Enumerator
CAP_NONE
CAP_G
CAP_T
CAP_DELTA
CAP_C
CAP_GAMMA0
CAP_GAMMA
CAP_ALL

Definition at line 92 of file GravityModel.h.

enum NETGeographicLib::GravityModel::Mask

strong

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

GravityModel::!GravityModel ( void  )

private

Definition at line 22 of file dotnet/NETGeographicLib/GravityModel.cpp.

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

Construct a gravity model.

Parameters

[in]	name	the name of the model.
[in]	path	(optional) directory for data file.

Exceptions

GeographicErr	if the data file cannot be found, is unreadable, or is corrupt.
std::bad_alloc	if 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 32 of file dotnet/NETGeographicLib/GravityModel.cpp.

NETGeographicLib::GravityModel::~GravityModel ( )

inline

The destructor calls the finalizer.

Definition at line 177 of file GravityModel.h.

Member Function Documentation

GravityCircle 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]	lat	latitude of the point (degrees).
[in]	h	the height of the point above the ellipsoid (meters).
[in]	caps	bitor'ed combination of GravityModel::mask values specifying the capabilities of the resulting GravityCircle object.

Exceptions

std::bad_alloc

if 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 gravityparallel for an example of using GravityCircle (together with OpenMP) to speed up the computation of geoid heights.

Definition at line 174 of file dotnet/NETGeographicLib/GravityModel.cpp.

System::String 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 230 of file dotnet/NETGeographicLib/GravityModel.cpp.

System::String 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 217 of file dotnet/NETGeographicLib/GravityModel.cpp.

double 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]	lat	the geographic latitude (degrees).
[in]	lon	the geographic longitude (degrees).
[in]	h	the height above the ellipsoid (meters).
[out]	deltax	the easterly component of the disturbance vector (m s−2).
[out]	deltay	the northerly component of the disturbance vector (m s−2).
[out]	deltaz	the upward component of the disturbance vector (m s−2).

Returns

T the corresponding disturbing potential.

Definition at line 67 of file dotnet/NETGeographicLib/GravityModel.cpp.

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

Evaluate the geoid height.

Parameters

[in]	lat	the geographic latitude (degrees).
[in]	lon	the 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 81 of file dotnet/NETGeographicLib/GravityModel.cpp.

double 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]	lat	the geographic latitude (degrees).
[in]	lon	the geographic longitude (degrees).
[in]	h	the height above the ellipsoid (meters).
[out]	gx	the easterly component of the acceleration (m s−2).
[out]	gy	the northerly component of the acceleration (m s−2).
[out]	gz	the 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.

Definition at line 53 of file dotnet/NETGeographicLib/GravityModel.cpp.

double 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]	X	geocentric coordinate of point (meters).
[in]	Y	geocentric coordinate of point (meters).
[out]	fX	the X component of the centrifugal acceleration (m s−2).
[out]	fY	the Y component of the centrifugal acceleration (m s−2).

Returns

Φ the centrifugal potential (m² s⁻²).

This calls NormalGravity::Phi for ReferenceEllipsoid().

Definition at line 162 of file dotnet/NETGeographicLib/GravityModel.cpp.

NormalGravity GravityModel::ReferenceEllipsoid

(

)

Returns

the NormalGravity object for the reference ellipsoid.

Definition at line 243 of file dotnet/NETGeographicLib/GravityModel.cpp.

void 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]	lat	the geographic latitude (degrees).
[in]	lon	the geographic longitude (degrees).
[in]	h	the height above the ellipsoid (meters).
[out]	Dg01	the gravity anomaly (m s−2).
[out]	xi	the northerly component of the deflection of the vertical (degrees).
[out]	eta	the 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 87 of file dotnet/NETGeographicLib/GravityModel.cpp.

double 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]	X	geocentric coordinate of point (meters).
[in]	Y	geocentric coordinate of point (meters).
[in]	Z	geocentric coordinate of point (meters).
[out]	deltaX	the X component of the gravity disturbance (m s−2).
[out]	deltaY	the Y component of the gravity disturbance (m s−2).
[out]	deltaZ	the Z component of the gravity disturbance (m s−2).

Returns

T = W - U the disturbing potential (also called the anomalous potential) (m² s⁻²).

Definition at line 128 of file dotnet/NETGeographicLib/GravityModel.cpp.

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

Evaluate disturbing potential in geocentric coordinates.

Parameters

[in]	X	geocentric coordinate of point (meters).
[in]	Y	geocentric coordinate of point (meters).
[in]	Z	geocentric coordinate of point (meters).

Returns

T = W - U the disturbing potential (also called the anomalous potential) (m² s⁻²).

Definition at line 142 of file dotnet/NETGeographicLib/GravityModel.cpp.

double 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]	X	geocentric coordinate of point (meters).
[in]	Y	geocentric coordinate of point (meters).
[in]	Z	geocentric coordinate of point (meters).
[out]	gammaX	the X component of the normal acceleration (m s−2).
[out]	gammaY	the Y component of the normal acceleration (m s−2).
[out]	gammaZ	the Z component of the normal acceleration (m s−2).

Returns

U = V₀ + Φ the sum of the normal gravitational and centrifugal potentials (m² s⁻²).

This calls NormalGravity::U for ReferenceEllipsoid().

Definition at line 148 of file dotnet/NETGeographicLib/GravityModel.cpp.

double 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]	X	geocentric coordinate of point (meters).
[in]	Y	geocentric coordinate of point (meters).
[in]	Z	geocentric coordinate of point (meters).
[out]	GX	the X component of the acceleration (m s−2).
[out]	GY	the Y component of the acceleration (m s−2).
[out]	GZ	the Z component of the acceleration (m s−2).

Returns

V = W - Φ the gravitational potential (m² s⁻²).

Definition at line 114 of file dotnet/NETGeographicLib/GravityModel.cpp.

double 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]	X	geocentric coordinate of point (meters).
[in]	Y	geocentric coordinate of point (meters).
[in]	Z	geocentric coordinate of point (meters).
[out]	gX	the X component of the acceleration (m s−2).
[out]	gY	the Y component of the acceleration (m s−2).
[out]	gZ	the Z component of the acceleration (m s−2).

Returns

W = V + Φ the sum of the gravitational and centrifugal potentials (m² s⁻²).

This calls NormalGravity::U for ReferenceEllipsoid().

Definition at line 100 of file dotnet/NETGeographicLib/GravityModel.cpp.

Member Data Documentation

property double NETGeographicLib::GravityModel::AngularVelocity { double get()

Returns

ω the angular velocity of the model and the ReferenceEllipsoid() (rad s⁻¹).

Definition at line 483 of file GravityModel.h.

property System::String NETGeographicLib::GravityModel::DateTime { System::String^ get()

Returns

date of the model; if absent, return "UNKNOWN".

Definition at line 441 of file GravityModel.h.

property System::String NETGeographicLib::GravityModel::Description { System::String^ 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.

property double NETGeographicLib::GravityModel::Flattening { double get()

Returns

f the flattening of the ellipsoid.

Definition at line 488 of file GravityModel.h.

property System::String NETGeographicLib::GravityModel::GravityFile { System::String^ get()

Returns

full file name used to load the gravity model.

Definition at line 446 of file GravityModel.h.

property System::String NETGeographicLib::GravityModel::GravityModelDirectory { System::String^ get()

Returns

directory used to load the gravity model.

Definition at line 458 of file GravityModel.h.

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

const GeographicLib::GravityModel* NETGeographicLib::GravityModel::m_pGravityModel

private

Definition at line 87 of file GravityModel.h.

property double NETGeographicLib::GravityModel::MajorRadius { double get()

Returns

a the equatorial radius of the ellipsoid (meters).

Definition at line 463 of file GravityModel.h.

property double NETGeographicLib::GravityModel::MassConstant { double get()

Returns

GM the mass constant of the model (m³ s⁻²); 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.

property double NETGeographicLib::GravityModel::ReferenceMassConstant { double get()

Returns

GM the mass constant of the ReferenceEllipsoid() (m³ s⁻²).

Definition at line 477 of file GravityModel.h.

---

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

• GravityModel.h
• dotnet/NETGeographicLib/GravityModel.cpp