00001 #pragma once 00002 /** 00003 * \file NETGeographicLib/MagneticModel.h 00004 * \brief Header for NETGeographicLib::MagneticModel class 00005 * 00006 * NETGeographicLib is copyright (c) Scott Heiman (2013) 00007 * GeographicLib is Copyright (c) Charles Karney (2010-2012) 00008 * <charles@karney.com> and licensed under the MIT/X11 License. 00009 * For more information, see 00010 * http://geographiclib.sourceforge.net/ 00011 **********************************************************************/ 00012 00013 namespace NETGeographicLib 00014 { 00015 ref class MagneticCircle; 00016 ref class Geocentric; 00017 /** 00018 * \brief .NET wrapper for GeographicLib::MagneticModel. 00019 * 00020 * This class allows .NET applications to access GeographicLib::MagneticModel. 00021 * 00022 * Evaluate the earth's magnetic field according to a model. At present only 00023 * internal magnetic fields are handled. These are due to the earth's code 00024 * and crust; these vary slowly (over many years). Excluded are the effects 00025 * of currents in the ionosphere and magnetosphere which have daily and 00026 * annual variations. 00027 * 00028 * See \ref magnetic for details of how to install the magnetic model and the 00029 * data format. 00030 * 00031 * See 00032 * - General information: 00033 * - http://geomag.org/models/index.html 00034 * - WMM2010: 00035 * - http://ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml 00036 * - http://ngdc.noaa.gov/geomag/WMM/data/WMM2010/WMM2010COF.zip 00037 * - IGRF11: 00038 * - http://ngdc.noaa.gov/IAGA/vmod/igrf.html 00039 * - http://ngdc.noaa.gov/IAGA/vmod/igrf11coeffs.txt 00040 * - http://ngdc.noaa.gov/IAGA/vmod/geomag70_linux.tar.gz 00041 * - EMM2010: 00042 * - http://ngdc.noaa.gov/geomag/EMM/index.html 00043 * - http://ngdc.noaa.gov/geomag/EMM/data/geomag/EMM2010_Sph_Windows_Linux.zip 00044 * 00045 * C# Example: 00046 * \include example-MagneticModel.cs 00047 * Managed C++ Example: 00048 * \include example-MagneticModel.cpp 00049 * Visual Basic Example: 00050 * \include example-MagneticModel.vb 00051 * 00052 * <B>INTERFACE DIFFERENCES:</B><BR> 00053 * The () operator has been replaced with Field. 00054 * 00055 * The following functions are implemented as properties: 00056 * Description, DateTime, MagneticFile, MagneticModelName, 00057 * MagneticModelDirectory, MinHeight, MaxHeight, MinTime, MaxTime, 00058 * MajorRadius, and Flattening. 00059 **********************************************************************/ 00060 public ref class MagneticModel 00061 { 00062 private: 00063 // The pointer to the unmanaged GeographicLib::MagneticModel. 00064 const GeographicLib::MagneticModel* m_pMagneticModel; 00065 00066 // The finalizer frees the unmanaged memory when the object is destroyed. 00067 !MagneticModel(void); 00068 public: 00069 00070 /** \name Setting up the magnetic model 00071 **********************************************************************/ 00072 ///@{ 00073 /** 00074 * Construct a magnetic model. 00075 * 00076 * @param[in] name the name of the model. 00077 * @param[in] path (optional) directory for data file. 00078 * @param[in] earth (optional) Geocentric object for converting 00079 * coordinates. 00080 * @exception GeographicErr if the data file cannot be found, is 00081 * unreadable, or is corrupt. 00082 * @exception std::bad_alloc if the memory necessary for storing the model 00083 * can't be allocated. 00084 * 00085 * A filename is formed by appending ".wmm" (World Magnetic Model) to the 00086 * name. If \e path is specified (and is non-empty), then the file is 00087 * loaded from directory, \e path. Otherwise the path is given by the 00088 * DefaultMagneticPath(). 00089 * 00090 * This file contains the metadata which specifies the properties of the 00091 * model. The coefficients for the spherical harmonic sums are obtained 00092 * from a file obtained by appending ".cof" to metadata file (so the 00093 * filename ends in ".wwm.cof"). 00094 * 00095 * The model is not tied to a particular ellipsoidal model of the earth. 00096 * The final earth argument to the constructor specifies an ellipsoid to 00097 * allow geodetic coordinates to the transformed into the spherical 00098 * coordinates used in the spherical harmonic sum. 00099 **********************************************************************/ 00100 MagneticModel(System::String^ name, 00101 System::String^ path, 00102 Geocentric^ earth); 00103 /** 00104 * Construct a magnetic model that assumes the WGS84 ellipsoid. 00105 * 00106 * @param[in] name the name of the model. 00107 * @param[in] path (optional) directory for data file. 00108 * @exception GeographicErr if the data file cannot be found, is 00109 * unreadable, or is corrupt. 00110 * @exception GeographicErr if the memory necessary for storing the model 00111 * can't be allocated. 00112 * 00113 * A filename is formed by appending ".wmm" (World Magnetic Model) to the 00114 * name. If \e path is specified (and is non-empty), then the file is 00115 * loaded from directory, \e path. Otherwise the path is given by the 00116 * DefaultMagneticPath(). 00117 * 00118 * This file contains the metadata which specifies the properties of the 00119 * model. The coefficients for the spherical harmonic sums are obtained 00120 * from a file obtained by appending ".cof" to metadata file (so the 00121 * filename ends in ".wwm.cof"). 00122 * 00123 * The model is not tied to a particular ellipsoidal model of the earth. 00124 * The final earth argument to the constructor specifies an ellipsoid to 00125 * allow geodetic coordinates to the transformed into the spherical 00126 * coordinates used in the spherical harmonic sum. 00127 **********************************************************************/ 00128 MagneticModel(System::String^ name, 00129 System::String^ path); 00130 00131 ///@} 00132 /** 00133 * The destructor calls the finalizer. 00134 **********************************************************************/ 00135 ~MagneticModel() 00136 { this->!MagneticModel(); } 00137 00138 /** \name Compute the magnetic field 00139 **********************************************************************/ 00140 ///@{ 00141 /** 00142 * Evaluate the components of the geomagnetic field. 00143 * 00144 * @param[in] t the time (years). 00145 * @param[in] lat latitude of the point (degrees). 00146 * @param[in] lon longitude of the point (degrees). 00147 * @param[in] h the height of the point above the ellipsoid (meters). 00148 * @param[out] Bx the easterly component of the magnetic field (nanotesla). 00149 * @param[out] By the northerly component of the magnetic field (nanotesla). 00150 * @param[out] Bz the vertical (up) component of the magnetic field 00151 * (nanotesla). 00152 **********************************************************************/ 00153 void Field(double t, double lat, double lon, double h, 00154 [System::Runtime::InteropServices::Out] double% Bx, 00155 [System::Runtime::InteropServices::Out] double% By, 00156 [System::Runtime::InteropServices::Out] double% Bz); 00157 00158 /** 00159 * Evaluate the components of the geomagnetic field and their time 00160 * derivatives 00161 * 00162 * @param[in] t the time (years). 00163 * @param[in] lat latitude of the point (degrees). 00164 * @param[in] lon longitude of the point (degrees). 00165 * @param[in] h the height of the point above the ellipsoid (meters). 00166 * @param[out] Bx the easterly component of the magnetic field (nanotesla). 00167 * @param[out] By the northerly component of the magnetic field (nanotesla). 00168 * @param[out] Bz the vertical (up) component of the magnetic field 00169 * (nanotesla). 00170 * @param[out] Bxt the rate of change of \e Bx (nT/yr). 00171 * @param[out] Byt the rate of change of \e By (nT/yr). 00172 * @param[out] Bzt the rate of change of \e Bz (nT/yr). 00173 **********************************************************************/ 00174 void Field(double t, double lat, double lon, double h, 00175 [System::Runtime::InteropServices::Out] double% Bx, 00176 [System::Runtime::InteropServices::Out] double% By, 00177 [System::Runtime::InteropServices::Out] double% Bz, 00178 [System::Runtime::InteropServices::Out] double% Bxt, 00179 [System::Runtime::InteropServices::Out] double% Byt, 00180 [System::Runtime::InteropServices::Out] double% Bzt); 00181 00182 /** 00183 * Create a MagneticCircle object to allow the geomagnetic field at many 00184 * points with constant \e lat, \e h, and \e t and varying \e lon to be 00185 * computed efficiently. 00186 * 00187 * @param[in] t the time (years). 00188 * @param[in] lat latitude of the point (degrees). 00189 * @param[in] h the height of the point above the ellipsoid (meters). 00190 * @exception std::bad_alloc if the memory necessary for creating a 00191 * MagneticCircle can't be allocated. 00192 * @return a MagneticCircle object whose MagneticCircle::Field(double 00193 * lon) member function computes the field at particular values of \e 00194 * lon. 00195 * 00196 * If the field at several points on a circle of latitude need to be 00197 * calculated then creating a MagneticCircle and using its member functions 00198 * will be substantially faster, especially for high-degree models. 00199 **********************************************************************/ 00200 MagneticCircle^ Circle(double t, double lat, double h); 00201 00202 /** 00203 * Compute various quantities dependent on the magnetic field. 00204 * 00205 * @param[in] Bx the \e x (easterly) component of the magnetic field (nT). 00206 * @param[in] By the \e y (northerly) component of the magnetic field (nT). 00207 * @param[in] Bz the \e z (vertical, up positive) component of the magnetic 00208 * field (nT). 00209 * @param[out] H the horizontal magnetic field (nT). 00210 * @param[out] F the total magnetic field (nT). 00211 * @param[out] D the declination of the field (degrees east of north). 00212 * @param[out] I the inclination of the field (degrees down from 00213 * horizontal). 00214 **********************************************************************/ 00215 static void FieldComponents(double Bx, double By, double Bz, 00216 [System::Runtime::InteropServices::Out] double% H, 00217 [System::Runtime::InteropServices::Out] double% F, 00218 [System::Runtime::InteropServices::Out] double% D, 00219 [System::Runtime::InteropServices::Out] double% I); 00220 00221 /** 00222 * Compute various quantities dependent on the magnetic field and its rate 00223 * of change. 00224 * 00225 * @param[in] Bx the \e x (easterly) component of the magnetic field (nT). 00226 * @param[in] By the \e y (northerly) component of the magnetic field (nT). 00227 * @param[in] Bz the \e z (vertical, up positive) component of the magnetic 00228 * field (nT). 00229 * @param[in] Bxt the rate of change of \e Bx (nT/yr). 00230 * @param[in] Byt the rate of change of \e By (nT/yr). 00231 * @param[in] Bzt the rate of change of \e Bz (nT/yr). 00232 * @param[out] H the horizontal magnetic field (nT). 00233 * @param[out] F the total magnetic field (nT). 00234 * @param[out] D the declination of the field (degrees east of north). 00235 * @param[out] I the inclination of the field (degrees down from 00236 * horizontal). 00237 * @param[out] Ht the rate of change of \e H (nT/yr). 00238 * @param[out] Ft the rate of change of \e F (nT/yr). 00239 * @param[out] Dt the rate of change of \e D (degrees/yr). 00240 * @param[out] It the rate of change of \e I (degrees/yr). 00241 **********************************************************************/ 00242 static void FieldComponents(double Bx, double By, double Bz, 00243 double Bxt, double Byt, double Bzt, 00244 [System::Runtime::InteropServices::Out] double% H, 00245 [System::Runtime::InteropServices::Out] double% F, 00246 [System::Runtime::InteropServices::Out] double% D, 00247 [System::Runtime::InteropServices::Out] double% I, 00248 [System::Runtime::InteropServices::Out] double% Ht, 00249 [System::Runtime::InteropServices::Out] double% Ft, 00250 [System::Runtime::InteropServices::Out] double% Dt, 00251 [System::Runtime::InteropServices::Out] double% It); 00252 ///@} 00253 00254 /** \name Inspector functions 00255 **********************************************************************/ 00256 ///@{ 00257 /** 00258 * @return the description of the magnetic model, if available, from the 00259 * Description file in the data file; if absent, return "NONE". 00260 **********************************************************************/ 00261 property System::String^ Description { System::String^ get(); } 00262 00263 /** 00264 * @return date of the model, if available, from the ReleaseDate field in 00265 * the data file; if absent, return "UNKNOWN". 00266 **********************************************************************/ 00267 property System::String^ DateTime { System::String^ get(); } 00268 00269 /** 00270 * @return full file name used to load the magnetic model. 00271 **********************************************************************/ 00272 property System::String^ MagneticFile { System::String^ get(); } 00273 00274 /** 00275 * @return "name" used to load the magnetic model (from the first argument 00276 * of the constructor, but this may be overridden by the model file). 00277 **********************************************************************/ 00278 property System::String^ MagneticModelName { System::String^ get(); } 00279 00280 /** 00281 * @return directory used to load the magnetic model. 00282 **********************************************************************/ 00283 property System::String^ MagneticModelDirectory { System::String^ get(); } 00284 00285 /** 00286 * @return the minimum height above the ellipsoid (in meters) for which 00287 * this MagneticModel should be used. 00288 * 00289 * Because the model will typically provide useful results 00290 * slightly outside the range of allowed heights, no check of \e t 00291 * argument is made by MagneticModel::Field() or 00292 * MagneticModel::Circle. 00293 **********************************************************************/ 00294 property double MinHeight { double get(); } 00295 00296 /** 00297 * @return the maximum height above the ellipsoid (in meters) for which 00298 * this MagneticModel should be used. 00299 * 00300 * Because the model will typically provide useful results 00301 * slightly outside the range of allowed heights, no check of \e t 00302 * argument is made by MagneticModel::Field() or 00303 * MagneticModel::Circle. 00304 **********************************************************************/ 00305 property double MaxHeight { double get(); } 00306 00307 /** 00308 * @return the minimum time (in years) for which this MagneticModel should 00309 * be used. 00310 * 00311 * Because the model will typically provide useful results 00312 * slightly outside the range of allowed times, no check of \e t 00313 * argument is made by MagneticModel::Field() or 00314 * MagneticModel::Circle. 00315 **********************************************************************/ 00316 property double MinTime { double get(); } 00317 00318 /** 00319 * @return the maximum time (in years) for which this MagneticModel should 00320 * be used. 00321 * 00322 * Because the model will typically provide useful results 00323 * slightly outside the range of allowed times, no check of \e t 00324 * argument is made by MagneticModel::Field() or 00325 * MagneticModel::Circle. 00326 **********************************************************************/ 00327 property double MaxTime { double get(); } 00328 00329 /** 00330 * @return \e a the equatorial radius of the ellipsoid (meters). This is 00331 * the value of \e a inherited from the Geocentric object used in the 00332 * constructor. 00333 **********************************************************************/ 00334 property double MajorRadius { double get(); } 00335 00336 /** 00337 * @return \e f the flattening of the ellipsoid. This is the value 00338 * inherited from the Geocentric object used in the constructor. 00339 **********************************************************************/ 00340 property double Flattening { double get(); } 00341 ///@} 00342 00343 /** 00344 * @return the default path for magnetic model data files. 00345 * 00346 * This is the value of the environment variable 00347 * GEOGRAPHICLIB_MAGNETIC_PATH, if set; otherwise, it is 00348 * $GEOGRAPHICLIB_DATA/magnetic if the environment variable 00349 * GEOGRAPHICLIB_DATA is set; otherwise, it is a compile-time default 00350 * (/usr/local/share/GeographicLib/magnetic on non-Windows systems and 00351 * C:/ProgramData/GeographicLib/magnetic on Windows systems). 00352 **********************************************************************/ 00353 static System::String^ DefaultMagneticPath(); 00354 00355 /** 00356 * @return the default name for the magnetic model. 00357 * 00358 * This is the value of the environment variable 00359 * GEOGRAPHICLIB_MAGNETIC_NAME, if set, otherwise, it is "wmm2010". 00360 * The MagneticModel class does not use this function; it is just 00361 * provided as a convenience for a calling program when constructing a 00362 * MagneticModel object. 00363 **********************************************************************/ 00364 static System::String^ DefaultMagneticName(); 00365 }; 00366 } //namespace NETGeographicLib