NETGeographicLib  1.50.1
Geoid.h
Go to the documentation of this file.
1 #pragma once
2 /**
3  * \file NETGeographicLib/Geoid.h
4  * \brief Header for NETGeographicLib::Geoid class
5  *
6  * NETGeographicLib is copyright (c) Scott Heiman (2013)
7  * GeographicLib is Copyright (c) Charles Karney (2010-2012)
8  * <charles@karney.com> and licensed under the MIT/X11 License.
9  * For more information, see
10  * https://geographiclib.sourceforge.io/
11  **********************************************************************/
12 
13 namespace NETGeographicLib
14 {
15  /**
16  * \brief .NET wrapper for GeographicLib::Geoid.
17  *
18  * This class allows .NET applications to access GeographicLib::Geoid.
19  *
20  * This class evaluated the height of one of the standard geoids, EGM84,
21  * EGM96, or EGM2008 by bilinear or cubic interpolation into a rectangular
22  * grid of data. These geoid models are documented in
23  * - EGM84:
24  * http://earth-info.nga.mil/GandG/wgs84/gravitymod/wgs84_180/wgs84_180.html
25  * - EGM96:
26  * http://earth-info.nga.mil/GandG/wgs84/gravitymod/egm96/egm96.html
27  * - EGM2008:
28  * http://earth-info.nga.mil/GandG/wgs84/gravitymod/egm2008
29  *
30  * The geoids are defined in terms of spherical harmonics. However in order
31  * to provide a quick and flexible method of evaluating the geoid heights,
32  * this class evaluates the height by interpolation into a grid of
33  * precomputed values.
34  *
35  * The geoid height, \e N, can be used to convert a height above the
36  * ellipsoid, \e h, to the corresponding height above the geoid (roughly the
37  * height above mean sea level), \e H, using the relations
38  *
39  * &nbsp;&nbsp;&nbsp;\e h = \e N + \e H;
40  * &nbsp;&nbsp;\e H = &minus;\e N + \e h.
41  *
42  * See \ref geoid for details of how to install the data sets, the data
43  * format, estimates of the interpolation errors, and how to use caching.
44  *
45  * This class is typically \e not thread safe in that a single instantiation
46  * cannot be safely used by multiple threads because of the way the object
47  * reads the data set and because it maintains a single-cell cache. If
48  * multiple threads need to calculate geoid heights they should all construct
49  * thread-local instantiations. Alternatively, set the optional \e
50  * threadsafe parameter to true in the constructor. This causes the
51  * constructor to read all the data into memory and to turn off the
52  * single-cell caching which results in a Geoid object which \e is thread
53  * safe.
54  *
55  * C# Example:
56  * \include example-Geoid.cs
57  * Managed C++ Example:
58  * \include example-Geoid.cpp
59  * Visual Basic Example:
60  * \include example-Geoid.vb
61  *
62  * <B>INTERFACE DIFFERENCES:</B><BR>
63  * The () operator has been replaced with Height method.
64  *
65  * The following functions are implemented as properties:
66  * Description, DateTime, GeoidFile, GeoidName, GeoidDirectory,
67  * Interpolation, MaxError, RMSError, Offset, Scale, ThreadSafe,
68  * Cache, CacheWest, CacheEast, CacheNorth, CacheSouth, EquatorialRadius,
69  * and Flattening.
70  **********************************************************************/
71  public ref class Geoid
72  {
73  private:
74  // a pointer to the unmanaged GeographicLib::Geoid.
75  const GeographicLib::Geoid* m_pGeoid;
76 
77  // the finalizer frees hthe unmanaged memory when the object is destroyed.
78  !Geoid(void);
79  public:
80  /**
81  * Flags indicating conversions between heights above the geoid and heights
82  * above the ellipsoid.
83  **********************************************************************/
84  enum class ConvertFlag {
85  /**
86  * The multiplier for converting from heights above the geoid to heights
87  * above the ellipsoid.
88  **********************************************************************/
89  ELLIPSOIDTOGEOID = -1,
90  /**
91  * No conversion.
92  **********************************************************************/
93  NONE = 0,
94  /**
95  * The multiplier for converting from heights above the ellipsoid to
96  * heights above the geoid.
97  **********************************************************************/
98  GEOIDTOELLIPSOID = 1,
99  };
100 
101  /** \name Setting up the geoid
102  **********************************************************************/
103  ///@{
104  /**
105  * Construct a geoid.
106  *
107  * @param[in] name the name of the geoid.
108  * @param[in] path (optional) directory for data file.
109  * @param[in] cubic (optional) interpolation method; false means bilinear,
110  * true (the default) means cubic.
111  * @param[in] threadsafe (optional), if true, construct a thread safe
112  * object. The default is false
113  * @exception GeographicErr if the data file cannot be found, is
114  * unreadable, or is corrupt.
115  * @exception GeographicErr if \e threadsafe is true but the memory
116  * necessary for caching the data can't be allocated.
117  *
118  * The data file is formed by appending ".pgm" to the name. If \e path is
119  * specified (and is non-empty), then the file is loaded from directory, \e
120  * path. Otherwise the path is given by DefaultGeoidPath(). If the \e
121  * threadsafe parameter is true, the data set is read into memory, the data
122  * file is closed, and single-cell caching is turned off; this results in a
123  * Geoid object which \e is thread safe.
124  **********************************************************************/
125  Geoid(System::String^ name, System::String^ path,
126  bool cubic, bool threadsafe);
127  /**
128  * The destructor calls the finalizer.
129  **********************************************************************/
131  { this->!Geoid(); }
132 
133  /**
134  * Set up a cache.
135  *
136  * @param[in] south latitude (degrees) of the south edge of the cached area.
137  * @param[in] west longitude (degrees) of the west edge of the cached area.
138  * @param[in] north latitude (degrees) of the north edge of the cached area.
139  * @param[in] east longitude (degrees) of the east edge of the cached area.
140  * @exception GeographicErr if the memory necessary for caching the data
141  * can't be allocated (in this case, you will have no cache and can try
142  * again with a smaller area).
143  * @exception GeographicErr if there's a problem reading the data.
144  * @exception GeographicErr if this is called on a threadsafe Geoid.
145  *
146  * Cache the data for the specified "rectangular" area bounded by the
147  * parallels \e south and \e north and the meridians \e west and \e east.
148  * \e east is always interpreted as being east of \e west, if necessary by
149  * adding 360&deg; to its value. \e south and \e north should be in
150  * the range [&minus;90&deg;, 90&deg;].
151  **********************************************************************/
152  void CacheArea(double south, double west, double north, double east);
153 
154  /**
155  * Cache all the data.
156  *
157  * @exception GeographicErr if the memory necessary for caching the data
158  * can't be allocated (in this case, you will have no cache and can try
159  * again with a smaller area).
160  * @exception GeographicErr if there's a problem reading the data.
161  * @exception GeographicErr if this is called on a threadsafe Geoid.
162  *
163  * On most computers, this is fast for data sets with grid resolution of 5'
164  * or coarser. For a 1' grid, the required RAM is 450MB; a 2.5' grid needs
165  * 72MB; and a 5' grid needs 18MB.
166  **********************************************************************/
167  void CacheAll();
168 
169  /**
170  * Clear the cache. This never throws an error. (This does nothing with a
171  * thread safe Geoid.)
172  **********************************************************************/
173  void CacheClear();
174 
175  ///@}
176 
177  /** \name Compute geoid heights
178  **********************************************************************/
179  ///@{
180  /**
181  * Compute the geoid height at a point
182  *
183  * @param[in] lat latitude of the point (degrees).
184  * @param[in] lon longitude of the point (degrees).
185  * @exception GeographicErr if there's a problem reading the data; this
186  * never happens if (\e lat, \e lon) is within a successfully cached area.
187  * @return geoid height (meters).
188  *
189  * The latitude should be in [&minus;90&deg;, 90&deg;].
190  **********************************************************************/
191  double Height(double lat, double lon);
192 
193  /**
194  * Convert a height above the geoid to a height above the ellipsoid and
195  * vice versa.
196  *
197  * @param[in] lat latitude of the point (degrees).
198  * @param[in] lon longitude of the point (degrees).
199  * @param[in] h height of the point (degrees).
200  * @param[in] d a Geoid::convertflag specifying the direction of the
201  * conversion; Geoid::GEOIDTOELLIPSOID means convert a height above the
202  * geoid to a height above the ellipsoid; Geoid::ELLIPSOIDTOGEOID means
203  * convert a height above the ellipsoid to a height above the geoid.
204  * @exception GeographicErr if there's a problem reading the data; this
205  * never happens if (\e lat, \e lon) is within a successfully cached area.
206  * @return converted height (meters).
207  **********************************************************************/
208  double ConvertHeight(double lat, double lon, double h,
209  ConvertFlag d);
210 
211  ///@}
212 
213  /** \name Inspector functions
214  **********************************************************************/
215  ///@{
216  /**
217  * @return geoid description, if available, in the data file; if
218  * absent, return "NONE".
219  **********************************************************************/
220  property System::String^ Description { System::String^ get(); }
221 
222  /**
223  * @return date of the data file; if absent, return "UNKNOWN".
224  **********************************************************************/
225  property System::String^ DateTime { System::String^ get(); }
226 
227  /**
228  * @return full file name used to load the geoid data.
229  **********************************************************************/
230  property System::String^ GeoidFile { System::String^ get(); }
231 
232  /**
233  * @return "name" used to load the geoid data (from the first argument of
234  * the constructor).
235  **********************************************************************/
236  property System::String^ GeoidName { System::String^ get(); }
237 
238  /**
239  * @return directory used to load the geoid data.
240  **********************************************************************/
241  property System::String^ GeoidDirectory { System::String^ get(); }
242 
243  /**
244  * @return interpolation method ("cubic" or "bilinear").
245  **********************************************************************/
246  property System::String^ Interpolation { System::String^ get(); }
247 
248  /**
249  * @return estimate of the maximum interpolation and quantization error
250  * (meters).
251  *
252  * This relies on the value being stored in the data file. If the value is
253  * absent, return &minus;1.
254  **********************************************************************/
255  property double MaxError { double get(); }
256 
257  /**
258  * @return estimate of the RMS interpolation and quantization error
259  * (meters).
260  *
261  * This relies on the value being stored in the data file. If the value is
262  * absent, return &minus;1.
263  **********************************************************************/
264  property double RMSError { double get(); }
265 
266  /**
267  * @return offset (meters).
268  *
269  * This in used in converting from the pixel values in the data file to
270  * geoid heights.
271  **********************************************************************/
272  property double Offset { double get(); }
273 
274  /**
275  * @return scale (meters).
276  *
277  * This in used in converting from the pixel values in the data file to
278  * geoid heights.
279  **********************************************************************/
280  property double Scale { double get(); }
281 
282  /**
283  * @return true if the object is constructed to be thread safe.
284  **********************************************************************/
285  property bool ThreadSafe { bool get(); }
286 
287  /**
288  * @return true if a data cache is active.
289  **********************************************************************/
290  property bool Cache { bool get(); }
291 
292  /**
293  * @return west edge of the cached area; the cache includes this edge.
294  **********************************************************************/
295  property double CacheWest { double get(); }
296 
297  /**
298  * @return east edge of the cached area; the cache excludes this edge.
299  **********************************************************************/
300  property double CacheEast { double get(); }
301 
302  /**
303  * @return north edge of the cached area; the cache includes this edge.
304  **********************************************************************/
305  property double CacheNorth { double get(); }
306 
307  /**
308  * @return south edge of the cached area; the cache excludes this edge
309  * unless it's the south pole.
310  **********************************************************************/
311  property double CacheSouth { double get(); }
312 
313  /**
314  * @return \e a the equatorial radius of the WGS84 ellipsoid (meters).
315  *
316  * (The WGS84 value is returned because the supported geoid models are all
317  * based on this ellipsoid.)
318  **********************************************************************/
319  property double EquatorialRadius { double get(); }
320 
321  /**
322  * @return \e f the flattening of the WGS84 ellipsoid.
323  *
324  * (The WGS84 value is returned because the supported geoid models are all
325  * based on this ellipsoid.)
326  **********************************************************************/
327  property double Flattening { double get(); }
328  ///@}
329 
330  /**
331  * @return the default path for geoid data files.
332  *
333  * This is the value of the environment variable
334  * GEOGRAPHICLIB_GEOID_PATH, if set; otherwise, it is
335  * $GEOGRAPHICLIB_DATA/geoids if the environment variable
336  * GEOGRAPHICLIB_DATA is set; otherwise, it is a compile-time default
337  * (/usr/local/share/GeographicLib/geoids on non-Windows systems and
338  * C:/ProgramData/GeographicLib/geoids on Windows systems).
339  **********************************************************************/
340  static System::String^ DefaultGeoidPath();
341 
342  /**
343  * @return the default name for the geoid.
344  *
345  * This is the value of the environment variable
346  * GEOGRAPHICLIB_GEOID_NAME, if set, otherwise, it is "egm96-5". The
347  * Geoid class does not use this function; it is just provided as a
348  * convenience for a calling program when constructing a Geoid object.
349  **********************************************************************/
350  static System::String^ DefaultGeoidName();
351  };
352 } // namespace NETGeographicLib
NETGeographicLib::Geoid::GeoidDirectory
System::String^ GeoidDirectory
Definition: Geoid.h:241
NETGeographicLib::Geoid::Interpolation
System::String^ Interpolation
Definition: Geoid.h:246
NETGeographicLib::Geoid::ConvertFlag::ELLIPSOIDTOGEOID
@ ELLIPSOIDTOGEOID
NETGeographicLib::Geoid::RMSError
double RMSError
Definition: Geoid.h:264
NETGeographicLib::Geoid::ConvertHeight
double ConvertHeight(double lat, double lon, double h, ConvertFlag d)
NETGeographicLib::Geoid::Scale
double Scale
Definition: Geoid.h:280
NETGeographicLib::Geoid::CacheArea
void CacheArea(double south, double west, double north, double east)
NETGeographicLib::Geoid::Flattening
double Flattening
Definition: Geoid.h:327
NETGeographicLib::Geoid::ThreadSafe
bool ThreadSafe
Definition: Geoid.h:285
NETGeographicLib::Geoid::CacheEast
double CacheEast
Definition: Geoid.h:300
NETGeographicLib::Geoid::Height
double Height(double lat, double lon)
NETGeographicLib::Geoid
.NET wrapper for GeographicLib::Geoid.
Definition: Geoid.h:72
NETGeographicLib::Geoid::Offset
double Offset
Definition: Geoid.h:272
NETGeographicLib::Geoid::EquatorialRadius
double EquatorialRadius
Definition: Geoid.h:319
NETGeographicLib::Geoid::DateTime
System::String^ DateTime
Definition: Geoid.h:225
NETGeographicLib::Geoid::DefaultGeoidName
static System::String ^ DefaultGeoidName()
NETGeographicLib::Geoid::~Geoid
~Geoid()
Definition: Geoid.h:130
NETGeographicLib::Geoid::GeoidFile
System::String^ GeoidFile
Definition: Geoid.h:230
NETGeographicLib::Geoid::CacheSouth
double CacheSouth
Definition: Geoid.h:311
GeographicLib::Geoid
NETGeographicLib::Geoid::Description
System::String^ Description
Definition: Geoid.h:220
NETGeographicLib::Geoid::MaxError
double MaxError
Definition: Geoid.h:255
NETGeographicLib::Geoid::ConvertFlag
ConvertFlag
Definition: Geoid.h:84
NETGeographicLib::Geoid::DefaultGeoidPath
static System::String ^ DefaultGeoidPath()
NETGeographicLib::Geoid::Cache
bool Cache
Definition: Geoid.h:290
NETGeographicLib::Geoid::GeoidName
System::String^ GeoidName
Definition: Geoid.h:236
NETGeographicLib::Geoid::CacheNorth
double CacheNorth
Definition: Geoid.h:305
NETGeographicLib::Geoid::CacheWest
double CacheWest
Definition: Geoid.h:295
NETGeographicLib::Geoid::ConvertFlag::NONE
@ NONE
NETGeographicLib::Geoid::ConvertFlag::GEOIDTOELLIPSOID
@ GEOIDTOELLIPSOID
NETGeographicLib::Geoid::Geoid
Geoid(System::String^ name, System::String^ path, bool cubic, bool threadsafe)
NETGeographicLib::Geoid::CacheAll
void CacheAll()
NETGeographicLib
Definition: Accumulator.h:14
NETGeographicLib::Geoid::CacheClear
void CacheClear()