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