NETGeographicLib::Geoid Class Reference

.NET wrapper for GeographicLib::Geoid. More...

#include <NETGeographicLib/Geoid.h>

List of all members.

Public Types

enum  ConvertFlag { ELLIPSOIDTOGEOID = -1, NONE = 0, GEOIDTOELLIPSOID = 1 }

Public Member Functions

Setting up the geoid



 Geoid (System::String^ name, System::String^ path, bool cubic, bool threadsafe)
 ~Geoid ()
void CacheArea (double south, double west, double north, double east)
void CacheAll ()
void CacheClear ()
Compute geoid heights



double Height (double lat, double lon)
double Height (double lat, double lon,[System::Runtime::InteropServices::Out] double% gradn,[System::Runtime::InteropServices::Out] double% grade)
double ConvertHeight (double lat, double lon, double h, ConvertFlag d)

Static Public Member Functions

static System::String^ DefaultGeoidPath ()
static System::String^ DefaultGeoidName ()

Properties

Inspector functions



System::String^  Description [get]
System::String^  DateTime [get]
System::String^  GeoidFile [get]
System::String^  GeoidName [get]
System::String^  GeoidDirectory [get]
System::String^  Interpolation [get]
double MaxError [get]
double RMSError [get]
double Offset [get]
double Scale [get]
bool ThreadSafe [get]
bool Cache [get]
double CacheWest [get]
double CacheEast [get]
double CacheNorth [get]
double CacheSouth [get]
double MajorRadius [get]
double Flattening [get]

Detailed Description

.NET wrapper for GeographicLib::Geoid.

This class allows .NET applications to access GeographicLib::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 into 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. As a result of the way that the geoid data is stored, the calculation of gradients can result in large quantization errors. This is particularly acute for fine grids, at high latitudes, and for the easterly gradient.

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.

C# Example:

using System;
using NETGeographicLib;

namespace example_Geoid
{
    class Program
    {
        static void Main(string[] args)
        {
            try {
                Geoid egm96 = new Geoid("egm96-5", "", true, false);
                // Convert height above egm96 to height above the ellipsoid
                double lat = 42, lon = -75, height_above_geoid = 20;
                double
                    geoid_height = egm96.Height(lat, lon),
                    height_above_ellipsoid = (height_above_geoid +
                        (double)Geoid.ConvertFlag.GEOIDTOELLIPSOID * geoid_height);
                Console.WriteLine(height_above_ellipsoid);
            }
            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 {
        Geoid^ egm96 = gcnew Geoid("egm96-5", "", true, false);
        // Convert height above egm96 to height above the ellipsoid
        double lat = 42, lon = -75, height_above_geoid = 20;
        double
            geoid_height = egm96->Height(lat, lon),
            height_above_ellipsoid = (height_above_geoid +
                (double)Geoid::ConvertFlag::GEOIDTOELLIPSOID * geoid_height);
        Console::WriteLine(height_above_ellipsoid);
    }
    catch (GeographicErr^ e) {
        Console::WriteLine(String::Format("Caught exception: {0}", e->Message));
        return -1;
    }
    return 0;
}

Visual Basic Example:

Imports NETGeographicLib

Module example_Geoid
    Sub Main()
        Try
            Dim egm96 As Geoid = New Geoid("egm96-5", "", True, False)
            ' Convert height above egm96 to height above the ellipsoid
            Dim lat As Double = 42, lon = -75, height_above_geoid = 20
            Dim geoid_height As Double = egm96.Height(lat, lon)
            Dim height_above_ellipsoid As Double  = (height_above_geoid +
                    CDbl(Geoid.ConvertFlag.GEOIDTOELLIPSOID) * geoid_height)
            Console.WriteLine(height_above_ellipsoid)
        Catch ex As GeographicErr
            Console.WriteLine(String.Format("Caught exception: {0}", ex.Message))
        End Try
    End Sub
End Module

INTERFACE DIFFERENCES:
The () operator has been replaced with Height method.

The following functions are implemented as properties: Description, DateTime, GeoidFile, GeoidName, GeoidDirectory, Interpolation, MaxError, RMSError, Offset, Scale, ThreadSafe, Cache, CacheWest, CacheEast, CacheNorth, CacheSouth, MajorRadius, and Flattening.

Definition at line 73 of file Geoid.h.


Member Enumeration Documentation

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 86 of file Geoid.h.


Constructor & Destructor Documentation

NETGeographicLib::Geoid::Geoid ( System::String^   name,
System::String^   path,
bool  cubic,
bool  threadsafe 
)

Construct a geoid.

Parameters:
[in] name the 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:
GeographicErr if the data file cannot be found, is unreadable, or is corrupt.
GeographicErr if 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.

Referenced by ~Geoid().

NETGeographicLib::Geoid::~Geoid (  )  [inline]

The destructor calls the finalizer.

Definition at line 132 of file Geoid.h.

References Geoid().


Member Function Documentation

void NETGeographicLib::Geoid::CacheArea ( double  south,
double  west,
double  north,
double  east 
)

Set up a cache.

Parameters:
[in] south latitude (degrees) of the south edge of the cached area.
[in] west longitude (degrees) of the west edge of the cached area.
[in] north latitude (degrees) of the north edge of the cached area.
[in] east longitude (degrees) of the east edge of the cached area.
Exceptions:
GeographicErr if 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).
GeographicErr if there's a problem reading the data.
GeographicErr if 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]; west and east should be in the range [540, 540).

void NETGeographicLib::Geoid::CacheAll (  ) 

Cache all the data.

Exceptions:
GeographicErr if 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).
GeographicErr if there's a problem reading the data.
GeographicErr if 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.

void NETGeographicLib::Geoid::CacheClear (  ) 

Clear the cache. This never throws an error. (This does nothing with a thread safe Geoid.)

double NETGeographicLib::Geoid::Height ( double  lat,
double  lon 
)

Compute the geoid height at a point

Parameters:
[in] lat latitude of the point (degrees).
[in] lon longitude of the point (degrees).
Exceptions:
GeographicErr if there's a problem reading the data; this never happens if (lat, lon) is within a successfully cached area.
Returns:
geoid height (meters).

The latitude should be in [90, 90] and longitude should be in [540, 540).

double NETGeographicLib::Geoid::Height ( double  lat,
double  lon,
[System::Runtime::InteropServices::Out] double%   gradn,
[System::Runtime::InteropServices::Out] double%   grade 
)

Compute the geoid height and gradient at a point

Parameters:
[in] lat latitude of the point (degrees).
[in] lon longitude of the point (degrees).
[out] gradn northerly gradient (dimensionless).
[out] grade easterly gradient (dimensionless).
Exceptions:
GeographicErr if there's a problem reading the data; this never happens if (lat, lon) is within a successfully cached area.
Returns:
geoid height (meters).

The latitude should be in [90, 90] and longitude should be in [540, 540). As a result of the way that the geoid data is stored, the calculation of gradients can result in large quantization errors. This is particularly acute for fine grids, at high latitudes, and for the easterly gradient. If you need to compute the direction of the acceleration due to gravity accurately, you should use GravityModel::Gravity.

double NETGeographicLib::Geoid::ConvertHeight ( double  lat,
double  lon,
double  h,
ConvertFlag  d 
)

Convert a height above the geoid to a height above the ellipsoid and vice versa.

Parameters:
[in] lat latitude of the point (degrees).
[in] lon longitude of the point (degrees).
[in] h height of the point (degrees).
[in] d a 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:
GeographicErr if there's a problem reading the data; this never happens if (lat, lon) is within a successfully cached area.
Returns:
converted height (meters).
static System::String ^ NETGeographicLib::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).

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


Property Documentation

System:: String^ NETGeographicLib::Geoid::Description [get]
Returns:
geoid description, if available, in the data file; if absent, return "NONE".

Definition at line 247 of file Geoid.h.

System:: String^ NETGeographicLib::Geoid::DateTime [get]
Returns:
date of the data file; if absent, return "UNKNOWN".

Definition at line 252 of file Geoid.h.

System:: String^ NETGeographicLib::Geoid::GeoidFile [get]
Returns:
full file name used to load the geoid data.

Definition at line 257 of file Geoid.h.

System:: String^ NETGeographicLib::Geoid::GeoidName [get]
Returns:
"name" used to load the geoid data (from the first argument of the constructor).

Definition at line 263 of file Geoid.h.

System:: String^ NETGeographicLib::Geoid::GeoidDirectory [get]
Returns:
directory used to load the geoid data.

Definition at line 268 of file Geoid.h.

System:: String^ NETGeographicLib::Geoid::Interpolation [get]
Returns:
interpolation method ("cubic" or "bilinear").

Definition at line 273 of file Geoid.h.

double NETGeographicLib::Geoid::MaxError [get]
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 282 of file Geoid.h.

double NETGeographicLib::Geoid::RMSError [get]
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 291 of file Geoid.h.

double NETGeographicLib::Geoid::Offset [get]
Returns:
offset (meters).

This in used in converting from the pixel values in the data file to geoid heights.

Definition at line 299 of file Geoid.h.

double NETGeographicLib::Geoid::Scale [get]
Returns:
scale (meters).

This in used in converting from the pixel values in the data file to geoid heights.

Definition at line 307 of file Geoid.h.

bool NETGeographicLib::Geoid::ThreadSafe [get]
Returns:
true if the object is constructed to be thread safe.

Definition at line 312 of file Geoid.h.

bool NETGeographicLib::Geoid::Cache [get]
Returns:
true if a data cache is active.

Definition at line 317 of file Geoid.h.

double NETGeographicLib::Geoid::CacheWest [get]
Returns:
west edge of the cached area; the cache includes this edge.

Definition at line 322 of file Geoid.h.

double NETGeographicLib::Geoid::CacheEast [get]
Returns:
east edge of the cached area; the cache excludes this edge.

Definition at line 327 of file Geoid.h.

double NETGeographicLib::Geoid::CacheNorth [get]
Returns:
north edge of the cached area; the cache includes this edge.

Definition at line 332 of file Geoid.h.

double NETGeographicLib::Geoid::CacheSouth [get]
Returns:
south edge of the cached area; the cache excludes this edge unless it's the south pole.

Definition at line 338 of file Geoid.h.

double NETGeographicLib::Geoid::MajorRadius [get]
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 346 of file Geoid.h.

double NETGeographicLib::Geoid::Flattening [get]
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 354 of file Geoid.h.


The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends

Generated on 6 Oct 2014 for NETGeographicLib by  doxygen 1.6.1