GeographicLib.NET 2.0.0

GeographicLib.NET

GeographicLib is a small set of C++ classes for performing conversions between geographic, UTM, UPS, MGRS, geocentric, and local cartesian coordinates,for gravity (e.g., EGM2008), geoid height and geomagnetic field (e.g., WMM2020) calculations, and for solving geodesic problems.

GeographicLib.NET is a native .NET implementation of GeographicLib written in pure C#.

What's different from NETGeographicLib

Unlike NETGeographicLib, GeographicLib.NET is implemented in pure C# without binding the C++ GeograpbicLib library by using C++/CLI or P/Invoke, thus achieves higher level of portability.

You should be able to use GeographicLib.NET with any target framework and platform that supports .NET Standard 2.0 or above.

Features

Bellow is a list of implemented features.

• Projections (AlbersEqualArea, AzimuthalEquidistant, CassiniSoldner, Gnomonic, LambertConformalConic, PolarStereographic and TransverseMercator)
• Geocodes (GARS, Geohash, Georef, MGRS and OSGB)
• Coordinate conversions (UTMUPS, Geocentric and LocalCartesian)
• Coordinate parsing/formatting (DMS and GeoCoords)
• Geodesic (Geodesic, GeodesicLine, GeodesicExact and GeodesicLineExact)
• Rhumb (Rhumb and RhumbLine)
• PolygonArea (PolygonArea<T>, PolygonArea, PolygonAreaExact and PolygonAreaRhumb)
• Geoid (Geoid)
• GravityModel (GravityCircle, NormalGravity and GravityModel)
• MagneticModel (MagneticModel, MagneticCircle)
• Auxilary classes (MathEx, Ellipoid, EllipticFunction and SphericalHarmonic)

Geodesic and GeodesicExact are tested with the test set for geodesic.

TransverseMercator and TransverseMercatorExact are tested with data generated by 64-bit TransverseMercatorProj utility ran on Windows.

Managed implemetation of C mathematical functions in MathEx are tested with data generated by 64-bit Windows Universal C Runtime.

Installing

Stable

Stable releases of GeographicLib.NET are hosted on NuGet. You can install them using the following command:

dotnet add package GeographicLib.NET

Preview

Preview versions of GeographicLib.NET are hosted on NuGet pre-release channel. You can install them using the following command:

dotnet add package GeographicLib.NET --prerelease

Mathematical Functions

GeographicLib uses several C mathematical functions that are not available in all versions of .NET. These functions are:

• remquo
• hypot
• log1p
• expm1
• frexp
• log2 (available since .NET 5.0)
• fma (available since .NET 5.0)
• scalbn (available since .NET 5.0)
• copysign (available since .NET 5.0)
• atanh (available since .NET Standard 2.1)
• asinh (available since .NET Standard 2.1)
• cbrt (available since .NET Standard 2.1)

GeographicLib.NET provides managed implementations of these functions (ported from musl libc).

GeographicLib.MathEx class will use implementations provided by .NET runtime whenever possible, and will fallback to managed implementations when not available in .NET runtime.

You can also force GeographicLib.MathEx to fallback to platform dependent implementations provided by system C runtime libraries, rather than managed implementations, by setting GeographicLib.MathEx.UseManagedCMath property to false. Native C math implemenation may provide slightly better performance, but also produce inconsistent results on different platforms in some edge cases.

In fact, the performance of different C math implementations are very close, managed implementation performs even better on newer runtimes. The following table shows the benchmark result of Geodesic.WGS84.GenDirect executed with/without manged C math:

BenchmarkDotNet=v0.13.1, OS=Windows 10.0.22000
Intel Xeon CPU E5-2689 0 2.60GHz, 1 CPU, 16 logical and 8 physical cores
.NET SDK=6.0.300-preview.22204.3
  [Host]        : .NET 6.0.4 (6.0.422.16404), X64 RyuJIT
  .NET 5.0      : .NET 5.0.16 (5.0.1622.16705), X64 RyuJIT
  .NET 6.0      : .NET 6.0.4 (6.0.422.16404), X64 RyuJIT
  .NET Core 2.1 : .NET Core 2.1.30 (CoreCLR 4.6.30411.01, CoreFX 4.6.30411.02), X64 RyuJIT
  .NET Core 3.1 : .NET Core 3.1.24 (CoreCLR 4.700.22.16002, CoreFX 4.700.22.17909), X64 RyuJIT

Thus it's recommended to stick with managed C math until it becomes a performance bottleneck of your application, as it's more consistent as compared to native C math on different platforms.

Documentation

GeographicLib.NET includes a detailed XML documentation for all public APIs. Since the API surface of GeographicLib.NET is highly compatible with GeographicLib, you can also refer the its documentation here for usage and detailed explanation.

Change Log

GeographicLib.NET adopts changes made in GeographicLib and aligns its version number with GeographicLib releases.

Bellow is a list of stable releases of GeographicLib.NET and changes made in .NET side in each release. For changes adopted from GeographicLib, please refer the its change log here.

Version 2.0.0 (released 2022/08/24)

• NEW
  • Add IPolygonArea interface to provide better support for unit testing and dependency injection.
  • Add Count and IsPolyline properties (corresponding to NumPoints and Polyline methods in GeographicLib) to PolygonArea.
  • Add a new method Utility.FractionalYear which can parse floating point number and date time string as fractional year.
  • Allow constructing Geoid from Stream and byte array.
• FIX
  • String accepting APIs now handle lowercase "nan" correctly.
  • Ensure consistent rounding mode (MidpointRounding.ToEven) across different runtimes when converting floating point number to string.
  • MGRS.Reverse now allows lowercase input.

Version 1.52.1 (released 2022/04/12)

• NEW

  • Target .NET 6.0 in addition to .NET 5.0, .NET Standard 2.1 and .NET Standard 2.0.
  • Source Link support.

• BREAKING

  • Fixed typos in Ellipsoid. (Renamed SecondFlatterning to SecondFlattening and ThirdFlatterning to ThirdFlattening)

• FIX

  • Fixed an issue that Freeze method in AlbersEqualArea, LambertConformalConic and PolarStereographic was not working correctly.
  • Fixed duplicate instantiation of WGS84 and GRS80 static properties defined in NormalGravity.
  • Add missing support for World Magnetic Model Format v2.

Version 1.52.0 (released 2021/07/07)

• BREAKING

  • Modify overloads of Forward and Reverse in AlbersEqualArea, AzimuthalEquidistant, CassiniSoldner and LambertConformalConic to return coordinates as tuples.
  • Modify methods using out parameters defined in NormalGravity, GravityModel, GravityCircle, MagneticModel and MagnegticCircle to return results as tuples.

• NEW

  • Add constructor overloads that accept IEllipsoid as parameter for AlbersEqualArea and LambertConformalConic.
  • Add managed implementation of log2.
  • Add overloads of Direct and Inverse in Geodesic/GeodesicLine, GeodesicExact/GeodesicLineExact and Rhumb/RhumbLineExact, that return the computation results as a single object.
  • Add definitions of popular reference ellipsoids in Ellipsoid class.

• FIX

  • Fix stack overflow bug for Forward(double lon0, double lat, double lon) and Reverse(double lon0, double x, double y) in TransverseMercatorExact.

Version 1.51.0 (released 2021/03/14)

Initial stable release.