NETGeographicLib 1.52
Loading...
Searching...
No Matches
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 * https://geographiclib.sourceforge.io/
11 **********************************************************************/
12
13namespace 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, EquatorialRadius, 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 **********************************************************************/
120 GRAVITY = CapType::CAP_G,
121 /**
122 * Allow calls to GravityCircle::Disturbance and GravityCircle::T.
123 * @hideinitializer
124 **********************************************************************/
125 DISTURBANCE = CapType::CAP_DELTA,
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 **********************************************************************/
131 DISTURBING_POTENTIAL = CapType::CAP_T,
132 /**
133 * Allow calls to GravityCircle::SphericalAnomaly.
134 * @hideinitializer
135 **********************************************************************/
136 SPHERICAL_ANOMALY = CapType::CAP_DELTA | CapType::CAP_GAMMA,
137 /**
138 * Allow calls to GravityCircle::GeoidHeight.
139 * @hideinitializer
140 **********************************************************************/
141 GEOID_HEIGHT = CapType::CAP_T | CapType::CAP_C | CapType::CAP_GAMMA0,
142 /**
143 * All capabilities.
144 * @hideinitializer
145 **********************************************************************/
146 ALL = CapType::CAP_ALL,
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 EquatorialRadius { 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:46
.NET wrapper for GeographicLib::GravityModel.
Definition: GravityModel.h:84
static System::String ^ DefaultGravityName()
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)
System::String^ GravityModelDirectory
Definition: GravityModel.h:457
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)
static System::String ^ DefaultGravityPath()
double Phi(double X, double Y, [System::Runtime::InteropServices::Out] double% fX, [System::Runtime::InteropServices::Out] double% fY)
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)
GravityModel(System::String^ name, System::String^ path)
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 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)
GravityCircle ^ Circle(double lat, double h, Mask caps)
double T(double X, double Y, double Z)
double GeoidHeight(double lat, double lon)
System::String^ GravityModelName
Definition: GravityModel.h:452
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 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)
NormalGravity ^ ReferenceEllipsoid()
.NET wrapper for GeographicLib::NormalGravity.
Definition: NormalGravity.h:72