00001 #pragma once 00002 /** 00003 * \file NETGeographicLib/NormalGravity.h 00004 * \brief Header for NETGeographicLib::NormalGravity class 00005 * 00006 * NETGeographicLib is copyright (c) Scott Heiman (2013) 00007 * GeographicLib is Copyright (c) Charles Karney (2010-2012) 00008 * <charles@karney.com> and licensed under the MIT/X11 License. 00009 * For more information, see 00010 * http://geographiclib.sourceforge.net/ 00011 **********************************************************************/ 00012 00013 namespace NETGeographicLib 00014 { 00015 ref class Geocentric; 00016 /** 00017 * \brief .NET wrapper for GeographicLib::NormalGravity. 00018 * 00019 * This class allows .NET applications to access GeographicLib::NormalGravity. 00020 * 00021 * "Normal" gravity refers to an idealization of the earth which is modeled 00022 * as an rotating ellipsoid. The eccentricity of the ellipsoid, the rotation 00023 * speed, and the distribution of mass within the ellipsoid are such that the 00024 * surface of the ellipsoid is a surface of constant potential (gravitational 00025 * plus centrifugal). The acceleration due to gravity is therefore 00026 * perpendicular to the surface of the ellipsoid. 00027 * 00028 * There is a closed solution to this problem which is implemented here. 00029 * Series "approximations" are only used to evaluate certain combinations of 00030 * elementary functions where use of the closed expression results in a loss 00031 * of accuracy for small arguments due to cancellation of the two leading 00032 * terms. However these series include sufficient terms to give full machine 00033 * precision. 00034 * 00035 * Definitions: 00036 * - <i>V</i><sub>0</sub>, the gravitational contribution to the normal 00037 * potential; 00038 * - Φ, the rotational contribution to the normal potential; 00039 * - \e U = <i>V</i><sub>0</sub> + Φ, the total 00040 * potential; 00041 * - <b>Γ</b> = ∇<i>V</i><sub>0</sub>, the acceleration due to 00042 * mass of the earth; 00043 * - <b>f</b> = ∇Φ, the centrifugal acceleration; 00044 * - <b>γ</b> = ∇\e U = <b>Γ</b> + <b>f</b>, the normal 00045 * acceleration; 00046 * - \e X, \e Y, \e Z, geocentric coordinates; 00047 * - \e x, \e y, \e z, local cartesian coordinates used to denote the east, 00048 * north and up directions. 00049 * 00050 * References: 00051 * - W. A. Heiskanen and H. Moritz, Physical Geodesy (Freeman, San 00052 * Francisco, 1967), Secs. 1-19, 2-7, 2-8 (2-9, 2-10), 6-2 (6-3). 00053 * - H. Moritz, Geodetic Reference System 1980, J. Geodesy 54(3), 395-405 00054 * (1980) http://dx.doi.org/10.1007/BF02521480 00055 * 00056 * C# Example: 00057 * \include example-NormalGravity.cs 00058 * Managed C++ Example: 00059 * \include example-NormalGravity.cpp 00060 * Visual Basic Example: 00061 * \include example-NormalGravity.vb 00062 * 00063 * <B>INTERFACE DIFFERENCES:</B><BR> 00064 * A constructor has been provided for creating standard WGS84 and GRS80 00065 * gravity models. 00066 * 00067 * The following functions are implemented as properties: 00068 * MajorRadius, MassConstant, AngularVelocity, Flattening, 00069 * EquatorialGravity, PolarGravity, GravityFlattening, SurfacePotential. 00070 **********************************************************************/ 00071 public ref class NormalGravity 00072 { 00073 private: 00074 // a pointer to the unmanaged GeographicLib::NormalGravity. 00075 const GeographicLib::NormalGravity* m_pNormalGravity; 00076 00077 // the finalizer frees the unmanaged memory when the object is destroyed. 00078 !NormalGravity(void); 00079 public: 00080 //! The enumerated standard gravity models. 00081 enum class StandardModels 00082 { 00083 WGS84, //!< WGS84 gravity model. 00084 GRS80 //!< GRS80 gravity model. 00085 }; 00086 00087 /** \name Setting up the normal gravity 00088 **********************************************************************/ 00089 ///@{ 00090 /** 00091 * Constructor for the normal gravity. 00092 * 00093 * @param[in] a equatorial radius (meters). 00094 * @param[in] GM mass constant of the ellipsoid 00095 * (meters<sup>3</sup>/seconds<sup>2</sup>); this is the product of \e G 00096 * the gravitational constant and \e M the mass of the earth (usually 00097 * including the mass of the earth's atmosphere). 00098 * @param[in] omega the angular velocity (rad s<sup>−1</sup>). 00099 * @param[in] f the flattening of the ellipsoid. 00100 * @param[in] J2 dynamical form factor. 00101 * @exception if \e a is not positive or the other constants are 00102 * inconsistent (see below). 00103 * 00104 * Exactly one of \e f and \e J2 should be positive and this will be used 00105 * to define the ellipsoid. The shape of the ellipsoid can be given in one 00106 * of two ways: 00107 * - geometrically, the ellipsoid is defined by the flattening \e f = (\e a 00108 * − \e b) / \e a, where \e a and \e b are the equatorial radius 00109 * and the polar semi-axis. 00110 * - physically, the ellipsoid is defined by the dynamical form factor 00111 * <i>J</i><sub>2</sub> = (\e C − \e A) / <i>Ma</i><sup>2</sup>, 00112 * where \e A and \e C are the equatorial and polar moments of inertia 00113 * and \e M is the mass of the earth. 00114 **********************************************************************/ 00115 NormalGravity(double a, double GM, double omega, double f, double J2); 00116 00117 /** 00118 * A constructor for creating standard gravity models.. 00119 * @param[in] model Specifies the desired model. 00120 **********************************************************************/ 00121 NormalGravity(StandardModels model); 00122 00123 /** 00124 * A constructor that accepts a GeographicLib::NormalGravity. 00125 * For internal use only. 00126 * @param g An existing GeographicLib::NormalGravity. 00127 **********************************************************************/ 00128 NormalGravity( const GeographicLib::NormalGravity& g); 00129 ///@} 00130 00131 /** 00132 * The destructor calls the finalizer. 00133 **********************************************************************/ 00134 ~NormalGravity() 00135 { this->!NormalGravity(); } 00136 00137 /** \name Compute the gravity 00138 **********************************************************************/ 00139 ///@{ 00140 /** 00141 * Evaluate the gravity on the surface of the ellipsoid. 00142 * 00143 * @param[in] lat the geographic latitude (degrees). 00144 * @return γ the acceleration due to gravity, positive downwards 00145 * (m s<sup>−2</sup>). 00146 * 00147 * Due to the axial symmetry of the ellipsoid, the result is independent of 00148 * the value of the longitude. This acceleration is perpendicular to the 00149 * surface of the ellipsoid. It includes the effects of the earth's 00150 * rotation. 00151 **********************************************************************/ 00152 double SurfaceGravity(double lat); 00153 00154 /** 00155 * Evaluate the gravity at an arbitrary point above (or below) the 00156 * ellipsoid. 00157 * 00158 * @param[in] lat the geographic latitude (degrees). 00159 * @param[in] h the height above the ellipsoid (meters). 00160 * @param[out] gammay the northerly component of the acceleration 00161 * (m s<sup>−2</sup>). 00162 * @param[out] gammaz the upward component of the acceleration 00163 * (m s<sup>−2</sup>); this is usually negative. 00164 * @return \e U the corresponding normal potential. 00165 * 00166 * Due to the axial symmetry of the ellipsoid, the result is independent of 00167 * the value of the longitude and the easterly component of the 00168 * acceleration vanishes, \e gammax = 0. The function includes the effects 00169 * of the earth's rotation. When \e h = 0, this function gives \e gammay = 00170 * 0 and the returned value matches that of NormalGravity::SurfaceGravity. 00171 **********************************************************************/ 00172 double Gravity(double lat, double h, 00173 [System::Runtime::InteropServices::Out] double% gammay, 00174 [System::Runtime::InteropServices::Out] double% gammaz); 00175 00176 /** 00177 * Evaluate the components of the acceleration due to gravity and the 00178 * centrifugal acceleration in geocentric coordinates. 00179 * 00180 * @param[in] X geocentric coordinate of point (meters). 00181 * @param[in] Y geocentric coordinate of point (meters). 00182 * @param[in] Z geocentric coordinate of point (meters). 00183 * @param[out] gammaX the \e X component of the acceleration 00184 * (m s<sup>−2</sup>). 00185 * @param[out] gammaY the \e Y component of the acceleration 00186 * (m s<sup>−2</sup>). 00187 * @param[out] gammaZ the \e Z component of the acceleration 00188 * (m s<sup>−2</sup>). 00189 * @return \e U = <i>V</i><sub>0</sub> + Φ the sum of the 00190 * gravitational and centrifugal potentials 00191 * (m<sup>2</sup> s<sup>−2</sup>). 00192 * 00193 * The acceleration given by <b>γ</b> = ∇\e U = 00194 * ∇<i>V</i><sub>0</sub> + ∇Φ = <b>Γ</b> + <b>f</b>. 00195 **********************************************************************/ 00196 double U(double X, double Y, double Z, 00197 [System::Runtime::InteropServices::Out] double% gammaX, 00198 [System::Runtime::InteropServices::Out] double% gammaY, 00199 [System::Runtime::InteropServices::Out] double% gammaZ); 00200 00201 /** 00202 * Evaluate the components of the acceleration due to gravity alone in 00203 * geocentric coordinates. 00204 * 00205 * @param[in] X geocentric coordinate of point (meters). 00206 * @param[in] Y geocentric coordinate of point (meters). 00207 * @param[in] Z geocentric coordinate of point (meters). 00208 * @param[out] GammaX the \e X component of the acceleration due to gravity 00209 * (m s<sup>−2</sup>). 00210 * @param[out] GammaY the \e Y component of the acceleration due to gravity 00211 * (m s<sup>−2</sup>). 00212 * @param[out] GammaZ the \e Z component of the acceleration due to gravity 00213 * (m s<sup>−2</sup>). 00214 * @return <i>V</i><sub>0</sub> the gravitational potential 00215 * (m<sup>2</sup> s<sup>−2</sup>). 00216 * 00217 * This function excludes the centrifugal acceleration and is appropriate 00218 * to use for space applications. In terrestrial applications, the 00219 * function NormalGravity::U (which includes this effect) should usually be 00220 * used. 00221 **********************************************************************/ 00222 double V0(double X, double Y, double Z, 00223 [System::Runtime::InteropServices::Out] double% GammaX, 00224 [System::Runtime::InteropServices::Out] double% GammaY, 00225 [System::Runtime::InteropServices::Out] double% GammaZ); 00226 00227 /** 00228 * Evaluate the centrifugal acceleration in geocentric coordinates. 00229 * 00230 * @param[in] X geocentric coordinate of point (meters). 00231 * @param[in] Y geocentric coordinate of point (meters). 00232 * @param[out] fX the \e X component of the centrifugal acceleration 00233 * (m s<sup>−2</sup>). 00234 * @param[out] fY the \e Y component of the centrifugal acceleration 00235 * (m s<sup>−2</sup>). 00236 * @return Φ the centrifugal potential (m<sup>2</sup> 00237 * s<sup>−2</sup>). 00238 * 00239 * Φ is independent of \e Z, thus \e fZ = 0. This function 00240 * NormalGravity::U sums the results of NormalGravity::V0 and 00241 * NormalGravity::Phi. 00242 **********************************************************************/ 00243 double Phi(double X, double Y, 00244 [System::Runtime::InteropServices::Out] double% fX, 00245 [System::Runtime::InteropServices::Out] double% fY); 00246 ///@} 00247 00248 /** \name Inspector functions 00249 **********************************************************************/ 00250 ///@{ 00251 /** 00252 * @return \e a the equatorial radius of the ellipsoid (meters). This is 00253 * the value used in the constructor. 00254 **********************************************************************/ 00255 property double MajorRadius { double get(); } 00256 00257 /** 00258 * @return \e GM the mass constant of the ellipsoid 00259 * (m<sup>3</sup> s<sup>−2</sup>). This is the value used in the 00260 * constructor. 00261 **********************************************************************/ 00262 property double MassConstant { double get(); } 00263 00264 /** 00265 * @return \e J<sub>n</sub> the dynamical form factors of the ellipsoid. 00266 * 00267 * If \e n = 2 (the default), this is the value of <i>J</i><sub>2</sub> 00268 * used in the constructor. Otherwise it is the zonal coefficient of the 00269 * Legendre harmonic sum of the normal gravitational potential. Note that 00270 * \e J<sub>n</sub> = 0 if \e n is odd. In most gravity applications, 00271 * fully normalized Legendre functions are used and the corresponding 00272 * coefficient is <i>C</i><sub><i>n</i>0</sub> = −\e J<sub>n</sub> / 00273 * sqrt(2 \e n + 1). 00274 **********************************************************************/ 00275 double DynamicalFormFactor(int n); 00276 00277 /** 00278 * @return ω the angular velocity of the ellipsoid (rad 00279 * s<sup>−1</sup>). This is the value used in the constructor. 00280 **********************************************************************/ 00281 property double AngularVelocity { double get(); } 00282 00283 /** 00284 * @return <i>f</i> the flattening of the ellipsoid (\e a − \e b)/\e 00285 * a. 00286 **********************************************************************/ 00287 property double Flattening { double get(); } 00288 00289 /** 00290 * @return γ<sub>e</sub> the normal gravity at equator (m 00291 * s<sup>−2</sup>). 00292 **********************************************************************/ 00293 property double EquatorialGravity { double get(); } 00294 00295 /** 00296 * @return γ<sub>p</sub> the normal gravity at poles (m 00297 * s<sup>−2</sup>). 00298 **********************************************************************/ 00299 property double PolarGravity { double get(); } 00300 00301 /** 00302 * @return <i>f*</i> the gravity flattening (γ<sub>p</sub> − 00303 * γ<sub>e</sub>) / γ<sub>e</sub>. 00304 **********************************************************************/ 00305 property double GravityFlattening { double get(); } 00306 00307 /** 00308 * @return <i>U</i><sub>0</sub> the constant normal potential for the 00309 * surface of the ellipsoid (m<sup>2</sup> s<sup>−2</sup>). 00310 **********************************************************************/ 00311 property double SurfacePotential { double get(); } 00312 00313 /** 00314 * @return the Geocentric object used by this instance. 00315 **********************************************************************/ 00316 Geocentric^ Earth(); 00317 ///@} 00318 00319 /** 00320 * A global instantiation of NormalGravity for the WGS84 ellipsoid. 00321 **********************************************************************/ 00322 static NormalGravity^ WGS84(); 00323 00324 /** 00325 * A global instantiation of NormalGravity for the GRS80 ellipsoid. 00326 **********************************************************************/ 00327 static NormalGravity^ GRS80(); 00328 00329 /** 00330 * Compute the flattening from the dynamical form factor. 00331 * 00332 * @param[in] a equatorial radius (meters). 00333 * @param[in] GM mass constant of the ellipsoid 00334 * (meters<sup>3</sup>/seconds<sup>2</sup>); this is the product of \e G 00335 * the gravitational constant and \e M the mass of the earth (usually 00336 * including the mass of the earth's atmosphere). 00337 * @param[in] omega the angular velocity (rad s<sup>−1</sup>). 00338 * @param[in] J2 the dynamical form factor. 00339 * @return \e f the flattening of the ellipsoid. 00340 **********************************************************************/ 00341 static double J2ToFlattening(double a, double GM, double omega, 00342 double J2); 00343 00344 /** 00345 * Compute the dynamical form factor from the flattening. 00346 * 00347 * @param[in] a equatorial radius (meters). 00348 * @param[in] GM mass constant of the ellipsoid 00349 * (meters<sup>3</sup>/seconds<sup>2</sup>); this is the product of \e G 00350 * the gravitational constant and \e M the mass of the earth (usually 00351 * including the mass of the earth's atmosphere). 00352 * @param[in] omega the angular velocity (rad s<sup>−1</sup>). 00353 * @param[in] f the flattening of the ellipsoid. 00354 * @return \e J2 the dynamical form factor. 00355 **********************************************************************/ 00356 static double FlatteningToJ2(double a, double GM, double omega, 00357 double f); 00358 }; 00359 } //namespace NETGeographicLib