Class: LatLonSpherical

latlon-spherical~LatLonSpherical(lat, lon)

Latitude/longitude points on a spherical model earth, and methods for calculating distances, bearings, destinations, etc on (orthodromic) great-circle paths and (loxodromic) rhumb lines.

Constructor

new LatLonSpherical(lat, lon)

Creates a latitude/longitude point on the earth’s surface, using a spherical model earth.
Parameters:
Name Type Description
lat number Latitude (in degrees).
lon number Longitude (in degrees).
Source:
Throws:
Invalid lat/lon.
Type
TypeError
Example
import LatLon from '/js/geodesy/latlon-spherical.js';
  const p = new LatLon(52.205, 0.119);

Members

(static) metresToKm

Conversion factors; 1000 * LatLon.metresToKm gives 1.
Source:

(static) metresToMiles

Conversion factors; 1000 * LatLon.metresToMiles gives 0.621371192237334.
Source:

(static) metresToNauticalMiles

Conversion factors; 1000 * LatLon.metresToMiles gives 0.5399568034557236.
Source:

lat

Latitude in degrees north from equator (including aliases lat, latitude): can be set as numeric or hexagesimal (deg-min-sec); returned as numeric.
Source:

lon

Longitude in degrees east from international reference meridian (including aliases lon, lng, longitude): can be set as numeric or hexagesimal (deg-min-sec); returned as numeric.
Source:

Methods

(static) areaOf(polygon, radiusopt) → {number}

Calculates the area of a spherical polygon where the sides of the polygon are great circle arcs joining the vertices.
Parameters:
Name Type Attributes Default Description
polygon Array.<LatLon> Array of points defining vertices of the polygon.
radius number <optional>
 6371e3 (Mean) radius of earth (defaults to radius in metres).
Source:
Returns:
The area of the polygon in the same units as radius.
Type
number
Example
const polygon = [new LatLon(0,0), new LatLon(1,0), new LatLon(0,1)];
  const area = LatLon.areaOf(polygon); // 6.18e9 m²

(static) crossingParallels(point1, point2, latitude) → {Object|null}

Returns the pair of meridians at which a great circle defined by two points crosses the given latitude. If the great circle doesn't reach the given latitude, null is returned.
Parameters:
Name Type Description
point1 LatLon First point defining great circle.
point2 LatLon Second point defining great circle.
latitude number Latitude crossings are to be determined for.
Source:
Returns:
Object containing { lon1, lon2 } or null if given latitude not reached.
Type
Object | null

(static) intersection(p1, brng1, p2, brng2) → {LatLon|null}

Returns the point of intersection of two paths defined by point and bearing.
Parameters:
Name Type Description
p1 LatLon First point.
brng1 number Initial bearing from first point.
p2 LatLon Second point.
brng2 number Initial bearing from second point.
Source:
Returns:
Destination point (null if no unique intersection defined).
Type
LatLon | null
Example
const p1 = new LatLon(51.8853, 0.2545), brng1 = 108.547;
  const p2 = new LatLon(49.0034, 2.5735), brng2 =  32.435;
  const pInt = LatLon.intersection(p1, brng1, p2, brng2); // 50.9078°N, 004.5084°E

(static) parse(lat|latlon, lonopt) → {LatLon}

Parses a latitude/longitude point from a variety of formats. Latitude & longitude (in degrees) can be supplied as two separate parameters, as a single comma-separated lat/lon string, or as a single object with { lat, lon } or GeoJSON properties. The latitude/longitude values may be numeric or strings; they may be signed decimal or deg-min-sec (hexagesimal) suffixed by compass direction (NSEW); a variety of separators are accepted. Examples -3.62, '3 37 12W', '3°37′12″W'. Thousands/decimal separators must be comma/dot; use Dms.fromLocale to convert locale-specific thousands/decimal separators.
Parameters:
Name Type Attributes Description
lat|latlon number | string | Object Latitude (in degrees) or comma-separated lat/lon or lat/lon object.
lon number | string <optional>
 Longitude (in degrees).
Source:
Throws:
Invalid point.
Type
TypeError
Returns:
Latitude/longitude point.
Type
LatLon
Example
const p1 = LatLon.parse(52.205, 0.119);                                    // numeric pair (≡ new LatLon)
  const p2 = LatLon.parse('52.205', '0.119');                                // numeric string pair (≡ new LatLon)
  const p3 = LatLon.parse('52.205, 0.119');                                  // single string numerics
  const p4 = LatLon.parse('52°12′18.0″N', '000°07′08.4″E');                  // DMS pair
  const p5 = LatLon.parse('52°12′18.0″N, 000°07′08.4″E');                    // single string DMS
  const p6 = LatLon.parse({ lat: 52.205, lon: 0.119 });                      // { lat, lon } object numeric
  const p7 = LatLon.parse({ lat: '52°12′18.0″N', lng: '000°07′08.4″E' });    // { lat, lng } object DMS
  const p8 = LatLon.parse({ type: 'Point', coordinates: [ 0.119, 52.205] }); // GeoJSON

alongTrackDistanceTo(pathStart, pathEnd, radiusopt) → {number}

Returns how far ‘this’ point is along a path from from start-point, heading towards end-point. That is, if a perpendicular is drawn from ‘this’ point to the (great circle) path, the along-track distance is the distance from the start point to where the perpendicular crosses the path.
Parameters:
Name Type Attributes Default Description
pathStart LatLon Start point of great circle path.
pathEnd LatLon End point of great circle path.
radius number <optional>
 6371e3 (Mean) radius of earth (defaults to radius in metres).
Source:
Returns:
Distance along great circle to point nearest ‘this’ point.
Type
number
Example
const pCurrent = new LatLon(53.2611, -0.7972);
  const p1 = new LatLon(53.3206, -1.7297);
  const p2 = new LatLon(53.1887,  0.1334);
  const d = pCurrent.alongTrackDistanceTo(p1, p2);  // 62.331 km

crossTrackDistanceTo(pathStart, pathEnd, radiusopt) → {number}

Returns (signed) distance from ‘this’ point to great circle defined by start-point and end-point.
Parameters:
Name Type Attributes Default Description
pathStart LatLon Start point of great circle path.
pathEnd LatLon End point of great circle path.
radius number <optional>
 6371e3 (Mean) radius of earth (defaults to radius in metres).
Source:
Returns:
Distance to great circle (-ve if to left, +ve if to right of path).
Type
number
Example
const pCurrent = new LatLon(53.2611, -0.7972);
  const p1 = new LatLon(53.3206, -1.7297);
  const p2 = new LatLon(53.1887, 0.1334);
  const d = pCurrent.crossTrackDistanceTo(p1, p2);  // -307.5 m

destinationPoint(distance, bearing, radiusopt) → {LatLon}

Returns the destination point from ‘this’ point having travelled the given distance on the given initial bearing (bearing normally varies around path followed).
Parameters:
Name Type Attributes Default Description
distance number Distance travelled, in same units as earth radius (default: metres).
bearing number Initial bearing in degrees from north.
radius number <optional>
 6371e3 (Mean) radius of earth (defaults to radius in metres).
Source:
Returns:
Destination point.
Type
LatLon
Example
const p1 = new LatLon(51.47788, -0.00147);
  const p2 = p1.destinationPoint(7794, 300.7); // 51.5136°N, 000.0983°W

distanceTo(point, radiusopt) → {number}

Returns the distance along the surface of the earth from ‘this’ point to destination point. Uses haversine formula: a = sin²(Δφ/2) + cosφ1·cosφ2 · sin²(Δλ/2); d = 2 · atan2(√a, √(a-1)).
Parameters:
Name Type Attributes Default Description
point LatLon Latitude/longitude of destination point.
radius number <optional>
 6371e3 Radius of earth (defaults to mean radius in metres).
Source:
Throws:
Invalid radius.
Type
TypeError
Returns:
Distance between this point and destination point, in same units as radius.
Type
number
Example
const p1 = new LatLon(52.205, 0.119);
  const p2 = new LatLon(48.857, 2.351);
  const d = p1.distanceTo(p2);       // 404.3×10³ m
  const m = p1.distanceTo(p2, 3959); // 251.2 miles

equals(point) → {bool}

Checks if another point is equal to ‘this’ point.
Parameters:
Name Type Description
point LatLon Point to be compared against this point.
Source:
Returns:
True if points have identical latitude and longitude values.
Type
bool
Example
const p1 = new LatLon(52.205, 0.119);
  const p2 = new LatLon(52.205, 0.119);
  const equal = p1.equals(p2); // true

finalBearingTo(point) → {number}

Returns final bearing arriving at destination point from ‘this’ point; the final bearing will differ from the initial bearing by varying degrees according to distance and latitude.
Parameters:
Name Type Description
point LatLon Latitude/longitude of destination point.
Source:
Returns:
Final bearing in degrees from north (0°..360°).
Type
number
Example
const p1 = new LatLon(52.205, 0.119);
  const p2 = new LatLon(48.857, 2.351);
  const b2 = p1.finalBearingTo(p2); // 157.9°

initialBearingTo(point) → {number}

Returns the initial bearing from ‘this’ point to destination point.
Parameters:
Name Type Description
point LatLon Latitude/longitude of destination point.
Source:
Returns:
Initial bearing in degrees from north (0°..360°).
Type
number
Example
const p1 = new LatLon(52.205, 0.119);
  const p2 = new LatLon(48.857, 2.351);
  const b1 = p1.initialBearingTo(p2); // 156.2°

intermediatePointTo(point, fraction) → {LatLon}

Returns the point at given fraction between ‘this’ point and given point.
Parameters:
Name Type Description
point LatLon Latitude/longitude of destination point.
fraction number Fraction between the two points (0 = this point, 1 = specified point).
Source:
Returns:
Intermediate point between this point and destination point.
Type
LatLon
Example
const p1 = new LatLon(52.205, 0.119);
  const p2 = new LatLon(48.857, 2.351);
  const pInt = p1.intermediatePointTo(p2, 0.25); // 51.3721°N, 000.7073°E

maxLatitude(bearing) → {number}

Returns maximum latitude reached when travelling on a great circle on given bearing from ‘this’ point (‘Clairaut’s formula’). Negate the result for the minimum latitude (in the southern hemisphere). The maximum latitude is independent of longitude; it will be the same for all points on a given latitude.
Parameters:
Name Type Description
bearing number Initial bearing.
Source:
Returns:
Maximum latitude reached.
Type
number

midpointTo(point) → {LatLon}

Returns the midpoint between ‘this’ point and destination point.
Parameters:
Name Type Description
point LatLon Latitude/longitude of destination point.
Source:
Returns:
Midpoint between this point and destination point.
Type
LatLon
Example
const p1 = new LatLon(52.205, 0.119);
  const p2 = new LatLon(48.857, 2.351);
  const pMid = p1.midpointTo(p2); // 50.5363°N, 001.2746°E

rhumbBearingTo(point) → {number}

Returns the bearing from ‘this’ point to destination point along a rhumb line.
Parameters:
Name Type Description
point LatLon Latitude/longitude of destination point.
Source:
Returns:
Bearing in degrees from north.
Type
number
Example
const p1 = new LatLon(51.127, 1.338);
  const p2 = new LatLon(50.964, 1.853);
  const d = p1.rhumbBearingTo(p2); // 116.7°

rhumbDestinationPoint(distance, bearing, radiusopt) → {LatLon}

Returns the destination point having travelled along a rhumb line from ‘this’ point the given distance on the given bearing.
Parameters:
Name Type Attributes Default Description
distance number Distance travelled, in same units as earth radius (default: metres).
bearing number Bearing in degrees from north.
radius number <optional>
 6371e3 (Mean) radius of earth (defaults to radius in metres).
Source:
Returns:
Destination point.
Type
LatLon
Example
const p1 = new LatLon(51.127, 1.338);
  const p2 = p1.rhumbDestinationPoint(40300, 116.7); // 50.9642°N, 001.8530°E

rhumbDistanceTo(point, radiusopt) → {number}

Returns the distance travelling from ‘this’ point to destination point along a rhumb line.
Parameters:
Name Type Attributes Default Description
point LatLon Latitude/longitude of destination point.
radius number <optional>
 6371e3 (Mean) radius of earth (defaults to radius in metres).
Source:
Returns:
Distance in km between this point and destination point (same units as radius).
Type
number
Example
const p1 = new LatLon(51.127, 1.338);
  const p2 = new LatLon(50.964, 1.853);
  const d = p1.distanceTo(p2); //  40.31 km

rhumbMidpointTo(point) → {LatLon}

Returns the loxodromic midpoint (along a rhumb line) between ‘this’ point and second point.
Parameters:
Name Type Description
point LatLon Latitude/longitude of second point.
Source:
Returns:
Midpoint between this point and second point.
Type
LatLon
Example
const p1 = new LatLon(51.127, 1.338);
  const p2 = new LatLon(50.964, 1.853);
  const pMid = p1.rhumbMidpointTo(p2); // 51.0455°N, 001.5957°E

toGeoJSON() → {Object}

Converts ‘this’ point to a GeoJSON object.
Source:
Returns:
this point as a GeoJSON ‘Point’ object.
Type
Object

toString(formatopt, dpopt) → {string}

Returns a string representation of ‘this’ point, formatted as degrees, degrees+minutes, or degrees+minutes+seconds.
Parameters:
Name Type Attributes Default Description
format string <optional>
 d Format point as 'd', 'dm', 'dms', or 'n' for signed numeric.
dp number <optional>
 4|2|0 Number of decimal places to use: default 4 for d, 2 for dm, 0 for dms.
Source:
Throws:
Invalid format.
Type
RangeError
Returns:
Comma-separated formatted latitude/longitude.
Type
string
Example
const greenwich = new LatLon(51.47788, -0.00147);
  const d = greenwich.toString();                        // 51.4779°N, 000.0015°W
  const dms = greenwich.toString('dms', 2);              // 51°28′40.37″N, 000°00′05.29″W
  const [lat, lon] = greenwich.toString('n').split(','); // 51.4779, -0.0015