NETGeographicLib  1.51
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  * https://geographiclib.sourceforge.io/
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://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  * EquatorialRadius, 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_J2 either the flattening of the ellipsoid \e f or the
100  * the dynamical form factor \e J2.
101  * @param[out] geometricp if true, then \e f_J2 denotes the
102  * flattening, else it denotes the dynamical form factor \e J2.
103  * @exception if \e a is not positive or if the other parameters do not
104  * obey the restrictions given below.
105  *
106  * The shape of the ellipsoid can be given in one of two ways:
107  * - geometrically (\e geomtricp = true), the ellipsoid is defined by the
108  * flattening \e f = (\e a &minus; \e b) / \e a, where \e a and \e b are
109  * the equatorial radius and the polar semi-axis. The parameters should
110  * obey \e a &gt; 0, \e f &lt; 1. There are no restrictions on \e GM or
111  * \e omega, in particular, \e GM need not be positive.
112  * - physically (\e geometricp = false), the ellipsoid is defined by the
113  * dynamical form factor <i>J</i><sub>2</sub> = (\e C &minus; \e A) /
114  * <i>Ma</i><sup>2</sup>, where \e A and \e C are the equatorial and
115  * polar moments of inertia and \e M is the mass of the earth. The
116  * parameters should obey \e a &gt; 0, \e GM &gt; 0 and \e J2 &lt; 1/3
117  * &minus; (<i>omega</i><sup>2</sup><i>a</i><sup>3</sup>/<i>GM</i>)
118  * 8/(45&pi;). There is no restriction on \e omega.
119  **********************************************************************/
120  NormalGravity(double a, double GM, double omega, double f_J2,
121  bool geometricp);
122 
123  /**
124  * A constructor for creating standard gravity models..
125  * @param[in] model Specifies the desired model.
126  **********************************************************************/
128 
129  /**
130  * A constructor that accepts a GeographicLib::NormalGravity.
131  * For internal use only.
132  * @param g An existing GeographicLib::NormalGravity.
133  **********************************************************************/
135  ///@}
136 
137  /**
138  * The destructor calls the finalizer.
139  **********************************************************************/
141  { this->!NormalGravity(); }
142 
143  /** \name Compute the gravity
144  **********************************************************************/
145  ///@{
146  /**
147  * Evaluate the gravity on the surface of the ellipsoid.
148  *
149  * @param[in] lat the geographic latitude (degrees).
150  * @return &gamma; the acceleration due to gravity, positive downwards
151  * (m s<sup>&minus;2</sup>).
152  *
153  * Due to the axial symmetry of the ellipsoid, the result is independent of
154  * the value of the longitude. This acceleration is perpendicular to the
155  * surface of the ellipsoid. It includes the effects of the earth's
156  * rotation.
157  **********************************************************************/
158  double SurfaceGravity(double lat);
159 
160  /**
161  * Evaluate the gravity at an arbitrary point above (or below) the
162  * ellipsoid.
163  *
164  * @param[in] lat the geographic latitude (degrees).
165  * @param[in] h the height above the ellipsoid (meters).
166  * @param[out] gammay the northerly component of the acceleration
167  * (m s<sup>&minus;2</sup>).
168  * @param[out] gammaz the upward component of the acceleration
169  * (m s<sup>&minus;2</sup>); this is usually negative.
170  * @return \e U the corresponding normal potential.
171  *
172  * Due to the axial symmetry of the ellipsoid, the result is independent of
173  * the value of the longitude and the easterly component of the
174  * acceleration vanishes, \e gammax = 0. The function includes the effects
175  * of the earth's rotation. When \e h = 0, this function gives \e gammay =
176  * 0 and the returned value matches that of NormalGravity::SurfaceGravity.
177  **********************************************************************/
178  double Gravity(double lat, double h,
179  [System::Runtime::InteropServices::Out] double% gammay,
180  [System::Runtime::InteropServices::Out] double% gammaz);
181 
182  /**
183  * Evaluate the components of the acceleration due to gravity and the
184  * centrifugal acceleration in geocentric coordinates.
185  *
186  * @param[in] X geocentric coordinate of point (meters).
187  * @param[in] Y geocentric coordinate of point (meters).
188  * @param[in] Z geocentric coordinate of point (meters).
189  * @param[out] gammaX the \e X component of the acceleration
190  * (m s<sup>&minus;2</sup>).
191  * @param[out] gammaY the \e Y component of the acceleration
192  * (m s<sup>&minus;2</sup>).
193  * @param[out] gammaZ the \e Z component of the acceleration
194  * (m s<sup>&minus;2</sup>).
195  * @return \e U = <i>V</i><sub>0</sub> + &Phi; the sum of the
196  * gravitational and centrifugal potentials
197  * (m<sup>2</sup> s<sup>&minus;2</sup>).
198  *
199  * The acceleration given by <b>&gamma;</b> = &nabla;\e U =
200  * &nabla;<i>V</i><sub>0</sub> + &nabla;&Phi; = <b>&Gamma;</b> + <b>f</b>.
201  **********************************************************************/
202  double U(double X, double Y, double Z,
203  [System::Runtime::InteropServices::Out] double% gammaX,
204  [System::Runtime::InteropServices::Out] double% gammaY,
205  [System::Runtime::InteropServices::Out] double% gammaZ);
206 
207  /**
208  * Evaluate the components of the acceleration due to gravity alone in
209  * geocentric coordinates.
210  *
211  * @param[in] X geocentric coordinate of point (meters).
212  * @param[in] Y geocentric coordinate of point (meters).
213  * @param[in] Z geocentric coordinate of point (meters).
214  * @param[out] GammaX the \e X component of the acceleration due to gravity
215  * (m s<sup>&minus;2</sup>).
216  * @param[out] GammaY the \e Y component of the acceleration due to gravity
217  * (m s<sup>&minus;2</sup>).
218  * @param[out] GammaZ the \e Z component of the acceleration due to gravity
219  * (m s<sup>&minus;2</sup>).
220  * @return <i>V</i><sub>0</sub> the gravitational potential
221  * (m<sup>2</sup> s<sup>&minus;2</sup>).
222  *
223  * This function excludes the centrifugal acceleration and is appropriate
224  * to use for space applications. In terrestrial applications, the
225  * function NormalGravity::U (which includes this effect) should usually be
226  * used.
227  **********************************************************************/
228  double V0(double X, double Y, double Z,
229  [System::Runtime::InteropServices::Out] double% GammaX,
230  [System::Runtime::InteropServices::Out] double% GammaY,
231  [System::Runtime::InteropServices::Out] double% GammaZ);
232 
233  /**
234  * Evaluate the centrifugal acceleration in geocentric coordinates.
235  *
236  * @param[in] X geocentric coordinate of point (meters).
237  * @param[in] Y geocentric coordinate of point (meters).
238  * @param[out] fX the \e X component of the centrifugal acceleration
239  * (m s<sup>&minus;2</sup>).
240  * @param[out] fY the \e Y component of the centrifugal acceleration
241  * (m s<sup>&minus;2</sup>).
242  * @return &Phi; the centrifugal potential (m<sup>2</sup>
243  * s<sup>&minus;2</sup>).
244  *
245  * &Phi; is independent of \e Z, thus \e fZ = 0. This function
246  * NormalGravity::U sums the results of NormalGravity::V0 and
247  * NormalGravity::Phi.
248  **********************************************************************/
249  double Phi(double X, double Y,
250  [System::Runtime::InteropServices::Out] double% fX,
251  [System::Runtime::InteropServices::Out] double% fY);
252  ///@}
253 
254  /** \name Inspector functions
255  **********************************************************************/
256  ///@{
257  /**
258  * @return \e a the equatorial radius of the ellipsoid (meters). This is
259  * the value used in the constructor.
260  **********************************************************************/
261  property double EquatorialRadius { double get(); }
262 
263  /**
264  * @return \e GM the mass constant of the ellipsoid
265  * (m<sup>3</sup> s<sup>&minus;2</sup>). This is the value used in the
266  * constructor.
267  **********************************************************************/
268  property double MassConstant { double get(); }
269 
270  /**
271  * @return \e J<sub>n</sub> the dynamical form factors of the ellipsoid.
272  *
273  * If \e n = 2 (the default), this is the value of <i>J</i><sub>2</sub>
274  * used in the constructor. Otherwise it is the zonal coefficient of the
275  * Legendre harmonic sum of the normal gravitational potential. Note that
276  * \e J<sub>n</sub> = 0 if \e n is odd. In most gravity applications,
277  * fully normalized Legendre functions are used and the corresponding
278  * coefficient is <i>C</i><sub><i>n</i>0</sub> = &minus;\e J<sub>n</sub> /
279  * sqrt(2 \e n + 1).
280  **********************************************************************/
281  double DynamicalFormFactor(int n);
282 
283  /**
284  * @return &omega; the angular velocity of the ellipsoid (rad
285  * s<sup>&minus;1</sup>). This is the value used in the constructor.
286  **********************************************************************/
287  property double AngularVelocity { double get(); }
288 
289  /**
290  * @return <i>f</i> the flattening of the ellipsoid (\e a &minus; \e b)/\e
291  * a.
292  **********************************************************************/
293  property double Flattening { double get(); }
294 
295  /**
296  * @return &gamma;<sub>e</sub> the normal gravity at equator (m
297  * s<sup>&minus;2</sup>).
298  **********************************************************************/
299  property double EquatorialGravity { double get(); }
300 
301  /**
302  * @return &gamma;<sub>p</sub> the normal gravity at poles (m
303  * s<sup>&minus;2</sup>).
304  **********************************************************************/
305  property double PolarGravity { double get(); }
306 
307  /**
308  * @return <i>f*</i> the gravity flattening (&gamma;<sub>p</sub> &minus;
309  * &gamma;<sub>e</sub>) / &gamma;<sub>e</sub>.
310  **********************************************************************/
311  property double GravityFlattening { double get(); }
312 
313  /**
314  * @return <i>U</i><sub>0</sub> the constant normal potential for the
315  * surface of the ellipsoid (m<sup>2</sup> s<sup>&minus;2</sup>).
316  **********************************************************************/
317  property double SurfacePotential { double get(); }
318 
319  /**
320  * @return the Geocentric object used by this instance.
321  **********************************************************************/
322  Geocentric^ Earth();
323  ///@}
324 
325  /**
326  * A global instantiation of NormalGravity for the WGS84 ellipsoid.
327  **********************************************************************/
328  static NormalGravity^ WGS84();
329 
330  /**
331  * A global instantiation of NormalGravity for the GRS80 ellipsoid.
332  **********************************************************************/
333  static NormalGravity^ GRS80();
334 
335  /**
336  * Compute the flattening from the dynamical form factor.
337  *
338  * @param[in] a equatorial radius (meters).
339  * @param[in] GM mass constant of the ellipsoid
340  * (meters<sup>3</sup>/seconds<sup>2</sup>); this is the product of \e G
341  * the gravitational constant and \e M the mass of the earth (usually
342  * including the mass of the earth's atmosphere).
343  * @param[in] omega the angular velocity (rad s<sup>&minus;1</sup>).
344  * @param[in] J2 the dynamical form factor.
345  * @return \e f the flattening of the ellipsoid.
346  **********************************************************************/
347  static double J2ToFlattening(double a, double GM, double omega,
348  double J2);
349 
350  /**
351  * Compute the dynamical form factor from the flattening.
352  *
353  * @param[in] a equatorial radius (meters).
354  * @param[in] GM mass constant of the ellipsoid
355  * (meters<sup>3</sup>/seconds<sup>2</sup>); this is the product of \e G
356  * the gravitational constant and \e M the mass of the earth (usually
357  * including the mass of the earth's atmosphere).
358  * @param[in] omega the angular velocity (rad s<sup>&minus;1</sup>).
359  * @param[in] f the flattening of the ellipsoid.
360  * @return \e J2 the dynamical form factor.
361  **********************************************************************/
362  static double FlatteningToJ2(double a, double GM, double omega,
363  double f);
364  };
365 } //namespace NETGeographicLib
static double FlatteningToJ2(double a, double GM, double omega, double f)
NormalGravity(double a, double GM, double omega, double f_J2, bool geometricp)
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)
static NormalGravity ^ WGS84()