// -*- text -*-
/**
 * \file NETGeographicLib.dox
 * \brief Documentation for NETGeographicLib
 *
 * Written by Scott Heiman <mrmtdew2@outlook.com> and licensed under the
 * MIT/X11 License.  For more information, see
 * http://geographiclib.sourceforge.net/
 **********************************************************************/

/**
\mainpage NETGeographicLib library
\author Scott Heiman (mrmtdew2@outlook.com)
\version 1.37
\date 2014-08-08

\section abstract Abstract

%NETGeographicLib is a .NET wrapper for GeographicLib.  It allows
.NET developers to access GeographicLib classes within C#, Visual
Basic, Managed C++, and other Microsoft .NET languages.

NETGeographicLib is written in Managed C++.  It IS NOT a reimplementation
of the GeographicLib software.  It is a container that provides interfaces
to the GeographicLib classes.  GeographicLib and NETGeographicLib is an
integrated product.

The NETGeographic project in the GeographicLib-vc10.sln file located in
\<install folder\>/GeographicLib-1.37/windows will create the NETGeographicLib
DLL.  The source code for NETGeographicLib is located in
\<install folder\>/GeographicLib-1.37/dotnet/NETGeographicLib.  NETGeographicLib
is not available for older versions of Microsoft Visual Studio.

NETGeographicLib has been tested with C#, Managed C++, and Visual Basic.
Sample code snippets can be found in
\<install folder\>/GeographicLib-1.37/dotnet/examples.

\section differences Differences between NETGeographicLib and GeographicLib

The NETGeographicLib class names are identical to the GeographicLib class names.
All NETGeographicLib classes are in the NETGeographicLib namespace.

NETGeographicLib exposes most of the GeographicLib classes.  The exceptions
are SphericalEngine, GeographicLib::Math, and GeographicLib::Utility.  The
SphericalEngine class is a template class which (according to the comments in
the SphericalEngine.h file) is not usually accessible to developers.  The
GeographicLib::Math class contains several specialized functions required by
GeographicLib classes.  They have limited use outside GeographicLib.  This class
may be exposed in a future release if there is demand for it.  The functions
provided by GeographicLib::Utility duplicate functions provided by existing .NET
controls (DateTime).

The SphericalCoefficients class replaces the SphericalEngine::coeff class.

The NETGeographicLib class function interfaces are similar, and in many cases,
identical to the GeographicLib interfaces.  There are differences because of
limitations in .NET and other differences that are discretionary.  The comments
in the header files contain a section labeled "INTERFACE DIFFERENCES" that detail
the differences between the NETGeographicLib interfaces and the GeographicLib
interfaces.  The differences are summarized in the text that follows.

Default values for function parameters are not supported in .NET.

Several GeographicLib class functions accept or return a "capabilities mask" as
an unsigned integer.  The NETGeographicLib classes accept and return the capabilities
mask as an enumeration.

The Geocentric and LocalCartesian classes have functions that return a rotation matrix.
The NETGeographicLib versions return a two-dimensional, 3 &times; 3 array rather than a vector.

A lot of GeographicLib classes have inspector functions (MajorRadius,
Flattening, etc.).  These inspector functions are implemented as
properties in NETGeographicLib.

NETGeographicLib classes do not implement constructors that create "uninitialized" objects.

Many NETGeographicLib classes implement a default constructor that assumes WGS84 parameters.

Several GeographicLib classes implement the () operator.  NETGeographicLib classes
replace the () operator with a specific function.  Managed C++ allows developers to
overload the () operator; however, the () operator is not 'elegantly' supported in
other .NET languages.  For example, if the () operator was implemented in the
NETGeographicLib::Geoid class, then C# code would look like
\code
Geoid geoid = new Geoid();
double h = geoid.op_FuncCall(latitude,longitude);  // if () operator was implemented.
h = geoid.Height(latitude,longitude); // with () operator replaced with Height
\endcode
The author felt that the op_FuncCall syntax did not appropriately define the purpose
of the function call.

.NET does not allow developers to overload the assignment operators (=,+=,-=,*=).
These operators have been replaced with functions in the NETGeographicLib::Accumulator class.

\section library Using NETGeographicLib in a .NET Application

If you have access to the NETGeographicLib and GeographicLib projects then
-# Create a new solution.
-# Create a new project using any .NET language.  For this example, call it MyApp.
-# Add the NETGeographic and Geographic projects to the solution.  Verify that NETGeographicLib depends upon GeographicLib.
-# Right-Click MyApp in the Solution View and select "Add Reference..." (C#/VB) or "References..." (Managed C++) in the pop-up menu.
-# (Managed C++) Click the "Add New Reference..." button in the Properties dialog.
\image html NETGeographicLib3.png
-# Click the Projects Tab and select NETGeographic.
   \image html NETGeographicLib1.png
-# Click OK.

If you only have access to the NETGeographic.dll then
-# Create a new solution.
-# Create a new project using any .NET language.  For this example, call it MyApp.
-# Right-Click MyApp in the Solution View and select "Add Reference..." in the popup menu.
-# Right-Click MyApp in the Solution View and select "Add Reference..." (C#/VB) or "References..." (Managed C++) in the pop-up menu.
-# (Managed C++) Click the "Add New Reference..." button in the Properties dialog.
\image html NETGeographicLib3.png
-# Click the Browse Tab and navigate to the folder containing NETGeographic.dll.
\image html NETGeographicLib2.png
-# Select NETGeographic.dll and click OK.

The MyApp project will have access to all public NETGeographicLib classes after the
NETGeographic reference is added to MyApp.

C# developers should add
\code using NETGeographicLib; \endcode
to any C# source file that uses NETGeographicLib.

Managed C++ developers should add
\code using namespace NETGeographicLib; \endcode
to any C++ source that uses NETGeographicLib classes.

Visual Basic developers should add
\code Imports NETGeographicLib \endcode
to any Visual Basic source that uses NETGeographicLib classes.

\section sample C# Sample Application

A C# sample application is provided that demonstrates NETGeographicLib classes.
The source code for the sample application is located in
\<install folder\>/GeographicLib-1.37/dotnet/Projections.  The sample
application creates a tabbed dialog.  Each tab provides data entry fields that
allow the user to exercise one or more NETGeographicLib classes.

The following table lists the source code that demonstrates specific classes.
<center>
<TABLE>
<TR><TH>Source File</TH><TH>Classes</TH></TR>
<TR><TD>AccumPanel.cs</TD><TD>Accumulator</TD></TR>
<TR><TD>AlbersPanel.cs</TD><TD>AlbersEqualArea, LambertConformalConic, TransverseMercator, TransverseMercatorExact</TD></TR>
<TR><TD>EllipsoidPanel.cs</TD><TD>Ellipsoid</TD></TR>
<TR><TD>EllipticPanel.cs</TD><TD>EllipticFunction</TD></TR>
<TR><TD>GeocentricPanel.cs</TD><TD>Geocentric</TD></TR>
<TR><TD>GeodesicPanel.cs</TD><TD>Geodesic, GeodesicLine, GeodesicExact, GeodesicLineExact</TD></TR>
<TR><TD>GeoidPanel.cs</TD><TD>Geoid</TD></TR>
<TR><TD>GravityPanel.cs</TD><TD>NormalGravity, GravityModel, GravityCircle</TD></TR>
<TR><TD>LocalCartesianPanel.cs</TD><TD>LocalCartesian</TD></TR>
<TR><TD>MagneticPanel.cs</TD><TD>MagneticModel, MagneticCircle</TD></TR>
<TR><TD>MiscPanel.cs</TD><TD>DMS, Geohash</TD></TR>
<TR><TD>PolarStereoPanel.cs</TD><TD>PolarStereographic</TD></TR>
<TR><TD>PolyPanel.cs</TD><TD>PolygonArea</TD></TR>
<TR><TD>ProjectionsPanel.cs</TD><TD>AzimuthalEquidistant, CassiniSoldner, Gnomonic</TD></TR>
<TR><TD>SphericalHarmonicsPanel.cs</TD><TD>SphericalHarmonic, SphericalHarmonic1, SphericalHarmonic2, CircularEngine, SphericalCoefficients</TD></TR>
<TR><TD>TypeIIIProjPanel.cs</TD><TD>UTMUPS, MGRS, OSGB</TD></TR>
<TR><TD>RhumbPanel.cs</TD><TD>Rhumb, RhumbLine</TD></TR>
</TABLE>
</center>

\section netcmake Using cmake to build a Managed C++ Application

The following assumes that you have installed %GeographicLib in one of
two ways:
- you have built and installed %GeographicLib using cmake with
  <code>-D BUILD_NETGEOGRAPHICLIB=ON</code> (see
  \ref cmake "Installation with cmake" in the %GeographicLib
  documentation).  You can use any version of Visual Studio to build
  %GeographicLib and should use the same version to build your
  application.  You can build %GeographicLib as a shared library using
  <code>-D GEOGRAPHICLIB_LIB_TYPE=SHARED</code> or <code>BOTH</code>.
- you have installed %GeographicLib using one of the binary installers (see
  \ref windowsbin "Using a binary installer for Windows" in the
  %GeographicLib documentation).  In this case, you are restricted to using
  Visual Studio 10.

The minimum recommended version of cmake for use with NETGeographicLib
is 2.8.7.  In order to build an application that uses NETGeographicLib
with cmake, ask for the NETGeographicLib "component" of %GeographicLib
using \verbatim
find_package(GeographicLib COMPONENTS NETGeographicLib) \endverbatim
If NETGeographicLib is found, then
<code>GeographicLib_NETGeographicLib_FOUND</code> will be set to true and
<code>GeographicLib_NETGeographicLib_LIBRARIES</code> will be set to the
NETGeographic shared library.  This is the name of the cmake target from
which the pathname of the dll can be obtained.

Here is a very simple test code, which uses the
NETGeographicLib::Geodesic class:
\include example-Geodesic-small.cpp
This example is
<code>dotnet/examples/ManagedCPP/example-Geodesic-small.cpp</code>.

Here is a complete CMakeList.txt files you can use to build this test
code using the installed library: \verbatim
project (geodesictest)
cmake_minimum_required (VERSION 2.8.7) # required for VS_DOTNET_REFERENCES

find_package (GeographicLib 1.35 REQUIRED COMPONENTS NETGeographicLib)

add_executable (${PROJECT_NAME} example-Geodesic-small.cpp)
set_target_properties (${PROJECT_NAME} PROPERTIES COMPILE_FLAGS "/clr")
string (REPLACE "/RTC1" "" CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG}")
string (REPLACE "/EHsc" "" CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS}")

# This is set up for Release builds only.  Change RELEASE to DEBUG for
# Debug builds.
get_target_property (_LOC "${GeographicLib_NETGeographicLib_LIBRARIES}"
  IMPORTED_LOCATION_RELEASE)
set_target_properties (${PROJECT_NAME} PROPERTIES VS_DOTNET_REFERENCES ${_LOC})

get_target_property (_LIB "${GeographicLib_NETGeographicLib_LIBRARIES}"
  IMPORTED_LINK_INTERFACE_LIBRARIES_RELEASE)
get_target_property (_LIBTYPE ${_LIB} TYPE)
if (_LIBTYPE STREQUAL "SHARED_LIBRARY")
  # On Windows systems, copy the shared library to build directory
  add_custom_command (TARGET ${PROJECT_NAME} POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E
    copy $<TARGET_FILE:${_LIB}> ${CMAKE_CFG_INTDIR}
    COMMENT "Copying shared library for GeographicLib")
endif () \endverbatim
The typical invocation of cmake is \verbatim
mkdir BUILD
cd BUILD
cmake -G "Visual Studio 10" -D CMAKE_PREFIX_PATH=C:/pkg-vc10 ..
cmake --build . --config Release \endverbatim
The version of Visual Studio should match that used to build
NETGeographicLib.  <b>NOTE:</b> With Visual Studio 10, this results in
warnings such as \verbatim
warning C4945: 'ExtensionAttribute' : cannot import symbol from ... \endverbatim
which can be safely(?) ignored.

Running the example with \verbatim
Release\geodesictest.exe  \endverbatim
should give \verbatim
  5551.75940031868 km \endverbatim
**********************************************************************/