NETGeographicLib 1.52
Loading...
Searching...
No Matches
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
13namespace 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 **********************************************************************/
323 ///@}
324
325 /**
326 * A global instantiation of NormalGravity for the WGS84 ellipsoid.
327 **********************************************************************/
329
330 /**
331 * A global instantiation of NormalGravity for the GRS80 ellipsoid.
332 **********************************************************************/
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
.NET wrapper for GeographicLib::Geocentric.
Definition: Geocentric.h:69
.NET wrapper for GeographicLib::NormalGravity.
Definition: NormalGravity.h:72
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)
double SurfaceGravity(double lat)
StandardModels
The enumerated standard gravity models.
Definition: NormalGravity.h:82
static double FlatteningToJ2(double a, double GM, double omega, double f)
NormalGravity(double a, double GM, double omega, double f_J2, bool geometricp)
static NormalGravity ^ GRS80()
NormalGravity(StandardModels model)
NormalGravity(const GeographicLib::NormalGravity &g)
double Gravity(double lat, double h, [System::Runtime::InteropServices::Out] double% gammay, [System::Runtime::InteropServices::Out] double% gammaz)
static NormalGravity ^ WGS84()
static double J2ToFlattening(double a, double GM, double omega, double J2)
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)