GeographicLib.NET 2.3.1-preview.1

This is a prerelease version of GeographicLib.NET.
There is a newer version of this package available.
See the version list below for details.
The owner has unlisted this package. This could mean that the package is deprecated, has security vulnerabilities or shouldn't be used anymore.
dotnet add package GeographicLib.NET --version 2.3.1-preview.1
NuGet\Install-Package GeographicLib.NET -Version 2.3.1-preview.1
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="GeographicLib.NET" Version="2.3.1-preview.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add GeographicLib.NET --version 2.3.1-preview.1
#r "nuget: GeographicLib.NET, 2.3.1-preview.1"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install GeographicLib.NET as a Cake Addin
#addin nuget:?package=GeographicLib.NET&version=2.3.1-preview.1&prerelease

// Install GeographicLib.NET as a Cake Tool
#tool nuget:?package=GeographicLib.NET&version=2.3.1-preview.1&prerelease

GeographicLib.NET

release prerelease

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)
  • Geodesic intersections (Intersect)
  • Rhumb (Rhumb and RhumbLine)
  • PolygonArea (PolygonArea<T>, PolygonArea, PolygonAreaExact and PolygonAreaRhumb)
  • Geoid (Geoid)
  • GravityModel (GravityCircle, NormalGravity and GravityModel)
  • MagneticModel (MagneticModel, MagneticCircle)
  • Auxiliary classes (MathEx, Ellipoid, EllipticFunction, SphericalHarmonic, AuxAngle, AuxLatitude and DAuxLatitude)

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 Release

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

dotnet add package GeographicLib.NET

Preview 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

Usage

This section lists some common usage examples of GeographicLib.NET. For detailed documentation, please refer GeographicLib's documentation.

Inverse calculation

Distance from JFK to LHR.

double
  lat1 = 40.6, lon1 = -73.8, // JFK Airport
  lat2 = 51.6, lon2 = -0.5;  // LHR Airport

double arcLength = Geodesic.WGS84.Inverse(lat1, lon1, lat2, lon2, out double distance);

Direct calculation

The point 5500 km NE of JFK:

double
  lat1 = 40.6, lon1 = -73.8,
  s12 = 5500e3, azi1 = 51;

double arcLength = Geodesic.WGS84.Direct(lat1, lon1, azi1, s12, out double lat2, out double lon2);

Geodesic intersection

Find closest intersection of two geodesics:

Geodesic geod = Geodesic.WGS84;
Intersect inter = new Intersect(geod);
IGeodesicLine
    lineX = geod.Line(0, 0, 45),
    lineY = geod.Line(45, 10, 135);

// Find displacement to closest intersection.
// Where point.X is the displacement from the starting point of lineX,
// and point.Y is the displacement from the starting point of lineY.
Point point = inter.Closest(lineX, lineY);

// Get the position of the intersection point by using the displacement on lineX.
lineX.Position(point.X, out double latx, out double lonx);

// Get the position of the intersection point by using the displacement on lineY.
lineY.Position(point.Y, out double laty, out double lony);

// (latx, lonx) and (laty, lony) should be pointing to the same location.
// Assert.AreEqual(latx, laty, 1e-12);
// Assert.AreEqual(lonx, lony, 1e-12);

Mathematical Functions

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

  • remquo
  • frexp
  • sincos (available since .NET 7.0, but not used due to this issue)
  • hypot (available since .NET 7.0, but not used due to this issue)
  • log1p (a naive implementation is available since .NET 7.0, not used by GeographicLib.NET)
  • expm1 (a naive implementation is available since .NET 7.0, not used by GeographicLib.NET)
  • exp2 (a naive implementation is available since .NET 7.0, not used by GeographicLib.NET)
  • 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.12, Windows 11 (10.0.22621.3155/22H2/2022Update/SunValley2)
Intel Xeon CPU E5-2689 0 2.60GHz, 1 CPU, 16 logical and 8 physical cores
.NET SDK 8.0.200
  [Host]        : .NET 6.0.27 (6.0.2724.6912), X64 RyuJIT AVX
  .NET 5.0      : .NET 5.0.17 (5.0.1722.21314), X64 RyuJIT AVX
  .NET 6.0      : .NET 6.0.27 (6.0.2724.6912), X64 RyuJIT AVX
  .NET 7.0      : .NET 7.0.16 (7.0.1624.6629), X64 RyuJIT AVX
  .NET 8.0      : .NET 8.0.2 (8.0.224.6711), X64 RyuJIT AVX
  .NET Core 2.1 : .NET Core 2.1.30 (CoreCLR 4.6.30411.01, CoreFX 4.6.30411.02), X64 RyuJIT AVX
  .NET Core 3.1 : .NET Core 3.1.32 (CoreCLR 4.700.22.55902, CoreFX 4.700.22.56512), X64 RyuJIT AVX
Method Job Runtime UseManagedCMath Mean Error StdDev Ratio RatioSD
Direct .NET 5.0 .NET 5.0 False 972.6 ns 9.31 ns 8.71 ns 1.00 0.03
Direct .NET 6.0 .NET 6.0 False 971.7 ns 19.16 ns 22.80 ns 1.00 0.00
Direct .NET 7.0 .NET 7.0 False 925.1 ns 11.09 ns 10.37 ns 0.95 0.02
Direct .NET 8.0 .NET 8.0 False 960.2 ns 14.22 ns 11.87 ns 0.98 0.02
Direct .NET Core 2.1 .NET Core 2.1 False 1,258.0 ns 19.32 ns 18.07 ns 1.29 0.03
Direct .NET Core 3.1 .NET Core 3.1 False 1,203.9 ns 16.11 ns 14.28 ns 1.23 0.03
Direct .NET 5.0 .NET 5.0 True 971.2 ns 19.21 ns 21.36 ns 1.03 0.03
Direct .NET 6.0 .NET 6.0 True 944.9 ns 14.32 ns 12.69 ns 1.00 0.00
Direct .NET 7.0 .NET 7.0 True 922.4 ns 17.88 ns 21.96 ns 0.98 0.02
Direct .NET 8.0 .NET 8.0 True 908.2 ns 5.44 ns 4.54 ns 0.96 0.01
Direct .NET Core 2.1 .NET Core 2.1 True 1,284.7 ns 14.19 ns 13.28 ns 1.36 0.02
Direct .NET Core 3.1 .NET Core 3.1 True 1,189.4 ns 12.68 ns 10.58 ns 1.26 0.02

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.

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.3.1 (unreleased)

  • NEW
    • Allow constructing MagneticModel and GravityModel from Stream and byte array. (#30)
    • AuxLatitude now implements IEllipsoid interface.
    • Parameter p0 of Intersect.Closest() now defaults to Point.Zero.
  • FIX
    • Fixed wrong GravityFlags handling in GravityCircle class.

Version 2.3.0 (released 2024/02/23)

  • NEW
    • Target .NET 7.0 and .NET 8.0.
    • Add managed implementation and libc wrapper for exp2.
    • Managed implementations and libc wrappers for log1p, expm1 and exp2 are now used for all versions of .NET, because the implementations provided by .NET runtime are just wrappers over Math.Log and Math.Pow.
  • FIX

Version 2.1.2 (released 2023/01/17)

  • FIX
    • Fixed an issue where number and date time parsing may fail or produce unexpected result when working with number and date time formats provided by CultureInfo.CurrentCulture. This fixes issue #27.

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.

Product Compatible and additional computed target framework versions.
.NET net5.0 is compatible.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • .NETStandard 2.0

  • .NETStandard 2.1

    • No dependencies.
  • net5.0

    • No dependencies.
  • net6.0

    • No dependencies.
  • net7.0

    • No dependencies.
  • net8.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on GeographicLib.NET:

Repository Stars
drewnoakes/metadata-extractor-dotnet
Extracts Exif, IPTC, XMP, ICC and other metadata from image, video and audio files
Version Downloads Last updated
2.3.1 4,309 3/20/2024
2.3.0 3,323 2/23/2024
2.1.2 49,413 1/17/2023
2.0.0 6,209 8/24/2022
1.52.1 6,961 4/12/2022
1.52.0 22,414 7/7/2021
1.51.0 5,022 3/14/2021