NETGeographicLib  1.40
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Pages
NormalGravity.h
Go to the documentation of this file.
1 #pragma once
2 /**
3  * \file NETGeographicLib/NormalGravity.h
4  * \brief Header for NETGeographicLib::NormalGravity 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 Geocentric;
16  /**
17  * \brief .NET wrapper for GeographicLib::NormalGravity.
18  *
19  * This class allows .NET applications to access GeographicLib::NormalGravity.
20  *
21  * "Normal" gravity refers to an idealization of the earth which is modeled
22  * as an rotating ellipsoid. The eccentricity of the ellipsoid, the rotation
23  * speed, and the distribution of mass within the ellipsoid are such that the
24  * surface of the ellipsoid is a surface of constant potential (gravitational
25  * plus centrifugal). The acceleration due to gravity is therefore
26  * perpendicular to the surface of the ellipsoid.
27  *
28  * There is a closed solution to this problem which is implemented here.
29  * Series "approximations" are only used to evaluate certain combinations of
30  * elementary functions where use of the closed expression results in a loss
31  * of accuracy for small arguments due to cancellation of the two leading
32  * terms. However these series include sufficient terms to give full machine
33  * precision.
34  *
35  * Definitions:
36  * - <i>V</i><sub>0</sub>, the gravitational contribution to the normal
37  * potential;
38  * - &Phi;, the rotational contribution to the normal potential;
39  * - \e U = <i>V</i><sub>0</sub> + &Phi;, the total
40  * potential;
41  * - <b>&Gamma;</b> = &nabla;<i>V</i><sub>0</sub>, the acceleration due to
42  * mass of the earth;
43  * - <b>f</b> = &nabla;&Phi;, the centrifugal acceleration;
44  * - <b>&gamma;</b> = &nabla;\e U = <b>&Gamma;</b> + <b>f</b>, the normal
45  * acceleration;
46  * - \e X, \e Y, \e Z, geocentric coordinates;
47  * - \e x, \e y, \e z, local cartesian coordinates used to denote the east,
48  * north and up directions.
49  *
50  * References:
51  * - W. A. Heiskanen and H. Moritz, Physical Geodesy (Freeman, San
52  * Francisco, 1967), Secs. 1-19, 2-7, 2-8 (2-9, 2-10), 6-2 (6-3).
53  * - H. Moritz, Geodetic Reference System 1980, J. Geodesy 54(3), 395-405
54  * (1980) https://dx.doi.org/10.1007/BF02521480
55  *
56  * C# Example:
57  * \include example-NormalGravity.cs
58  * Managed C++ Example:
59  * \include example-NormalGravity.cpp
60  * Visual Basic Example:
61  * \include example-NormalGravity.vb
62  *
63  * <B>INTERFACE DIFFERENCES:</B><BR>
64  * A constructor has been provided for creating standard WGS84 and GRS80
65  * gravity models.
66  *
67  * The following functions are implemented as properties:
68  * MajorRadius, MassConstant, AngularVelocity, Flattening,
69  * EquatorialGravity, PolarGravity, GravityFlattening, SurfacePotential.
70  **********************************************************************/
71  public ref class NormalGravity
72  {
73  private:
74  // a pointer to the unmanaged GeographicLib::NormalGravity.
75  const GeographicLib::NormalGravity* m_pNormalGravity;
76 
77  // the finalizer frees the unmanaged memory when the object is destroyed.
78  !NormalGravity(void);
79  public:
80  //! The enumerated standard gravity models.
81  enum class StandardModels
82  {
83  WGS84, //!< WGS84 gravity model.
84  GRS80 //!< GRS80 gravity model.
85  };
86 
87  /** \name Setting up the normal gravity
88  **********************************************************************/
89  ///@{
90  /**
91  * Constructor for the normal gravity.
92  *
93  * @param[in] a equatorial radius (meters).
94  * @param[in] GM mass constant of the ellipsoid
95  * (meters<sup>3</sup>/seconds<sup>2</sup>); this is the product of \e G
96  * the gravitational constant and \e M the mass of the earth (usually
97  * including the mass of the earth's atmosphere).
98  * @param[in] omega the angular velocity (rad s<sup>&minus;1</sup>).
99  * @param[in] f the flattening of the ellipsoid.
100  * @param[in] J2 dynamical form factor.
101  * @exception if \e a is not positive or the other constants are
102  * inconsistent (see below).
103  *
104  * Exactly one of \e f and \e J2 should be positive and this will be used
105  * to define the ellipsoid. The shape of the ellipsoid can be given in one
106  * of two ways:
107  * - geometrically, the ellipsoid is defined by the flattening \e f = (\e a
108  * &minus; \e b) / \e a, where \e a and \e b are the equatorial radius
109  * and the polar semi-axis.
110  * - physically, the ellipsoid is defined by the dynamical form factor
111  * <i>J</i><sub>2</sub> = (\e C &minus; \e A) / <i>Ma</i><sup>2</sup>,
112  * where \e A and \e C are the equatorial and polar moments of inertia
113  * and \e M is the mass of the earth.
114  **********************************************************************/
115  NormalGravity(double a, double GM, double omega, double f, double J2);
116 
117  /**
118  * A constructor for creating standard gravity models..
119  * @param[in] model Specifies the desired model.
120  **********************************************************************/
122 
123  /**
124  * A constructor that accepts a GeographicLib::NormalGravity.
125  * For internal use only.
126  * @param g An existing GeographicLib::NormalGravity.
127  **********************************************************************/
129  ///@}
130 
131  /**
132  * The destructor calls the finalizer.
133  **********************************************************************/
135  { this->!NormalGravity(); }
136 
137  /** \name Compute the gravity
138  **********************************************************************/
139  ///@{
140  /**
141  * Evaluate the gravity on the surface of the ellipsoid.
142  *
143  * @param[in] lat the geographic latitude (degrees).
144  * @return &gamma; the acceleration due to gravity, positive downwards
145  * (m s<sup>&minus;2</sup>).
146  *
147  * Due to the axial symmetry of the ellipsoid, the result is independent of
148  * the value of the longitude. This acceleration is perpendicular to the
149  * surface of the ellipsoid. It includes the effects of the earth's
150  * rotation.
151  **********************************************************************/
152  double SurfaceGravity(double lat);
153 
154  /**
155  * Evaluate the gravity at an arbitrary point above (or below) the
156  * ellipsoid.
157  *
158  * @param[in] lat the geographic latitude (degrees).
159  * @param[in] h the height above the ellipsoid (meters).
160  * @param[out] gammay the northerly component of the acceleration
161  * (m s<sup>&minus;2</sup>).
162  * @param[out] gammaz the upward component of the acceleration
163  * (m s<sup>&minus;2</sup>); this is usually negative.
164  * @return \e U the corresponding normal potential.
165  *
166  * Due to the axial symmetry of the ellipsoid, the result is independent of
167  * the value of the longitude and the easterly component of the
168  * acceleration vanishes, \e gammax = 0. The function includes the effects
169  * of the earth's rotation. When \e h = 0, this function gives \e gammay =
170  * 0 and the returned value matches that of NormalGravity::SurfaceGravity.
171  **********************************************************************/
172  double Gravity(double lat, double h,
173  [System::Runtime::InteropServices::Out] double% gammay,
174  [System::Runtime::InteropServices::Out] double% gammaz);
175 
176  /**
177  * Evaluate the components of the acceleration due to gravity and the
178  * centrifugal acceleration in geocentric coordinates.
179  *
180  * @param[in] X geocentric coordinate of point (meters).
181  * @param[in] Y geocentric coordinate of point (meters).
182  * @param[in] Z geocentric coordinate of point (meters).
183  * @param[out] gammaX the \e X component of the acceleration
184  * (m s<sup>&minus;2</sup>).
185  * @param[out] gammaY the \e Y component of the acceleration
186  * (m s<sup>&minus;2</sup>).
187  * @param[out] gammaZ the \e Z component of the acceleration
188  * (m s<sup>&minus;2</sup>).
189  * @return \e U = <i>V</i><sub>0</sub> + &Phi; the sum of the
190  * gravitational and centrifugal potentials
191  * (m<sup>2</sup> s<sup>&minus;2</sup>).
192  *
193  * The acceleration given by <b>&gamma;</b> = &nabla;\e U =
194  * &nabla;<i>V</i><sub>0</sub> + &nabla;&Phi; = <b>&Gamma;</b> + <b>f</b>.
195  **********************************************************************/
196  double U(double X, double Y, double Z,
197  [System::Runtime::InteropServices::Out] double% gammaX,
198  [System::Runtime::InteropServices::Out] double% gammaY,
199  [System::Runtime::InteropServices::Out] double% gammaZ);
200 
201  /**
202  * Evaluate the components of the acceleration due to gravity alone in
203  * geocentric coordinates.
204  *
205  * @param[in] X geocentric coordinate of point (meters).
206  * @param[in] Y geocentric coordinate of point (meters).
207  * @param[in] Z geocentric coordinate of point (meters).
208  * @param[out] GammaX the \e X component of the acceleration due to gravity
209  * (m s<sup>&minus;2</sup>).
210  * @param[out] GammaY the \e Y component of the acceleration due to gravity
211  * (m s<sup>&minus;2</sup>).
212  * @param[out] GammaZ the \e Z component of the acceleration due to gravity
213  * (m s<sup>&minus;2</sup>).
214  * @return <i>V</i><sub>0</sub> the gravitational potential
215  * (m<sup>2</sup> s<sup>&minus;2</sup>).
216  *
217  * This function excludes the centrifugal acceleration and is appropriate
218  * to use for space applications. In terrestrial applications, the
219  * function NormalGravity::U (which includes this effect) should usually be
220  * used.
221  **********************************************************************/
222  double V0(double X, double Y, double Z,
223  [System::Runtime::InteropServices::Out] double% GammaX,
224  [System::Runtime::InteropServices::Out] double% GammaY,
225  [System::Runtime::InteropServices::Out] double% GammaZ);
226 
227  /**
228  * Evaluate the centrifugal acceleration in geocentric coordinates.
229  *
230  * @param[in] X geocentric coordinate of point (meters).
231  * @param[in] Y geocentric coordinate of point (meters).
232  * @param[out] fX the \e X component of the centrifugal acceleration
233  * (m s<sup>&minus;2</sup>).
234  * @param[out] fY the \e Y component of the centrifugal acceleration
235  * (m s<sup>&minus;2</sup>).
236  * @return &Phi; the centrifugal potential (m<sup>2</sup>
237  * s<sup>&minus;2</sup>).
238  *
239  * &Phi; is independent of \e Z, thus \e fZ = 0. This function
240  * NormalGravity::U sums the results of NormalGravity::V0 and
241  * NormalGravity::Phi.
242  **********************************************************************/
243  double Phi(double X, double Y,
244  [System::Runtime::InteropServices::Out] double% fX,
245  [System::Runtime::InteropServices::Out] double% fY);
246  ///@}
247 
248  /** \name Inspector functions
249  **********************************************************************/
250  ///@{
251  /**
252  * @return \e a the equatorial radius of the ellipsoid (meters). This is
253  * the value used in the constructor.
254  **********************************************************************/
255  property double MajorRadius { double get(); }
256 
257  /**
258  * @return \e GM the mass constant of the ellipsoid
259  * (m<sup>3</sup> s<sup>&minus;2</sup>). This is the value used in the
260  * constructor.
261  **********************************************************************/
262  property double MassConstant { double get(); }
263 
264  /**
265  * @return \e J<sub>n</sub> the dynamical form factors of the ellipsoid.
266  *
267  * If \e n = 2 (the default), this is the value of <i>J</i><sub>2</sub>
268  * used in the constructor. Otherwise it is the zonal coefficient of the
269  * Legendre harmonic sum of the normal gravitational potential. Note that
270  * \e J<sub>n</sub> = 0 if \e n is odd. In most gravity applications,
271  * fully normalized Legendre functions are used and the corresponding
272  * coefficient is <i>C</i><sub><i>n</i>0</sub> = &minus;\e J<sub>n</sub> /
273  * sqrt(2 \e n + 1).
274  **********************************************************************/
275  double DynamicalFormFactor(int n);
276 
277  /**
278  * @return &omega; the angular velocity of the ellipsoid (rad
279  * s<sup>&minus;1</sup>). This is the value used in the constructor.
280  **********************************************************************/
281  property double AngularVelocity { double get(); }
282 
283  /**
284  * @return <i>f</i> the flattening of the ellipsoid (\e a &minus; \e b)/\e
285  * a.
286  **********************************************************************/
287  property double Flattening { double get(); }
288 
289  /**
290  * @return &gamma;<sub>e</sub> the normal gravity at equator (m
291  * s<sup>&minus;2</sup>).
292  **********************************************************************/
293  property double EquatorialGravity { double get(); }
294 
295  /**
296  * @return &gamma;<sub>p</sub> the normal gravity at poles (m
297  * s<sup>&minus;2</sup>).
298  **********************************************************************/
299  property double PolarGravity { double get(); }
300 
301  /**
302  * @return <i>f*</i> the gravity flattening (&gamma;<sub>p</sub> &minus;
303  * &gamma;<sub>e</sub>) / &gamma;<sub>e</sub>.
304  **********************************************************************/
305  property double GravityFlattening { double get(); }
306 
307  /**
308  * @return <i>U</i><sub>0</sub> the constant normal potential for the
309  * surface of the ellipsoid (m<sup>2</sup> s<sup>&minus;2</sup>).
310  **********************************************************************/
311  property double SurfacePotential { double get(); }
312 
313  /**
314  * @return the Geocentric object used by this instance.
315  **********************************************************************/
316  Geocentric^ Earth();
317  ///@}
318 
319  /**
320  * A global instantiation of NormalGravity for the WGS84 ellipsoid.
321  **********************************************************************/
322  static NormalGravity^ WGS84();
323 
324  /**
325  * A global instantiation of NormalGravity for the GRS80 ellipsoid.
326  **********************************************************************/
327  static NormalGravity^ GRS80();
328 
329  /**
330  * Compute the flattening from the dynamical form factor.
331  *
332  * @param[in] a equatorial radius (meters).
333  * @param[in] GM mass constant of the ellipsoid
334  * (meters<sup>3</sup>/seconds<sup>2</sup>); this is the product of \e G
335  * the gravitational constant and \e M the mass of the earth (usually
336  * including the mass of the earth's atmosphere).
337  * @param[in] omega the angular velocity (rad s<sup>&minus;1</sup>).
338  * @param[in] J2 the dynamical form factor.
339  * @return \e f the flattening of the ellipsoid.
340  **********************************************************************/
341  static double J2ToFlattening(double a, double GM, double omega,
342  double J2);
343 
344  /**
345  * Compute the dynamical form factor from the flattening.
346  *
347  * @param[in] a equatorial radius (meters).
348  * @param[in] GM mass constant of the ellipsoid
349  * (meters<sup>3</sup>/seconds<sup>2</sup>); this is the product of \e G
350  * the gravitational constant and \e M the mass of the earth (usually
351  * including the mass of the earth's atmosphere).
352  * @param[in] omega the angular velocity (rad s<sup>&minus;1</sup>).
353  * @param[in] f the flattening of the ellipsoid.
354  * @return \e J2 the dynamical form factor.
355  **********************************************************************/
356  static double FlatteningToJ2(double a, double GM, double omega,
357  double f);
358  };
359 } //namespace NETGeographicLib
static double FlatteningToJ2(double a, double GM, double omega, double f)
StandardModels
The enumerated standard gravity models.
Definition: NormalGravity.h:81
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)
.NET wrapper for GeographicLib::Geocentric.
Definition: Geocentric.h:68
static double J2ToFlattening(double a, double GM, double omega, double J2)
.NET wrapper for GeographicLib::NormalGravity.
Definition: NormalGravity.h:71
double Phi(double X, double Y, [System::Runtime::InteropServices::Out] double% fX, [System::Runtime::InteropServices::Out] double% fY)
double V0(double X, double Y, double Z, [System::Runtime::InteropServices::Out] double% GammaX, [System::Runtime::InteropServices::Out] double% GammaY, [System::Runtime::InteropServices::Out] double% GammaZ)
static NormalGravity^ GRS80()
double Gravity(double lat, double h, [System::Runtime::InteropServices::Out] double% gammay, [System::Runtime::InteropServices::Out] double% gammaz)
double SurfaceGravity(double lat)
NormalGravity(double a, double GM, double omega, double f, double J2)
static NormalGravity^ WGS84()