// -*- text -*- /** * \file NETGeographicLib.dox * \brief Documentation for NETGeographicLib * * Written by Scott Heiman and licensed under the * MIT/X11 License. For more information, see * https://geographiclib.sourceforge.io/ **********************************************************************/ /** \mainpage NETGeographicLib library \author Scott Heiman (mrmtdew2@outlook.com) \version 1.50.1 \date 2019-12-13 The documentation for other versions is available at https://geographiclib.sourceforge.io/m.nn/NET for versions numbers m.nn ≥ 1.33. \section abstract-net 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 solutions and C++ projects are located in the \/GeographicLib-1.50.1/windows folder where \ is the directory where you unpacked the GeographicLib source distribution. The C# Projections projects are located in the \/GeographicLib-1.50.1/dotnet/Projections folder. Solution files have been provided for VS 2010 and VS 2013 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 \/GeographicLib-1.50.1/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 most of 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 GeographicLib::Utility::fractionalyear function is available to .NET programmers by calling NETGeographicLib::Utility::FractionalYear. 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. If the documentation refers to a default value for a parameter, it applies only to GeographicLib. However, such a "default" value often provides a reasonable choice for this parameter. 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 × 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 \/GeographicLib-1.50.1/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.
Source FileClasses
AccumPanel.csAccumulator
AlbersPanel.csAlbersEqualArea, LambertConformalConic, TransverseMercator, TransverseMercatorExact
EllipsoidPanel.csEllipsoid
EllipticPanel.csEllipticFunction
GeocentricPanel.csGeocentric
GeodesicPanel.csGeodesic, GeodesicLine, GeodesicExact, GeodesicLineExact
GeoidPanel.csGeoid
GravityPanel.csNormalGravity, GravityModel, GravityCircle
LocalCartesianPanel.csLocalCartesian
MagneticPanel.csMagneticModel, MagneticCircle
MiscPanel.csDMS, Geohash, GARS, Georef
PolarStereoPanel.csPolarStereographic
PolyPanel.csPolygonArea
ProjectionsPanel.csAzimuthalEquidistant, CassiniSoldner, Gnomonic
SphericalHarmonicsPanel.csSphericalHarmonic, SphericalHarmonic1, SphericalHarmonic2, CircularEngine, SphericalCoefficients
TypeIIIProjPanel.csUTMUPS, MGRS, OSGB
RhumbPanel.csRhumb, RhumbLine
\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 -D BUILD_NETGEOGRAPHICLIB=ON (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 -D GEOGRAPHICLIB_LIB_TYPE=SHARED or BOTH. - you have installed %GeographicLib using one of the binary installers (see \ref binaryinstwin "Using a binary installer for Windows" in the %GeographicLib documentation). In this case, you are restricted to using Visual Studio 10. The minimum version of cmake for use with NETGeographicLib is 3.1.0 or later. 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 GeographicLib_NETGeographicLib_FOUND will be set to true and GeographicLib_NETGeographicLib_LIBRARIES 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 dotnet/examples/ManagedCPP/example-Geodesic-small.cpp. 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 $ ${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. NOTE: 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 **********************************************************************/