NETGeographicLib  1.38
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Pages
GravityCircle.h
Go to the documentation of this file.
1 #pragma once
2 /**
3  * \file NETGeographicLib/GravityCircle.h
4  * \brief Header for NETGeographicLib::GravityCircle 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  /**
16  * \brief .NET wrapper for GeographicLib::GravityCircle.
17  *
18  * This class allows .NET applications to access GeographicLib::GravityCircle.
19  *
20  * Evaluate the earth's gravity field on a circle of constant height and
21  * latitude. This uses a CircularEngine to pre-evaluate the inner sum of the
22  * spherical harmonic sum, allowing the values of the field at several
23  * different longitudes to be evaluated rapidly.
24  *
25  * Use GravityModel::Circle to create a GravityCircle object. (The
26  * constructor for this class is for internal use only.)
27  *
28  * C# Example:
29  * \include example-GravityCircle.cs
30  * Managed C++ Example:
31  * \include example-GravityCircle.cpp
32  * Visual Basic Example:
33  * \include example-GravityCircle.vb
34  *
35  * <B>INTERFACE DIFFERENCES:</B><BR>
36  * The following functions are implemented as properties:
37  * Init, MajorRadius, Flattening, Latitude, and Height.
38  *
39  * The Capabilities functions accept and return the "capabilities mask"
40  * as a NETGeographicLib::GravityModel::Mask rather than an unsigned.
41  **********************************************************************/
42  public ref class GravityCircle
43  {
44  private:
45  // the pointer to the unmanaged GeographicLib::GravityCircle.
46  const GeographicLib::GravityCircle* m_pGravityCircle;
47 
48  // the finalizer frees the unmanaged memory when the object is destroyed.
49  !GravityCircle(void);
50  public:
51  /**
52  * A constructor that is initialized from an unmanaged
53  * GeographicLib::GravityCircle. For internal use only. Developers
54  * should use GravityModel::Circle to create a GavityCircle object.
55  **********************************************************************/
57 
58  /**
59  * The destructor calls the finalizer.
60  **********************************************************************/
62  { this->!GravityCircle(); }
63 
64  /** \name Compute the gravitational field
65  **********************************************************************/
66  ///@{
67  /**
68  * Evaluate the gravity.
69  *
70  * @param[in] lon the geographic longitude (degrees).
71  * @param[out] gx the easterly component of the acceleration
72  * (m s<sup>&minus;2</sup>).
73  * @param[out] gy the northerly component of the acceleration
74  * (m s<sup>&minus;2</sup>).
75  * @param[out] gz the upward component of the acceleration
76  * (m s<sup>&minus;2</sup>); this is usually negative.
77  * @return \e W the sum of the gravitational and centrifugal potentials.
78  *
79  * The function includes the effects of the earth's rotation.
80  **********************************************************************/
81  double Gravity(double lon,
82  [System::Runtime::InteropServices::Out] double% gx,
83  [System::Runtime::InteropServices::Out] double% gy,
84  [System::Runtime::InteropServices::Out] double% gz);
85 
86  /**
87  * Evaluate the gravity disturbance vector.
88  *
89  * @param[in] lon the geographic longitude (degrees).
90  * @param[out] deltax the easterly component of the disturbance vector
91  * (m s<sup>&minus;2</sup>).
92  * @param[out] deltay the northerly component of the disturbance vector
93  * (m s<sup>&minus;2</sup>).
94  * @param[out] deltaz the upward component of the disturbance vector
95  * (m s<sup>&minus;2</sup>).
96  * @return \e T the corresponding disturbing potential.
97  **********************************************************************/
98  double Disturbance(double lon,
99  [System::Runtime::InteropServices::Out] double% deltax,
100  [System::Runtime::InteropServices::Out] double% deltay,
101  [System::Runtime::InteropServices::Out] double% deltaz);
102 
103  /**
104  * Evaluate the geoid height.
105  *
106  * @param[in] lon the geographic longitude (degrees).
107  * @return \e N the height of the geoid above the reference ellipsoid
108  * (meters).
109  *
110  * Some approximations are made in computing the geoid height so that the
111  * results of the NGA codes are reproduced accurately. Details are given
112  * in \ref gravitygeoid.
113  **********************************************************************/
114  double GeoidHeight(double lon);
115 
116  /**
117  * Evaluate the components of the gravity anomaly vector using the
118  * spherical approximation.
119  *
120  * @param[in] lon the geographic longitude (degrees).
121  * @param[out] Dg01 the gravity anomaly (m s<sup>&minus;2</sup>).
122  * @param[out] xi the northerly component of the deflection of the vertical
123  * (degrees).
124  * @param[out] eta the easterly component of the deflection of the vertical
125  * (degrees).
126  *
127  * The spherical approximation (see Heiskanen and Moritz, Sec 2-14) is used
128  * so that the results of the NGA codes are reproduced accurately.
129  * approximations used here. Details are given in \ref gravitygeoid.
130  **********************************************************************/
131  void SphericalAnomaly(double lon,
132  [System::Runtime::InteropServices::Out] double% Dg01,
133  [System::Runtime::InteropServices::Out] double% xi,
134  [System::Runtime::InteropServices::Out] double% eta);
135 
136  /**
137  * Evaluate the components of the acceleration due to gravity and the
138  * centrifugal acceleration in geocentric coordinates.
139  *
140  * @param[in] lon the geographic longitude (degrees).
141  * @param[out] gX the \e X component of the acceleration
142  * (m s<sup>&minus;2</sup>).
143  * @param[out] gY the \e Y component of the acceleration
144  * (m s<sup>&minus;2</sup>).
145  * @param[out] gZ the \e Z component of the acceleration
146  * (m s<sup>&minus;2</sup>).
147  * @return \e W = \e V + &Phi; the sum of the gravitational and
148  * centrifugal potentials (m<sup>2</sup> s<sup>&minus;2</sup>).
149  **********************************************************************/
150  double W(double lon,
151  [System::Runtime::InteropServices::Out] double% gX,
152  [System::Runtime::InteropServices::Out] double% gY,
153  [System::Runtime::InteropServices::Out] double% gZ);
154 
155  /**
156  * Evaluate the components of the acceleration due to gravity in geocentric
157  * coordinates.
158  *
159  * @param[in] lon the geographic longitude (degrees).
160  * @param[out] GX the \e X component of the acceleration
161  * (m s<sup>&minus;2</sup>).
162  * @param[out] GY the \e Y component of the acceleration
163  * (m s<sup>&minus;2</sup>).
164  * @param[out] GZ the \e Z component of the acceleration
165  * (m s<sup>&minus;2</sup>).
166  * @return \e V = \e W - &Phi; the gravitational potential
167  * (m<sup>2</sup> s<sup>&minus;2</sup>).
168  **********************************************************************/
169  double V(double lon,
170  [System::Runtime::InteropServices::Out] double% GX,
171  [System::Runtime::InteropServices::Out] double% GY,
172  [System::Runtime::InteropServices::Out] double% GZ);
173 
174  /**
175  * Evaluate the components of the gravity disturbance in geocentric
176  * coordinates.
177  *
178  * @param[in] lon the geographic longitude (degrees).
179  * @param[out] deltaX the \e X component of the gravity disturbance
180  * (m s<sup>&minus;2</sup>).
181  * @param[out] deltaY the \e Y component of the gravity disturbance
182  * (m s<sup>&minus;2</sup>).
183  * @param[out] deltaZ the \e Z component of the gravity disturbance
184  * (m s<sup>&minus;2</sup>).
185  * @return \e T = \e W - \e U the disturbing potential (also called the
186  * anomalous potential) (m<sup>2</sup> s<sup>&minus;2</sup>).
187  **********************************************************************/
188  double T(double lon,
189  [System::Runtime::InteropServices::Out] double% deltaX,
190  [System::Runtime::InteropServices::Out] double% deltaY,
191  [System::Runtime::InteropServices::Out] double% deltaZ);
192 
193  /**
194  * Evaluate disturbing potential in geocentric coordinates.
195  *
196  * @param[in] lon the geographic longitude (degrees).
197  * @return \e T = \e W - \e U the disturbing potential (also called the
198  * anomalous potential) (m<sup>2</sup> s<sup>&minus;2</sup>).
199  **********************************************************************/
200  double T(double lon);
201 
202  ///@}
203 
204  /** \name Inspector functions
205  **********************************************************************/
206  ///@{
207  /**
208  * @return true if the object has been initialized.
209  **********************************************************************/
210  property bool Init { bool get(); }
211 
212  /**
213  * @return \e a the equatorial radius of the ellipsoid (meters). This is
214  * the value inherited from the GravityModel object used in the
215  * constructor.
216  * This property throws an exception if the GravityCircles has not
217  * been initialized.
218  **********************************************************************/
219  property double MajorRadius { double get(); }
220 
221  /**
222  * @return \e f the flattening of the ellipsoid. This is the value
223  * inherited from the GravityModel object used in the constructor.
224  * This property throws an exception if the GravityCircles has not
225  * been initialized.
226  **********************************************************************/
227  property double Flattening { double get(); }
228 
229  /**
230  * @return the latitude of the circle (degrees).
231  * This property throws an exception if the GravityCircles has not
232  * been initialized.
233  **********************************************************************/
234  property double Latitude { double get(); }
235 
236  /**
237  * @return the height of the circle (meters).
238  * This property throws an exception if the GravityCircles has not
239  * been initialized.
240  **********************************************************************/
241  property double Height { double get(); }
242 
243  /**
244  * @return \e caps the computational capabilities that this object was
245  * constructed with.
246  **********************************************************************/
248 
249  /**
250  * @param[in] testcaps a set of bitor'ed GeodesicLine::mask values.
251  * @return true if the GeodesicLine object has all these capabilities.
252  **********************************************************************/
253  bool Capabilities(GravityModel::Mask testcaps);
254  ///@}
255  };
256 } // namespace NETGeographicLib