NETGeographicLib 1.52
Loading...
Searching...
No Matches
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
13namespace 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::Geocentric.
Definition: Geocentric.h:69
.NET wrapper for GeographicLib::MagneticCircle.
.NET wrapper for GeographicLib::MagneticModel.
Definition: MagneticModel.h:70
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()
System::String^ MagneticModelDirectory
MagneticModel(System::String^ name, System::String^ path)
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)
MagneticModel(System::String^ name, System::String^ path, Geocentric^ earth)
static System::String ^ DefaultMagneticName()
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, [System::Runtime::InteropServices::Out] double% Bxt, [System::Runtime::InteropServices::Out] double% Byt, [System::Runtime::InteropServices::Out] double% Bzt)
MagneticCircle ^ Circle(double t, double lat, double h)