NETGeographicLib  1.43
GravityModel.h
Go to the documentation of this file.
1 #pragma once
2 /**
3  * \file NETGeographicLib/GravityModel.h
4  * \brief Header for NETGeographicLib::GravityModel 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  * http://geographiclib.sourceforge.net/
11  **********************************************************************/
12 
13 namespace NETGeographicLib
14 {
15  ref class GravityCircle;
16  ref class NormalGravity;
17  /**
18  * \brief .NET wrapper for GeographicLib::GravityModel.
19  *
20  * This class allows .NET applications to access GeographicLib::GravityModel.
21  *
22  * Evaluate the earth's gravity field according to a model. The supported
23  * models treat only the gravitational field exterior to the mass of the
24  * earth. When computing the field at points near (but above) the surface of
25  * the earth a small correction can be applied to account for the mass of the
26  * atomsphere above the point in question; see \ref gravityatmos.
27  * Determining the geoid height entails correcting for the mass of the earth
28  * above the geoid. The egm96 and egm2008 include separate correction terms
29  * to account for this mass.
30  *
31  * Definitions and terminology (from Heiskanen and Moritz, Sec 2-13):
32  * - \e V = gravitational potential;
33  * - &Phi; = rotational potential;
34  * - \e W = \e V + &Phi; = \e T + \e U = total potential;
35  * - <i>V</i><sub>0</sub> = normal gravitation potential;
36  * - \e U = <i>V</i><sub>0</sub> + &Phi; = total normal potential;
37  * - \e T = \e W &minus; \e U = \e V &minus; <i>V</i><sub>0</sub> = anomalous
38  * or disturbing potential;
39  * - <b>g</b> = &nabla;\e W = <b>&gamma;</b> + <b>&delta;</b>;
40  * - <b>f</b> = &nabla;&Phi;;
41  * - <b>&Gamma;</b> = &nabla;<i>V</i><sub>0</sub>;
42  * - <b>&gamma;</b> = &nabla;\e U;
43  * - <b>&delta;</b> = &nabla;\e T = gravity disturbance vector
44  * = <b>g</b><sub><i>P</i></sub> &minus; <b>&gamma;</b><sub><i>P</i></sub>;
45  * - &delta;\e g = gravity disturbance = \e g<sub><i>P</i></sub> &minus;
46  * &gamma;<sub><i>P</i></sub>;
47  * - &Delta;<b>g</b> = gravity anomaly vector = <b>g</b><sub><i>P</i></sub>
48  * &minus; <b>&gamma;</b><sub><i>Q</i></sub>; here the line \e PQ is
49  * perpendicular to ellipsoid and the potential at \e P equals the normal
50  * potential at \e Q;
51  * - &Delta;\e g = gravity anomaly = \e g<sub><i>P</i></sub> &minus;
52  * &gamma;<sub><i>Q</i></sub>;
53  * - (&xi;, &eta;) deflection of the vertical, the difference in
54  * directions of <b>g</b><sub><i>P</i></sub> and
55  * <b>&gamma;</b><sub><i>Q</i></sub>, &xi; = NS, &eta; = EW.
56  * - \e X, \e Y, \e Z, geocentric coordinates;
57  * - \e x, \e y, \e z, local cartesian coordinates used to denote the east,
58  * north and up directions.
59  *
60  * See \ref gravity for details of how to install the gravity model and the
61  * data format.
62  *
63  * References:
64  * - W. A. Heiskanen and H. Moritz, Physical Geodesy (Freeman, San
65  * Francisco, 1967).
66  *
67  * C# Example:
68  * \include example-GravityModel.cs
69  * Managed C++ Example:
70  * \include example-GravityModel.cpp
71  * Visual Basic Example:
72  * \include example-GravityModel.vb
73  *
74  * <B>INTERFACE DIFFERENCES:</B><BR>
75  * The following functions are implemented as properties:
76  * Description, DateTime, GravityFile, GravityModelName,
77  * GravityModelDirectory, MajorRadius, MassConstant,
78  * ReferenceMassConstant, AngularVelocity, and Flattening.
79  *
80  * The Circle function accepts the "capabilities mask" as a
81  * NETGeographicLib::GravityModel::Mask rather than an unsigned.
82  **********************************************************************/
83  public ref class GravityModel
84  {
85  private:
86  // pointer to the unmanaged GeographicLib::GravityModel.
87  const GeographicLib::GravityModel* m_pGravityModel;
88 
89  // the finalizer frees the unmanaged memory when the object is destroyed.
90  !GravityModel(void);
91 
92  enum class CapType {
93  CAP_NONE = 0U,
94  CAP_G = 1U<<0, // implies potentials W and V
95  CAP_T = 1U<<1,
96  CAP_DELTA = 1U<<2 | CapType::CAP_T, // delta implies T?
97  CAP_C = 1U<<3,
98  CAP_GAMMA0 = 1U<<4,
99  CAP_GAMMA = 1U<<5,
100  CAP_ALL = 0x3FU,
101  };
102 
103  public:
104 
105  /**
106  * Bit masks for the capabilities to be given to the GravityCircle object
107  * produced by Circle.
108  **********************************************************************/
109  enum class Mask {
110  /**
111  * No capabilities.
112  * @hideinitializer
113  **********************************************************************/
114  NONE = 0U,
115  /**
116  * Allow calls to GravityCircle::Gravity, GravityCircle::W, and
117  * GravityCircle::V.
118  * @hideinitializer
119  **********************************************************************/
121  /**
122  * Allow calls to GravityCircle::Disturbance and GravityCircle::T.
123  * @hideinitializer
124  **********************************************************************/
126  /**
127  * Allow calls to GravityCircle::T(double lon) (i.e., computing the
128  * disturbing potential and not the gravity disturbance vector).
129  * @hideinitializer
130  **********************************************************************/
132  /**
133  * Allow calls to GravityCircle::SphericalAnomaly.
134  * @hideinitializer
135  **********************************************************************/
137  /**
138  * Allow calls to GravityCircle::GeoidHeight.
139  * @hideinitializer
140  **********************************************************************/
142  /**
143  * All capabilities.
144  * @hideinitializer
145  **********************************************************************/
147  };
148  /** \name Setting up the gravity model
149  **********************************************************************/
150  ///@{
151  /**
152  * Construct a gravity model.
153  *
154  * @param[in] name the name of the model.
155  * @param[in] path (optional) directory for data file.
156  * @exception GeographicErr if the data file cannot be found, is
157  * unreadable, or is corrupt.
158  * @exception std::bad_alloc if the memory necessary for storing the model
159  * can't be allocated.
160  *
161  * A filename is formed by appending ".egm" (World Gravity Model) to the
162  * name. If \e path is specified (and is non-empty), then the file is
163  * loaded from directory, \e path. Otherwise the path is given by
164  * DefaultGravityPath().
165  *
166  * This file contains the metadata which specifies the properties of the
167  * model. The coefficients for the spherical harmonic sums are obtained
168  * from a file obtained by appending ".cof" to metadata file (so the
169  * filename ends in ".egm.cof").
170  **********************************************************************/
171  GravityModel(System::String^ name, System::String^ path);
172  ///@}
173 
174  /**
175  * The destructor calls the finalizer.
176  **********************************************************************/
178  { this->!GravityModel(); }
179 
180  /** \name Compute gravity in geodetic coordinates
181  **********************************************************************/
182  ///@{
183  /**
184  * Evaluate the gravity at an arbitrary point above (or below) the
185  * ellipsoid.
186  *
187  * @param[in] lat the geographic latitude (degrees).
188  * @param[in] lon the geographic longitude (degrees).
189  * @param[in] h the height above the ellipsoid (meters).
190  * @param[out] gx the easterly component of the acceleration
191  * (m s<sup>&minus;2</sup>).
192  * @param[out] gy the northerly component of the acceleration
193  * (m s<sup>&minus;2</sup>).
194  * @param[out] gz the upward component of the acceleration
195  * (m s<sup>&minus;2</sup>); this is usually negative.
196  * @return \e W the sum of the gravitational and centrifugal potentials.
197  *
198  * The function includes the effects of the earth's rotation.
199  **********************************************************************/
200  double Gravity(double lat, double lon, double h,
201  [System::Runtime::InteropServices::Out] double% gx,
202  [System::Runtime::InteropServices::Out] double% gy,
203  [System::Runtime::InteropServices::Out] double% gz);
204 
205  /**
206  * Evaluate the gravity disturbance vector at an arbitrary point above (or
207  * below) the ellipsoid.
208  *
209  * @param[in] lat the geographic latitude (degrees).
210  * @param[in] lon the geographic longitude (degrees).
211  * @param[in] h the height above the ellipsoid (meters).
212  * @param[out] deltax the easterly component of the disturbance vector
213  * (m s<sup>&minus;2</sup>).
214  * @param[out] deltay the northerly component of the disturbance vector
215  * (m s<sup>&minus;2</sup>).
216  * @param[out] deltaz the upward component of the disturbance vector
217  * (m s<sup>&minus;2</sup>).
218  * @return \e T the corresponding disturbing potential.
219  **********************************************************************/
220  double Disturbance(double lat, double lon, double h,
221  [System::Runtime::InteropServices::Out] double% deltax,
222  [System::Runtime::InteropServices::Out] double% deltay,
223  [System::Runtime::InteropServices::Out] double% deltaz);
224 
225  /**
226  * Evaluate the geoid height.
227  *
228  * @param[in] lat the geographic latitude (degrees).
229  * @param[in] lon the geographic longitude (degrees).
230  * @return \e N the height of the geoid above the ReferenceEllipsoid()
231  * (meters).
232  *
233  * This calls NormalGravity::U for ReferenceEllipsoid(). Some
234  * approximations are made in computing the geoid height so that the
235  * results of the NGA codes are reproduced accurately. Details are given
236  * in \ref gravitygeoid.
237  **********************************************************************/
238  double GeoidHeight(double lat, double lon);
239 
240  /**
241  * Evaluate the components of the gravity anomaly vector using the
242  * spherical approximation.
243  *
244  * @param[in] lat the geographic latitude (degrees).
245  * @param[in] lon the geographic longitude (degrees).
246  * @param[in] h the height above the ellipsoid (meters).
247  * @param[out] Dg01 the gravity anomaly (m s<sup>&minus;2</sup>).
248  * @param[out] xi the northerly component of the deflection of the vertical
249  * (degrees).
250  * @param[out] eta the easterly component of the deflection of the vertical
251  * (degrees).
252  *
253  * The spherical approximation (see Heiskanen and Moritz, Sec 2-14) is used
254  * so that the results of the NGA codes are reproduced accurately.
255  * approximations used here. Details are given in \ref gravitygeoid.
256  **********************************************************************/
257  void SphericalAnomaly(double lat, double lon, double h,
258  [System::Runtime::InteropServices::Out] double% Dg01,
259  [System::Runtime::InteropServices::Out] double% xi,
260  [System::Runtime::InteropServices::Out] double% eta);
261  ///@}
262 
263  /** \name Compute gravity in geocentric coordinates
264  **********************************************************************/
265  ///@{
266  /**
267  * Evaluate the components of the acceleration due to gravity and the
268  * centrifugal acceleration in geocentric coordinates.
269  *
270  * @param[in] X geocentric coordinate of point (meters).
271  * @param[in] Y geocentric coordinate of point (meters).
272  * @param[in] Z geocentric coordinate of point (meters).
273  * @param[out] gX the \e X component of the acceleration
274  * (m s<sup>&minus;2</sup>).
275  * @param[out] gY the \e Y component of the acceleration
276  * (m s<sup>&minus;2</sup>).
277  * @param[out] gZ the \e Z component of the acceleration
278  * (m s<sup>&minus;2</sup>).
279  * @return \e W = \e V + &Phi; the sum of the gravitational and
280  * centrifugal potentials (m<sup>2</sup> s<sup>&minus;2</sup>).
281  *
282  * This calls NormalGravity::U for ReferenceEllipsoid().
283  **********************************************************************/
284  double W(double X, double Y, double Z,
285  [System::Runtime::InteropServices::Out] double% gX,
286  [System::Runtime::InteropServices::Out] double% gY,
287  [System::Runtime::InteropServices::Out] double% gZ);
288 
289  /**
290  * Evaluate the components of the acceleration due to gravity in geocentric
291  * coordinates.
292  *
293  * @param[in] X geocentric coordinate of point (meters).
294  * @param[in] Y geocentric coordinate of point (meters).
295  * @param[in] Z geocentric coordinate of point (meters).
296  * @param[out] GX the \e X component of the acceleration
297  * (m s<sup>&minus;2</sup>).
298  * @param[out] GY the \e Y component of the acceleration
299  * (m s<sup>&minus;2</sup>).
300  * @param[out] GZ the \e Z component of the acceleration
301  * (m s<sup>&minus;2</sup>).
302  * @return \e V = \e W - &Phi; the gravitational potential
303  * (m<sup>2</sup> s<sup>&minus;2</sup>).
304  **********************************************************************/
305  double V(double X, double Y, double Z,
306  [System::Runtime::InteropServices::Out] double% GX,
307  [System::Runtime::InteropServices::Out] double% GY,
308  [System::Runtime::InteropServices::Out] double% GZ);
309 
310  /**
311  * Evaluate the components of the gravity disturbance in geocentric
312  * coordinates.
313  *
314  * @param[in] X geocentric coordinate of point (meters).
315  * @param[in] Y geocentric coordinate of point (meters).
316  * @param[in] Z geocentric coordinate of point (meters).
317  * @param[out] deltaX the \e X component of the gravity disturbance
318  * (m s<sup>&minus;2</sup>).
319  * @param[out] deltaY the \e Y component of the gravity disturbance
320  * (m s<sup>&minus;2</sup>).
321  * @param[out] deltaZ the \e Z component of the gravity disturbance
322  * (m s<sup>&minus;2</sup>).
323  * @return \e T = \e W - \e U the disturbing potential (also called the
324  * anomalous potential) (m<sup>2</sup> s<sup>&minus;2</sup>).
325  **********************************************************************/
326  double T(double X, double Y, double Z,
327  [System::Runtime::InteropServices::Out] double% deltaX,
328  [System::Runtime::InteropServices::Out] double% deltaY,
329  [System::Runtime::InteropServices::Out] double% deltaZ);
330 
331  /**
332  * Evaluate disturbing potential in geocentric coordinates.
333  *
334  * @param[in] X geocentric coordinate of point (meters).
335  * @param[in] Y geocentric coordinate of point (meters).
336  * @param[in] Z geocentric coordinate of point (meters).
337  * @return \e T = \e W - \e U the disturbing potential (also called the
338  * anomalous potential) (m<sup>2</sup> s<sup>&minus;2</sup>).
339  **********************************************************************/
340  double T(double X, double Y, double Z);
341 
342  /**
343  * Evaluate the components of the acceleration due to normal gravity and
344  * the centrifugal acceleration in geocentric coordinates.
345  *
346  * @param[in] X geocentric coordinate of point (meters).
347  * @param[in] Y geocentric coordinate of point (meters).
348  * @param[in] Z geocentric coordinate of point (meters).
349  * @param[out] gammaX the \e X component of the normal acceleration
350  * (m s<sup>&minus;2</sup>).
351  * @param[out] gammaY the \e Y component of the normal acceleration
352  * (m s<sup>&minus;2</sup>).
353  * @param[out] gammaZ the \e Z component of the normal acceleration
354  * (m s<sup>&minus;2</sup>).
355  * @return \e U = <i>V</i><sub>0</sub> + &Phi; the sum of the
356  * normal gravitational and centrifugal potentials
357  * (m<sup>2</sup> s<sup>&minus;2</sup>).
358  *
359  * This calls NormalGravity::U for ReferenceEllipsoid().
360  **********************************************************************/
361  double U(double X, double Y, double Z,
362  [System::Runtime::InteropServices::Out] double% gammaX,
363  [System::Runtime::InteropServices::Out] double% gammaY,
364  [System::Runtime::InteropServices::Out] double% gammaZ);
365 
366  /**
367  * Evaluate the centrifugal acceleration in geocentric coordinates.
368  *
369  * @param[in] X geocentric coordinate of point (meters).
370  * @param[in] Y geocentric coordinate of point (meters).
371  * @param[out] fX the \e X component of the centrifugal acceleration
372  * (m s<sup>&minus;2</sup>).
373  * @param[out] fY the \e Y component of the centrifugal acceleration
374  * (m s<sup>&minus;2</sup>).
375  * @return &Phi; the centrifugal potential (m<sup>2</sup>
376  * s<sup>&minus;2</sup>).
377  *
378  * This calls NormalGravity::Phi for ReferenceEllipsoid().
379  **********************************************************************/
380  double Phi(double X, double Y,
381  [System::Runtime::InteropServices::Out] double% fX,
382  [System::Runtime::InteropServices::Out] double% fY);
383  ///@}
384 
385  /** \name Compute gravity on a circle of constant latitude
386  **********************************************************************/
387  ///@{
388  /**
389  * Create a GravityCircle object to allow the gravity field at many points
390  * with constant \e lat and \e h and varying \e lon to be computed
391  * efficiently.
392  *
393  * @param[in] lat latitude of the point (degrees).
394  * @param[in] h the height of the point above the ellipsoid (meters).
395  * @param[in] caps bitor'ed combination of GravityModel::mask values
396  * specifying the capabilities of the resulting GravityCircle object.
397  * @exception std::bad_alloc if the memory necessary for creating a
398  * GravityCircle can't be allocated.
399  * @return a GravityCircle object whose member functions computes the
400  * gravitational field at a particular values of \e lon.
401  *
402  * The GravityModel::mask values are
403  * - \e caps |= GravityModel::GRAVITY
404  * - \e caps |= GravityModel::DISTURBANCE
405  * - \e caps |= GravityModel::DISTURBING_POTENTIAL
406  * - \e caps |= GravityModel::SPHERICAL_ANOMALY
407  * - \e caps |= GravityModel::GEOID_HEIGHT
408  * .
409  * The default value of \e caps is GravityModel::ALL which turns on all the
410  * capabilities. If an unsupported function is invoked, it will return
411  * NaNs. Note that GravityModel::GEOID_HEIGHT will only be honored if \e h
412  * = 0.
413  *
414  * If the field at several points on a circle of latitude need to be
415  * calculated then creating a GravityCircle object and using its member
416  * functions will be substantially faster, especially for high-degree
417  * models. See \ref gravityparallel for an example of using GravityCircle
418  * (together with OpenMP) to speed up the computation of geoid heights.
419  **********************************************************************/
420  GravityCircle^ Circle(double lat, double h, Mask caps );
421  ///@}
422 
423  /** \name Inspector functions
424  **********************************************************************/
425  ///@{
426 
427  /**
428  * @return the NormalGravity object for the reference ellipsoid.
429  **********************************************************************/
431 
432  /**
433  * @return the description of the gravity model, if available, in the data
434  * file; if absent, return "NONE".
435  **********************************************************************/
436  property System::String^ Description { System::String^ get(); }
437 
438  /**
439  * @return date of the model; if absent, return "UNKNOWN".
440  **********************************************************************/
441  property System::String^ DateTime { System::String^ get(); }
442 
443  /**
444  * @return full file name used to load the gravity model.
445  **********************************************************************/
446  property System::String^ GravityFile { System::String^ get(); }
447 
448  /**
449  * @return "name" used to load the gravity model (from the first argument
450  * of the constructor, but this may be overridden by the model file).
451  **********************************************************************/
452  property System::String^ GravityModelName { System::String^ get(); }
453 
454  /**
455  * @return directory used to load the gravity model.
456  **********************************************************************/
457  property System::String^ GravityModelDirectory
458  { System::String^ get(); }
459 
460  /**
461  * @return \e a the equatorial radius of the ellipsoid (meters).
462  **********************************************************************/
463  property double MajorRadius { double get(); }
464 
465  /**
466  * @return \e GM the mass constant of the model (m<sup>3</sup>
467  * s<sup>&minus;2</sup>); this is the product of \e G the gravitational
468  * constant and \e M the mass of the earth (usually including the mass of
469  * the earth's atmosphere).
470  **********************************************************************/
471  property double MassConstant { double get(); }
472 
473  /**
474  * @return \e GM the mass constant of the ReferenceEllipsoid()
475  * (m<sup>3</sup> s<sup>&minus;2</sup>).
476  **********************************************************************/
477  property double ReferenceMassConstant { double get(); }
478 
479  /**
480  * @return &omega; the angular velocity of the model and the
481  * ReferenceEllipsoid() (rad s<sup>&minus;1</sup>).
482  **********************************************************************/
483  property double AngularVelocity { double get(); }
484 
485  /**
486  * @return \e f the flattening of the ellipsoid.
487  **********************************************************************/
488  property double Flattening { double get(); }
489  ///@}
490 
491  /**
492  * @return the default path for gravity model data files.
493  *
494  * This is the value of the environment variable GEOGRAPHICLIB_GRAVITY_PATH, if set;
495  * otherwise, it is $GEOGRAPHICLIB_DATA/gravity if the environment variable
496  * GEOGRAPHICLIB_DATA is set; otherwise, it is a compile-time default
497  * (/usr/local/share/GeographicLib/gravity on non-Windows systems and
498  * C:/ProgramData/GeographicLib/gravity on Windows systems).
499  **********************************************************************/
500  static System::String^ DefaultGravityPath();
501 
502  /**
503  * @return the default name for the gravity model.
504  *
505  * This is the value of the environment variable GEOGRAPHICLIB_GRAVITY_NAME, if set,
506  * otherwise, it is "egm96". The GravityModel class does not use
507  * this function; it is just provided as a convenience for a calling
508  * program when constructing a GravityModel object.
509  **********************************************************************/
510  static System::String^ DefaultGravityName();
511  };
512 } //namespace NETGeographicLib
.NET wrapper for GeographicLib::GravityCircle.
Definition: GravityCircle.h:45
double GeoidHeight(double lat, double lon)
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 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)
.NET wrapper for GeographicLib::NormalGravity.
Definition: NormalGravity.h:71
System::String^ GravityModelName
Definition: GravityModel.h:452
System::String^ GravityModelDirectory
Definition: GravityModel.h:457
GravityModel(System::String^ name, System::String^ path)
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)
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 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)
GravityCircle^ Circle(double lat, double h, Mask caps)
double Phi(double X, double Y, [System::Runtime::InteropServices::Out] double% fX, [System::Runtime::InteropServices::Out] double% fY)
static System::String^ DefaultGravityName()
.NET wrapper for GeographicLib::GravityModel.
Definition: GravityModel.h:83
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 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)
NormalGravity^ ReferenceEllipsoid()
static System::String^ DefaultGravityPath()