1 #pragma once
2 /**
3  * \file NETGeographicLib/MagneticCircle.h
4  * \brief Header for NETGeographicLib::MagneticCircle 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   /**
16    * \brief .NET wrapper for GeographicLib::MagneticCircle.
17    *
18    * This class allows .NET applications to access GeographicLib::MagneticCircle.
19    *
20    * Evaluate the earth's magnetic field on a circle of constant height and
21    * latitude.  This uses a CircularEngine to pre-evaluate the inner sum of the
22    * spherical harmonic sum, allowing the values of the field at several
23    * different longitudes to be evaluated rapidly.
24    *
25    * Use MagneticModel::Circle to create a MagneticCircle object.  (The
26    * constructor for this class is for internal use only.)
27    *
28    * C# Example:
29    * \include example-MagneticCircle.cs
30    * Managed C++ Example:
31    * \include example-MagneticCircle.cpp
32    * Visual Basic Example:
33    * \include example-MagneticCircle.vb
34    *
35    * <B>INTERFACE DIFFERENCES:</B><BR>
36    * The () operator has been replaced with Field.
37    *
38    * The following functions are implemented as properties:
39    * Init, EquatorialRadius, Flattening, Latitude, Height, and Time.
40    **********************************************************************/
41     public ref class MagneticCircle
42     {
43         private:
44         // pointer to the unmanaged GeographicLib::MagneticCircle.
45         const GeographicLib::MagneticCircle* m_pMagneticCircle;
46 
47         // the finalizer frees the unmanaged memory when the object is destroyed.
48         !MagneticCircle(void);
49     public:
50 
51         /**
52          * %brief A constructor that is initialized from an unmanaged
53          * GeographicLib::MagneticCircle. This is for internal use only.
54          *
55          * Developers should use MagneticModel::Circle to create a
56          * MagneticCircle.
57          **********************************************************************/
58         MagneticCircle( const GeographicLib::MagneticCircle& c );
59 
60         /**
61          * %brief The destructor calls the finalizer.
62          **********************************************************************/
~MagneticCircle()63         ~MagneticCircle()
64         { this->!MagneticCircle(); }
65 
66         /** \name Compute the magnetic field
67          **********************************************************************/
68         ///@{
69         /**
70          * %brief Evaluate the components of the geomagnetic field at a
71          * particular longitude.
72          *
73          * @param[in] lon longitude of the point (degrees).
74          * @param[out] Bx the easterly component of the magnetic field (nanotesla).
75          * @param[out] By the northerly component of the magnetic field (nanotesla).
76          * @param[out] Bz the vertical (up) component of the magnetic field
77          *   (nanotesla).
78          **********************************************************************/
79         void Field(double lon,
80             [System::Runtime::InteropServices::Out] double% Bx,
81             [System::Runtime::InteropServices::Out] double% By,
82             [System::Runtime::InteropServices::Out] double% Bz);
83 
84         /**
85          * Evaluate the components of the geomagnetic field and their time
86          * derivatives at a particular longitude.
87          *
88          * @param[in] lon longitude of the point (degrees).
89          * @param[out] Bx the easterly component of the magnetic field (nanotesla).
90          * @param[out] By the northerly component of the magnetic field (nanotesla).
91          * @param[out] Bz the vertical (up) component of the magnetic field
92          *   (nanotesla).
93          * @param[out] Bxt the rate of change of \e Bx (nT/yr).
94          * @param[out] Byt the rate of change of \e By (nT/yr).
95          * @param[out] Bzt the rate of change of \e Bz (nT/yr).
96          **********************************************************************/
97         void Field(double lon,
98             [System::Runtime::InteropServices::Out] double% Bx,
99             [System::Runtime::InteropServices::Out] double% By,
100             [System::Runtime::InteropServices::Out] double% Bz,
101             [System::Runtime::InteropServices::Out] double% Bxt,
102             [System::Runtime::InteropServices::Out] double% Byt,
103             [System::Runtime::InteropServices::Out] double% Bzt);
104         ///@}
105 
106         /** \name Inspector functions
107          **********************************************************************/
108         ///@{
109         /**
110          * @return true if the object has been initialized.
111          **********************************************************************/
112         property bool Init { bool get(); }
113         /**
114          * @return \e a the equatorial radius of the ellipsoid (meters).  This is
115          *   the value inherited from the MagneticModel object used in the
116          *   constructor.  This property throws a GeographicErr exception if
117          *   the object is not initialized.
118          **********************************************************************/
119         property double EquatorialRadius { double get(); }
120         /**
121          * @return \e f the flattening of the ellipsoid.  This is the value
122          *   inherited from the MagneticModel object used in the constructor.
123          *   This property throws a GeographicErr exception if the object is
124          *   not initialized.
125          **********************************************************************/
126         property double Flattening { double get(); }
127         /**
128          * @return the latitude of the circle (degrees).
129          *   This property throws a GeographicErr exception if the object is
130          *   not initialized.
131          **********************************************************************/
132         property double Latitude { double get(); }
133         /**
134          * @return the height of the circle (meters).
135          *   This property throws a GeographicErr exception if the object is
136          *   not initialized.
137          **********************************************************************/
138         property double Height { double get(); }
139         /**
140          * @return the time (fractional years).
141          *   This property throws a GeographicErr exception if the object is
142          *   not initialized.
143          **********************************************************************/
144         property double Time { double get(); }
145         ///@}
146     };
147 } //namespace NETGeographicLib
148