NETGeographicLib  1.48
Author
Scott Heiman (mrmtd.nosp@m.ew2@.nosp@m.outlo.nosp@m.ok.c.nosp@m.om)
Version
1.47
Date
2017-02-15

The documentation for other versions is available at https://geographiclib.sourceforge.io/m.nn/NET for versions numbers m.nn ≥ 1.33.

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 <install>/windows folder. The C# Projections projects are located in the <install>/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 <install folder>/GeographicLib-1.46/dotnet/examples.

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

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

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.

Using NETGeographicLib in a .NET Application

If you have access to the NETGeographicLib and GeographicLib projects then

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

If you only have access to the NETGeographic.dll then

  1. Create a new solution.
  2. Create a new project using any .NET language. For this example, call it MyApp.
  3. Right-Click MyApp in the Solution View and select "Add Reference..." in the popup menu.
  4. Right-Click MyApp in the Solution View and select "Add Reference..." (C#/VB) or "References..." (Managed C++) in the pop-up menu.
  5. (Managed C++) Click the "Add New Reference..." button in the Properties dialog.
    NETGeographicLib3.png
  6. Click the Browse Tab and navigate to the folder containing NETGeographic.dll.
    NETGeographicLib2.png
  7. 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

to any C# source file that uses NETGeographicLib.

Managed C++ developers should add

using namespace NETGeographicLib;

to any C++ source that uses NETGeographicLib classes.

Visual Basic developers should add

to any Visual Basic source that uses NETGeographicLib classes.

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.46/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

Using cmake to build a Managed C++ Application

The following assumes that you have installed GeographicLib in one of two ways:

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

find_package(GeographicLib COMPONENTS NETGeographicLib) 

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:

using namespace System;
using namespace NETGeographicLib;
int main() {
Geodesic^ geod = gcnew Geodesic();
// Distance from JFK to LHR
double
lat1 = 40.6, lon1 = -73.8, // JFK Airport
lat2 = 51.6, lon2 = -0.5; // LHR Airport
double s12;
geod->Inverse(lat1, lon1, lat2, lon2, s12);
Console::WriteLine( s12 / 1000 + " km" );
return 0;
}

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:

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 () 

The typical invocation of cmake is

mkdir BUILD
cd BUILD
cmake -G "Visual Studio 10" -D CMAKE_PREFIX_PATH=C:/pkg-vc10 ..
cmake --build . --config Release 

The version of Visual Studio should match that used to build NETGeographicLib. NOTE: With Visual Studio 10, this results in warnings such as

warning C4945: 'ExtensionAttribute' : cannot import symbol from ... 

which can be safely(?) ignored.

Running the example with

Release\geodesictest.exe  

should give

  5551.75940031868 km