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