NETGeographicLib  1.38
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Pages
MagneticModel.h
Go to the documentation of this file.
1 #pragma once
2 /**
3  * \file NETGeographicLib/MagneticModel.h
4  * \brief Header for NETGeographicLib::MagneticModel 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  ref class MagneticCircle;
16  ref class Geocentric;
17  /**
18  * \brief .NET wrapper for GeographicLib::MagneticModel.
19  *
20  * This class allows .NET applications to access GeographicLib::MagneticModel.
21  *
22  * Evaluate the earth's magnetic field according to a model. At present only
23  * internal magnetic fields are handled. These are due to the earth's code
24  * and crust; these vary slowly (over many years). Excluded are the effects
25  * of currents in the ionosphere and magnetosphere which have daily and
26  * annual variations.
27  *
28  * See \ref magnetic for details of how to install the magnetic model and the
29  * data format.
30  *
31  * See
32  * - General information:
33  * - http://geomag.org/models/index.html
34  * - WMM2010:
35  * - http://ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml
36  * - http://ngdc.noaa.gov/geomag/WMM/data/WMM2010/WMM2010COF.zip
37  * - IGRF11:
38  * - http://ngdc.noaa.gov/IAGA/vmod/igrf.html
39  * - http://ngdc.noaa.gov/IAGA/vmod/igrf11coeffs.txt
40  * - http://ngdc.noaa.gov/IAGA/vmod/geomag70_linux.tar.gz
41  * - EMM2010:
42  * - http://ngdc.noaa.gov/geomag/EMM/index.html
43  * - http://ngdc.noaa.gov/geomag/EMM/data/geomag/EMM2010_Sph_Windows_Linux.zip
44  *
45  * C# Example:
46  * \include example-MagneticModel.cs
47  * Managed C++ Example:
48  * \include example-MagneticModel.cpp
49  * Visual Basic Example:
50  * \include example-MagneticModel.vb
51  *
52  * <B>INTERFACE DIFFERENCES:</B><BR>
53  * The () operator has been replaced with Field.
54  *
55  * The following functions are implemented as properties:
56  * Description, DateTime, MagneticFile, MagneticModelName,
57  * MagneticModelDirectory, MinHeight, MaxHeight, MinTime, MaxTime,
58  * MajorRadius, and Flattening.
59  **********************************************************************/
60  public ref class MagneticModel
61  {
62  private:
63  // The pointer to the unmanaged GeographicLib::MagneticModel.
64  const GeographicLib::MagneticModel* m_pMagneticModel;
65 
66  // The finalizer frees the unmanaged memory when the object is destroyed.
67  !MagneticModel(void);
68  public:
69 
70  /** \name Setting up the magnetic model
71  **********************************************************************/
72  ///@{
73  /**
74  * Construct a magnetic model.
75  *
76  * @param[in] name the name of the model.
77  * @param[in] path (optional) directory for data file.
78  * @param[in] earth (optional) Geocentric object for converting
79  * coordinates.
80  * @exception GeographicErr if the data file cannot be found, is
81  * unreadable, or is corrupt.
82  * @exception std::bad_alloc if the memory necessary for storing the model
83  * can't be allocated.
84  *
85  * A filename is formed by appending ".wmm" (World Magnetic Model) to the
86  * name. If \e path is specified (and is non-empty), then the file is
87  * loaded from directory, \e path. Otherwise the path is given by the
88  * DefaultMagneticPath().
89  *
90  * This file contains the metadata which specifies the properties of the
91  * model. The coefficients for the spherical harmonic sums are obtained
92  * from a file obtained by appending ".cof" to metadata file (so the
93  * filename ends in ".wwm.cof").
94  *
95  * The model is not tied to a particular ellipsoidal model of the earth.
96  * The final earth argument to the constructor specifies an ellipsoid to
97  * allow geodetic coordinates to the transformed into the spherical
98  * coordinates used in the spherical harmonic sum.
99  **********************************************************************/
100  MagneticModel(System::String^ name,
101  System::String^ path,
102  Geocentric^ earth);
103  /**
104  * Construct a magnetic model that assumes the WGS84 ellipsoid.
105  *
106  * @param[in] name the name of the model.
107  * @param[in] path (optional) directory for data file.
108  * @exception GeographicErr if the data file cannot be found, is
109  * unreadable, or is corrupt.
110  * @exception GeographicErr if the memory necessary for storing the model
111  * can't be allocated.
112  *
113  * A filename is formed by appending ".wmm" (World Magnetic Model) to the
114  * name. If \e path is specified (and is non-empty), then the file is
115  * loaded from directory, \e path. Otherwise the path is given by the
116  * DefaultMagneticPath().
117  *
118  * This file contains the metadata which specifies the properties of the
119  * model. The coefficients for the spherical harmonic sums are obtained
120  * from a file obtained by appending ".cof" to metadata file (so the
121  * filename ends in ".wwm.cof").
122  *
123  * The model is not tied to a particular ellipsoidal model of the earth.
124  * The final earth argument to the constructor specifies an ellipsoid to
125  * allow geodetic coordinates to the transformed into the spherical
126  * coordinates used in the spherical harmonic sum.
127  **********************************************************************/
128  MagneticModel(System::String^ name,
129  System::String^ path);
130 
131  ///@}
132  /**
133  * The destructor calls the finalizer.
134  **********************************************************************/
136  { this->!MagneticModel(); }
137 
138  /** \name Compute the magnetic field
139  **********************************************************************/
140  ///@{
141  /**
142  * Evaluate the components of the geomagnetic field.
143  *
144  * @param[in] t the time (years).
145  * @param[in] lat latitude of the point (degrees).
146  * @param[in] lon longitude of the point (degrees).
147  * @param[in] h the height of the point above the ellipsoid (meters).
148  * @param[out] Bx the easterly component of the magnetic field (nanotesla).
149  * @param[out] By the northerly component of the magnetic field (nanotesla).
150  * @param[out] Bz the vertical (up) component of the magnetic field
151  * (nanotesla).
152  **********************************************************************/
153  void Field(double t, double lat, double lon, double h,
154  [System::Runtime::InteropServices::Out] double% Bx,
155  [System::Runtime::InteropServices::Out] double% By,
156  [System::Runtime::InteropServices::Out] double% Bz);
157 
158  /**
159  * Evaluate the components of the geomagnetic field and their time
160  * derivatives
161  *
162  * @param[in] t the time (years).
163  * @param[in] lat latitude of the point (degrees).
164  * @param[in] lon longitude of the point (degrees).
165  * @param[in] h the height of the point above the ellipsoid (meters).
166  * @param[out] Bx the easterly component of the magnetic field (nanotesla).
167  * @param[out] By the northerly component of the magnetic field (nanotesla).
168  * @param[out] Bz the vertical (up) component of the magnetic field
169  * (nanotesla).
170  * @param[out] Bxt the rate of change of \e Bx (nT/yr).
171  * @param[out] Byt the rate of change of \e By (nT/yr).
172  * @param[out] Bzt the rate of change of \e Bz (nT/yr).
173  **********************************************************************/
174  void Field(double t, double lat, double lon, double h,
175  [System::Runtime::InteropServices::Out] double% Bx,
176  [System::Runtime::InteropServices::Out] double% By,
177  [System::Runtime::InteropServices::Out] double% Bz,
178  [System::Runtime::InteropServices::Out] double% Bxt,
179  [System::Runtime::InteropServices::Out] double% Byt,
180  [System::Runtime::InteropServices::Out] double% Bzt);
181 
182  /**
183  * Create a MagneticCircle object to allow the geomagnetic field at many
184  * points with constant \e lat, \e h, and \e t and varying \e lon to be
185  * computed efficiently.
186  *
187  * @param[in] t the time (years).
188  * @param[in] lat latitude of the point (degrees).
189  * @param[in] h the height of the point above the ellipsoid (meters).
190  * @exception std::bad_alloc if the memory necessary for creating a
191  * MagneticCircle can't be allocated.
192  * @return a MagneticCircle object whose MagneticCircle::Field(double
193  * lon) member function computes the field at particular values of \e
194  * lon.
195  *
196  * If the field at several points on a circle of latitude need to be
197  * calculated then creating a MagneticCircle and using its member functions
198  * will be substantially faster, especially for high-degree models.
199  **********************************************************************/
200  MagneticCircle^ Circle(double t, double lat, double h);
201 
202  /**
203  * Compute various quantities dependent on the magnetic field.
204  *
205  * @param[in] Bx the \e x (easterly) component of the magnetic field (nT).
206  * @param[in] By the \e y (northerly) component of the magnetic field (nT).
207  * @param[in] Bz the \e z (vertical, up positive) component of the magnetic
208  * field (nT).
209  * @param[out] H the horizontal magnetic field (nT).
210  * @param[out] F the total magnetic field (nT).
211  * @param[out] D the declination of the field (degrees east of north).
212  * @param[out] I the inclination of the field (degrees down from
213  * horizontal).
214  **********************************************************************/
215  static void FieldComponents(double Bx, double By, double Bz,
216  [System::Runtime::InteropServices::Out] double% H,
217  [System::Runtime::InteropServices::Out] double% F,
218  [System::Runtime::InteropServices::Out] double% D,
219  [System::Runtime::InteropServices::Out] double% I);
220 
221  /**
222  * Compute various quantities dependent on the magnetic field and its rate
223  * of change.
224  *
225  * @param[in] Bx the \e x (easterly) component of the magnetic field (nT).
226  * @param[in] By the \e y (northerly) component of the magnetic field (nT).
227  * @param[in] Bz the \e z (vertical, up positive) component of the magnetic
228  * field (nT).
229  * @param[in] Bxt the rate of change of \e Bx (nT/yr).
230  * @param[in] Byt the rate of change of \e By (nT/yr).
231  * @param[in] Bzt the rate of change of \e Bz (nT/yr).
232  * @param[out] H the horizontal magnetic field (nT).
233  * @param[out] F the total magnetic field (nT).
234  * @param[out] D the declination of the field (degrees east of north).
235  * @param[out] I the inclination of the field (degrees down from
236  * horizontal).
237  * @param[out] Ht the rate of change of \e H (nT/yr).
238  * @param[out] Ft the rate of change of \e F (nT/yr).
239  * @param[out] Dt the rate of change of \e D (degrees/yr).
240  * @param[out] It the rate of change of \e I (degrees/yr).
241  **********************************************************************/
242  static void FieldComponents(double Bx, double By, double Bz,
243  double Bxt, double Byt, double Bzt,
244  [System::Runtime::InteropServices::Out] double% H,
245  [System::Runtime::InteropServices::Out] double% F,
246  [System::Runtime::InteropServices::Out] double% D,
247  [System::Runtime::InteropServices::Out] double% I,
248  [System::Runtime::InteropServices::Out] double% Ht,
249  [System::Runtime::InteropServices::Out] double% Ft,
250  [System::Runtime::InteropServices::Out] double% Dt,
251  [System::Runtime::InteropServices::Out] double% It);
252  ///@}
253 
254  /** \name Inspector functions
255  **********************************************************************/
256  ///@{
257  /**
258  * @return the description of the magnetic model, if available, from the
259  * Description file in the data file; if absent, return "NONE".
260  **********************************************************************/
261  property System::String^ Description { System::String^ get(); }
262 
263  /**
264  * @return date of the model, if available, from the ReleaseDate field in
265  * the data file; if absent, return "UNKNOWN".
266  **********************************************************************/
267  property System::String^ DateTime { System::String^ get(); }
268 
269  /**
270  * @return full file name used to load the magnetic model.
271  **********************************************************************/
272  property System::String^ MagneticFile { System::String^ get(); }
273 
274  /**
275  * @return "name" used to load the magnetic model (from the first argument
276  * of the constructor, but this may be overridden by the model file).
277  **********************************************************************/
278  property System::String^ MagneticModelName { System::String^ get(); }
279 
280  /**
281  * @return directory used to load the magnetic model.
282  **********************************************************************/
283  property System::String^ MagneticModelDirectory { System::String^ get(); }
284 
285  /**
286  * @return the minimum height above the ellipsoid (in meters) for which
287  * this MagneticModel should be used.
288  *
289  * Because the model will typically provide useful results
290  * slightly outside the range of allowed heights, no check of \e t
291  * argument is made by MagneticModel::Field() or
292  * MagneticModel::Circle.
293  **********************************************************************/
294  property double MinHeight { double get(); }
295 
296  /**
297  * @return the maximum height above the ellipsoid (in meters) for which
298  * this MagneticModel should be used.
299  *
300  * Because the model will typically provide useful results
301  * slightly outside the range of allowed heights, no check of \e t
302  * argument is made by MagneticModel::Field() or
303  * MagneticModel::Circle.
304  **********************************************************************/
305  property double MaxHeight { double get(); }
306 
307  /**
308  * @return the minimum time (in years) for which this MagneticModel should
309  * be used.
310  *
311  * Because the model will typically provide useful results
312  * slightly outside the range of allowed times, no check of \e t
313  * argument is made by MagneticModel::Field() or
314  * MagneticModel::Circle.
315  **********************************************************************/
316  property double MinTime { double get(); }
317 
318  /**
319  * @return the maximum time (in years) for which this MagneticModel should
320  * be used.
321  *
322  * Because the model will typically provide useful results
323  * slightly outside the range of allowed times, no check of \e t
324  * argument is made by MagneticModel::Field() or
325  * MagneticModel::Circle.
326  **********************************************************************/
327  property double MaxTime { double get(); }
328 
329  /**
330  * @return \e a the equatorial radius of the ellipsoid (meters). This is
331  * the value of \e a inherited from the Geocentric object used in the
332  * constructor.
333  **********************************************************************/
334  property double MajorRadius { double get(); }
335 
336  /**
337  * @return \e f the flattening of the ellipsoid. This is the value
338  * inherited from the Geocentric object used in the constructor.
339  **********************************************************************/
340  property double Flattening { double get(); }
341  ///@}
342 
343  /**
344  * @return the default path for magnetic model data files.
345  *
346  * This is the value of the environment variable
347  * GEOGRAPHICLIB_MAGNETIC_PATH, if set; otherwise, it is
348  * $GEOGRAPHICLIB_DATA/magnetic if the environment variable
349  * GEOGRAPHICLIB_DATA is set; otherwise, it is a compile-time default
350  * (/usr/local/share/GeographicLib/magnetic on non-Windows systems and
351  * C:/ProgramData/GeographicLib/magnetic on Windows systems).
352  **********************************************************************/
353  static System::String^ DefaultMagneticPath();
354 
355  /**
356  * @return the default name for the magnetic model.
357  *
358  * This is the value of the environment variable
359  * GEOGRAPHICLIB_MAGNETIC_NAME, if set, otherwise, it is "wmm2010".
360  * The MagneticModel class does not use this function; it is just
361  * provided as a convenience for a calling program when constructing a
362  * MagneticModel object.
363  **********************************************************************/
364  static System::String^ DefaultMagneticName();
365  };
366 } //namespace NETGeographicLib