Leaflet.Geodesic

Add-on for Leaflet to draw geodesic lines and circles. A geodesic line is the shortest path between two given positions on the earth surface. It's based on Vincenty's formulae implemented by Chris Veness for highest precision.

Live Demos and Tutorials

Observable-Notebook

API-Documentation

⚗️ Leaflet 2.0 Preview

Leaflet is planning to release a new major version by the end of this year. Leaflet.Geodesic already supports this with a new release: v3.0.0-alpha.2.

<details> <summary>Migration Guide</summary>

Migrate from Leaflet.Geodesic 2.x to 3.x

Leaflet.Geodesic requires Leaflet 2 to work.

1. Replace the <script src=... for Leaflet and Leaflet.Geodesic with an importmap as follows:

<script type="importmap">
    {
        "imports": {
            "leaflet": "https://unpkg.com/leaflet@2.0.0-alpha.1/dist/leaflet.js",
            "leaflet.geodesic": "https://unpkg.com/leaflet.geodesic@3.0.0-alpha.2/dist/leaflet.geodesic.esm.min.js"
        },
        "integrity": {
            "https://unpkg.com/leaflet.geodesic@3.0.0-alpha.2/dist/leaflet.geodesic.esm.min.js": "sha512-5lUYcVPLuTl2uEsodxmC2AJQ/uFqQ2mEWPtHGL8ktTr5f212ddNqR1iGyuT0Gy8HY8V4KZmVX6PsEOuFBHZD3Q=="
        }
    }
</script>

The integrity property is optional but recommended (Subresource Integrity).

2. Replace the <script type="text/javascript"> of your map setup with

<script type="module">
    import { LeafletMap, TileLayer, Marker, LatLng, Polyline, Control, DomUtil } from 'leaflet';
    import { GeodesicLine } from "leaflet.geodesic";
    // ...
</script>

Leaflet.Geodsic provides two classes: GeodesicLine and GeodesicCircle. Make sure to import the class you need.

3. Classes provided by Leaflet and Leaflet.Geodesic must be instanciated using new as follows:

// Leaflet setup
const map = new LeafletMap(/* your arguments */)
const tileLayer = new TileLayer(/* your arguments */).addTo(map);

// Leaflet.Geodesic setup
const geodesicLine = new GeodesicLine().addTo(map);
const geodesicCircle = new GeodesicCircle().addTo(map);

Please note that the global L object is no longer used.

Everything else is unchanged and the existing documentation is still valid.

</details>

See Leaflet.Geodesic 3 Demos on how to use Leaflet.Geodesic 3 with Leaflet 2.

Add the plugin to your project

Leaflet.Geodesic is available via CDN. Add the following snippet to your html-file after you have included leaflet.js.

<!-- Make sure you put this AFTER leaflet.js -->
<script src="https://cdn.jsdelivr.net/npm/leaflet.geodesic"></script>

Leaflet.Geodesic is available via the following CDNs:

• unpkg
• jsDelivr
• npmjs

Add it in your nodejs-project with npm i leaflet.geodesic.

It is good practice, to pin the plug-in to a specific version and use Subresource Integrity. Check the release page for the latest version, links and checksum. A checksum can by verified with npm run build, is stored in dist/leaflet.geodesic.umd.min.js.sha512 on jsDelivr and unpkg and is shown in the release notes.

Basic usage

• L.Geodesic draws geodesic lines between all points of a given line- or multiline-string.
• L.GeodesicCircle draws a circle with a specific radius around a given point.

The Objects can be created as follows:

const geodesicLine = new L.Geodesic().addTo(map);   // creates a blank geodesic-line-object and adds it to the map
const geodesicCircle = new L.GeodesicCircle().addTo(map);   // creates a blank geodesic-circle-object and adds it to the map

Alternative method:

const geodesicLine = L.geodesic().addTo(map);   // lower-case, w/o new-keyword
const geodesicCircle = L.geodesiccircle().addTo(map);   // lower-case, w/o new-keyword

Make sure you add the geodesic-object to the map (.addTo(map)). It won't display otherwise.

Each constructor is defined as:

Geodesic(latlngs?: L.LatLngExpression[] | L.LatLngExpression[][], options?: GeodesicOptions)
GeodesicCircle(center?: L.LatLngExpression, options?: GeodesicOptions)

Both classes are extended from L.Polyline, so all methods, events and options for L.Polyline can be used with L.Geodesic and L.GeodesicCircle here as well. Any alt-properties given with any points are preserved by L.Geodesic.

Geodesic Lines

This draws a line. The geometry (points) to use can be given during creation as:

Objects (Literals)

const Berlin = {lat: 52.5, lng: 13.35};
const LosAngeles = {lat: 33.82, lng: -118.38};
const geodesic = new L.Geodesic([Berlin, LosAngeles]).addTo(map);

LatLng-Class

const Berlin = new L.LatLng(52.5, 13.35);
const LosAngeles = new L.LatLng(33.82, -118.38);
const geodesic = new L.Geodesic([Berlin, LosAngeles]).addTo(map);

Tuples

const Berlin = [52.5, 13.35];
const LosAngeles = [33.82, -118.38];
const geodesic = new L.Geodesic([Berlin, LosAngeles]).addTo(map);

Line-strings

Multiple consecutive points can be given as an array (linestring):

const places = [
    new L.LatLng(52.5, 13.35), // Berlin
    new L.LatLng(33.82, -118.38), // Los Angeles
    new L.LatLng(-33.44, -70.71), // Santiago
    new L.LatLng(-33.94, 18.39), // Capetown
];
const geodesic = new L.Geodesic(places).addTo(map);

Multi-line-strings

Multiple independent linestrings can be defined as a 2-dimensional array of points:

const places = [
    [   // 1st line
        new L.LatLng(52.5, 13.35), // Berlin
        new L.LatLng(33.82, -118.38), // Los Angeles
    ],
    [   // 2nd line
        new L.LatLng(-33.44, -70.71), // Santiago
        new L.LatLng(-33.94, 18.39), // Capetown
    ]
];
const geodesic = new L.Geodesic(places).addTo(map);

GeoJSON-Support

GeoJSON-data can be used to create geodesic lines with the fromGeoJson() method:

const geojson = {
    "type": "LineString",
    "coordinates": [
        [13.35, 52.5], [-122.33, 47.56], [18.39, -33.94], [116.39, 39.92], [13.35, 52.5]
    ]
};
const geodesic = new L.Geodesic().addTo(map);
geodesic.fromGeoJson(geojson);

Updating the geometry

Set new geometry

The Geodesic-Class provides a setLatLngs()-Method, that can be used to update the geometry of an existing L.Geodesic-object:

const geodesic = new L.Geodesic().addTo(map);   // add empty object to the map

const Berlin = new L.LatLng(52.5, 13.35);
const LosAngeles = new L.LatLng(33.82, -118.38);

geodesic.setLatLngs([Berlin, LosAngeles])   // update in-place

The setLatLngs()-Method accepts the same types (Literal, Tuple, LatLang-Class, Linstring, Multilinestring) as the L.Geodesic-constructor itself. Please refer to the section about geodesic circles below, on how to update a circle geometry.

Delete geometry

Delete the existing geometry by setting an empty array geodesic.setLatLngs([]).

adding points

Points can be added to existing geodesic lines with addLatLng():

const Berlin = new L.LatLng(52.5, 13.35);
const LosAngeles = new L.LatLng(33.82, -118.38);
const Beijing = new L.LatLng(39.92, 116.39);

const geodesic = new L.Geodesic([Berlin, LosAngeles]).addTo(map);
geodesic.addLatLng(Beijing);    // results in [[Berlin, LosAngeles, Beijing]

The new point will always be added to the last linestring of a multiline. You can define a specific linestring to add to by reading the points property before and hand over a specific linestring as second parameter:

const Berlin = new L.LatLng(52.5, 13.35);
const LosAngeles = new L.LatLng(33.82, -118.38);
const Beijing = new L.LatLng(39.92, 116.39 );
const Capetown =  new L.LatLng(-33.94, 18.39 );
const Santiago = new L.LatLng(