Home

Geodesic and DMS routines from GeographicLib

This documentation applies to version 2.1.0.

The documentation for other versions is available at https://geographiclib.sourceforge.io/JavaScript.

Licensed under the MIT/X11 License; see LICENSE.txt.

These packages are a JavaScript implementations of the geodesic and DMS routines from GeographicLib. The two packages are

  • geographiclib-geodesic solves the direct and inverse geodesic problems for an ellipsoid of revolution.

  • geographiclib-dms converts angles in decimal degrees to degrees-minutes-seconds and vice versa.

Prior to version 2.0.0, these were combined in a single package geographiclib. Because the geodesic and DMS components of this package were independent and because most users will primarily be interested in the geodesic calculations, it made sense to separate them into two packages; removal of the DMS routines from geographiclib-geodesic reduced it size by about 20%. The geographiclib package was be deprecated on 2023-05-01.

Installation

The libraries can be used in node by first installing the packages with npm

$ npm install geographiclib-geodesic geographiclib-dms
$ node
> var geodesic = require("geographiclib-geodesic");
> var DMS = require("geographiclib-dms");

The npm packages include test suites. Run this by, e.g.,

$ cd node_modules/geographiclib-geodesic
$ npm test

Alternatively, you can use it in client-side JavaScript, by including in your HTML page

<script
  type="text/javascript"
  src="https://geographiclib.sourceforge.io/scripts/geographiclib-geodesic.min.js">
</script>
<script
  type="text/javascript"
  src="https://geographiclib.sourceforge.io/scripts/geographiclib-dms.min.js">
</script>

Both of these prescriptions bring geodesic and DMS into scope.

Examples

Now geodesic calculations can be carried out, for example,

var geod = geodesic.Geodesic.WGS84, r;

// Find the distance from Wellington, NZ (41.32S, 174.81E) to
// Salamanca, Spain (40.96N, 5.50W)...
r = geod.Inverse(-41.32, 174.81, 40.96, -5.50);
console.log("The distance is " + r.s12.toFixed(3) + " m.");
// This prints "The distance is 19959679.267 m."

// Find the point 20000 km SW of Perth, Australia (32.06S, 115.74E)...
r = geod.Direct(-32.06, 115.74, 225, 20000e3);
console.log("The position is (" +
            r.lat2.toFixed(8) + ", " + r.lon2.toFixed(8) + ").");
// This prints "The position is (32.11195529, -63.95925278)."

Two examples of this library in use are

More information

Other links

Change log

  • Version 2.1.0 (released 2024-08-18)

    • Fixed a problem with the inverse geodesic calculation when points are on opposite latitude ±45°.
    • Fixes for new version of minify.

  • Version 2.0.0 (released 2022-04-29)

    • The geographiclib package is now split into two packages geographiclib-geodesic and geographiclib-dms geographiclib-geodesic and geographiclib-dms.
    • The JavaScript package now has its own git repository.
    • Fix bug where the solution of the inverse geodesic problem with φ1 = 0 and φ2 = nan was treated as equatorial.
    • More careful treatment of ±0° and ±180°.
      • These behave consistently with taking the limits
        • ±0 means ±ε as ε → 0+
        • ±180 means ±(180 − ε) as ε → 0+
      • As a consequence, azimuths of +0° and +180° are reckoned to be east-going, as far as tracking the longitude with net.sf.geographiclib.GeodesicMask#LONG_UNROLL and the area goes, while azimuths −0° and −180° are reckoned to be west-going.
      • When computing longitude differences, if λ2 − λ1 = ±180° (mod 360°), then the sign is picked depending on the sign of the difference.
      • The normal range for returned longitudes and azimuths is [−180°, 180°].
      • A separate test suite signtest.js has been added to check this treatment.
    • The DMS.Encode function now rounds ties away from zero consistent the JavaScript's toFixed function.

  • Version 1.52.2 (released 2022-04-29)

  • Version 1.52 (released 2020-06-22)

    • Work around inaccuracy in Math.hypot (see the GeodSolve92 test).
    • Be more aggressive in preventing negative s12 and m12 for short lines.
    • Provide typescript support.

  • Version 1.51 (released 2020-11-22)

    • More symbols allowed with DMS decodings.

  • Version 1.50 (released 2019-09-24)

    • PolygonArea can now handle arbitrarily complex polygons. In the case of self-intersecting polygons the area is accumulated "algebraically", e.g., the areas of the 2 loops in a figure-8 polygon will partially cancel.
    • Fix two bugs in the computation of areas when some vertices are specified by an added edge.
    • Fix bug in computing unsigned area.
    • When parsing DMS strings ignore various non-breaking spaces.
    • Fall back to system versions of hypot, cbrt, log1p, atanh if they are available.
    • Math.cbrt, Math.atanh, and Math.asinh preserve the sign of −0.

  • Version 1.49 (released 2017-10-05)

    • Use explicit test for nonzero real numbers.

  • Version 1.48 (released 2017-04-09)

    • Change default range for longitude and azimuth to (−180°, 180°] (instead of [−180°, 180°)).

  • Version 1.47 (released 2017-02-15)

    • Improve accuracy of area calculation (fixing a flaw introduced in version 1.46).

  • Version 1.46 (released 2016-02-15)

    • Fix bugs in PolygonArea.TestEdge (problem found by threepointone).
    • Add Geodesic.DirectLine, Geodesic.ArcDirectLine, Geodesic.GenDirectLine, Geodesic.InverseLine, GeodesicLine.SetDistance, GeodesicLine.SetArc, GeodesicLine.GenSetDistance, GeodesicLine.s13, GeodesicLine.a13.
    • More accurate inverse solution when longitude difference is close to 180°.

Authors

  • algorithms + js code: Charles Karney (karney@alum.mit.edu)
  • node.js port: Yurij Mikhalevich (yurij@mikhalevi.ch)