00001 /** 00002 * \file NETGeographicLib/CircularEngine.h 00003 * \brief Header for NETGeographicLib::CircularEngine class 00004 * 00005 * NETGeographicLib is copyright (c) Scott Heiman (2013) 00006 * GeographicLib is Copyright (c) Charles Karney (2010-2012) 00007 * <charles@karney.com> and licensed under the MIT/X11 License. 00008 * For more information, see 00009 * http://geographiclib.sourceforge.net/ 00010 **********************************************************************/ 00011 #pragma once 00012 00013 namespace NETGeographicLib 00014 { 00015 /** 00016 * \brief .NET wrapper for GeographicLib::CircularEngine. 00017 * 00018 * This class allows .NET applications to access GeographicLib::CircularEngine. 00019 * 00020 * The class is a companion to SphericalEngine. If the results of a 00021 * spherical harmonic sum are needed for several points on a circle of 00022 * constant latitude \e lat and height \e h, then SphericalEngine::Circle can 00023 * compute the inner sum, which is independent of longitude \e lon, and 00024 * produce a CircularEngine object. CircularEngine::LongitudeSum() can 00025 * then be used to perform the outer sum for particular values of \e lon. 00026 * This can lead to substantial improvements in computational speed for high 00027 * degree sum (approximately by a factor of \e N / 2 where \e N is the 00028 * maximum degree). 00029 * 00030 * CircularEngine is tightly linked to the internals of SphericalEngine. For 00031 * that reason, the constructor for this class is for internal use only. Use 00032 * SphericalHarmonic::Circle, SphericalHarmonic1::Circle, and 00033 * SphericalHarmonic2::Circle to create instances of this class. 00034 * 00035 * CircularEngine stores the coefficients needed to allow the summation over 00036 * order to be performed in 2 or 6 vectors of length \e M + 1 (depending on 00037 * whether gradients are to be calculated). For this reason the constructor 00038 * may throw a GeographicErr exception. 00039 * 00040 * C# Example: 00041 * \include example-CircularEngine.cs 00042 * Managed C++ Example: 00043 * \include example-CircularEngine.cpp 00044 * Visual Basic Example: 00045 * \include example-CircularEngine.vb 00046 * 00047 * <B>INTERFACE DIFFERENCES:</B><BR> 00048 * The () operator has been replaced with with LongitudeSum. 00049 * 00050 * This class does not have a constructor that can be used in a .NET 00051 * application. Use SphericalHarmonic::Circle, SphericalHarmonic1::Circle or 00052 * SphericalHarmonic2::Circle to create instances of this class. 00053 **********************************************************************/ 00054 public ref class CircularEngine 00055 { 00056 private: 00057 // pointer to the unmanaged GeographicLib::CircularEngine 00058 const GeographicLib::CircularEngine* m_pCircularEngine; 00059 00060 // The finalizer frees the unmanaged memory when the object is destroyed. 00061 !CircularEngine(); 00062 public: 00063 /** 00064 * The constructor. 00065 * 00066 * This constructor should not be used in .NET applications. 00067 * Use SphericalHarmonic::Circle, SphericalHarmonic1::Circle or 00068 * SphericalHarmonic2::Circle to create instances of this class. 00069 * 00070 * @param[in] c The unmanaged CircularEngine to be copied. 00071 **********************************************************************/ 00072 CircularEngine( const GeographicLib::CircularEngine& c ); 00073 00074 /** 00075 * The destructor calls the finalizer 00076 **********************************************************************/ 00077 ~CircularEngine() 00078 { this->!CircularEngine(); } 00079 00080 /** 00081 * Evaluate the sum for a particular longitude given in terms of its 00082 * cosine and sine. 00083 * 00084 * @param[in] coslon the cosine of the longitude. 00085 * @param[in] sinlon the sine of the longitude. 00086 * @return \e V the value of the sum. 00087 * 00088 * The arguments must satisfy <i>coslon</i><sup>2</sup> + 00089 * <i>sinlon</i><sup>2</sup> = 1. 00090 **********************************************************************/ 00091 double LongitudeSum(double coslon, double sinlon); 00092 00093 /** 00094 * Evaluate the sum for a particular longitude. 00095 * 00096 * @param[in] lon the longitude (degrees). 00097 * @return \e V the value of the sum. 00098 **********************************************************************/ 00099 double LongitudeSum(double lon); 00100 00101 /** 00102 * Evaluate the sum and its gradient for a particular longitude given in 00103 * terms of its cosine and sine. 00104 * 00105 * @param[in] coslon the cosine of the longitude. 00106 * @param[in] sinlon the sine of the longitude. 00107 * @param[out] gradx \e x component of the gradient. 00108 * @param[out] grady \e y component of the gradient. 00109 * @param[out] gradz \e z component of the gradient. 00110 * @return \e V the value of the sum. 00111 * 00112 * The gradients will only be computed if the CircularEngine object was 00113 * created with this capability (e.g., via \e gradp = true in 00114 * SphericalHarmonic::Circle). If not, \e gradx, etc., will not be 00115 * touched. The arguments must satisfy <i>coslon</i><sup>2</sup> + 00116 * <i>sinlon</i><sup>2</sup> = 1. 00117 **********************************************************************/ 00118 double LongitudeSum(double coslon, double sinlon, 00119 [System::Runtime::InteropServices::Out] double% gradx, 00120 [System::Runtime::InteropServices::Out] double% grady, 00121 [System::Runtime::InteropServices::Out] double% gradz); 00122 00123 /** 00124 * Evaluate the sum and its gradient for a particular longitude. 00125 * 00126 * @param[in] lon the longitude (degrees). 00127 * @param[out] gradx \e x component of the gradient. 00128 * @param[out] grady \e y component of the gradient. 00129 * @param[out] gradz \e z component of the gradient. 00130 * @return \e V the value of the sum. 00131 * 00132 * The gradients will only be computed if the CircularEngine object was 00133 * created with this capability (e.g., via \e gradp = true in 00134 * SphericalHarmonic::Circle). If not, \e gradx, etc., will not be 00135 * touched. 00136 **********************************************************************/ 00137 double LongitudeSum(double lon, 00138 [System::Runtime::InteropServices::Out] double% gradx, 00139 [System::Runtime::InteropServices::Out] double% grady, 00140 [System::Runtime::InteropServices::Out] double% gradz); 00141 }; 00142 } //namespace NETGeographicLib