Class: LatLonNvectorSpherical

latlon-nvector-spherical~LatLonNvectorSpherical(lat, lon)

Latitude/longitude points on an spherical model earth, and methods for calculating distances, bearings, destinations, etc on great circle paths.

Constructor

new LatLonNvectorSpherical(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-nvector-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. Uses Girard’s theorem: A = [Σθᵢ − (n−2)·π]·R²
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) centreOf(polygon) → {LatLon}

Calculates the centre of a spherical polygon where the sides of the polygon are great circle arcs joining the vertices. Based on a ‘non-obvious application of Stokes’ theorem’ giving C = Σ[a×b / |a×b| ⋅ θab/2] for each pair of consecutive vertices a, b; stackoverflow.com/questions/19897187#answer-38201499.
Parameters:
Name Type Description
polygon Array.<LatLon> Array of points defining vertices of the polygon.
Source:
Returns:
Centre point of the polygon.
Type
LatLon
Example
const polygon = [ new LatLon(0, 0), new LatLon(1, 0), new LatLon(1, 1), new LatLon(0, 1) ];
  const centre = LatLon.centreOf(polygon); // 0.500°N, 0.500°E

(static) intersection(path1start, path1brngEnd, path2start, path2brngEnd) → {LatLon}

Returns the point of intersection of two paths each defined by point pairs or start point and bearing.
Parameters:
Name Type Description
path1start LatLon Start point of first path.
path1brngEnd LatLon | number End point of first path or initial bearing from first start point.
path2start LatLon Start point of second path.
path2brngEnd LatLon | number End point of second path or initial bearing from second start point.
Source:
Throws:
Invalid parameter.
Type
TypeError
Returns:
Destination point (null if no unique intersection defined)
Type
LatLon
Example
const p1 = new LatLon(51.8853, 0.2545), brng1 = 108.55;
  const p2 = new LatLon(49.0034, 2.5735), brng2 =  32.44;
  const pInt = LatLon.intersection(p1, brng1, p2, brng2); // 50.9076°N, 004.5086°E

(static) meanOf(points) → {LatLon}

Returns point representing geographic mean of supplied points.
Parameters:
Name Type Description
points Array.<LatLon> Array of points to be averaged.
Source:
Returns:
Point at the geographic mean of the supplied points.
Type
LatLon
Example
const p = LatLon.meanOf([ new LatLon(1, 1), new LatLon(4, 2), new LatLon(1, 3) ]); // 02.0001°N, 002.0000°E

(static) triangulate(point1, bearing1, point2, bearing2) → {LatLon}

Locates a point given two known locations and bearings from those locations.
Parameters:
Name Type Description
point1 LatLon First reference point.
bearing1 number Bearing (in degrees from north) from first reference point.
point2 LatLon Second reference point.
bearing2 number Bearing (in degrees from north) from second reference point.
Source:
Returns:
Triangulated point.
Type
LatLon
Example
const p1 = new LatLon(50.7175,1.65139), p2 = new LatLon(50.9250,1.7094);
  const p = LatLon.triangulate(p1, 333.3508, p2, 310.1414); // 51.1297°N, 001.3214°E

(static) trilaterate(point1, distance1, point2, distance2, point3, distance3, radiusopt) → {LatLon}

Locates a latitude/longitude point at given distances from three other points.
Parameters:
Name Type Attributes Default Description
point1 LatLon First reference point.
distance1 number Distance to first reference point (same units as radius).
point2 LatLon Second reference point.
distance2 number Distance to second reference point (same units as radius).
point3 LatLon Third reference point.
distance3 number Distance to third reference point (same units as radius).
radius number <optional>
 6371e3 (Mean) radius of earth (defaults to radius in metres).
Source:
Returns:
Trilaterated point.
Type
LatLon
Example
LatLon.trilaterate(new LatLon(0, 0), 157e3, new LatLon(0, 1), 111e3, new LatLon(1, 0), 111e3); // 00.9985°N, 000.9986°E

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

Returns how far ‘this’ point is along a path from from start-point, heading on bearing or 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.
pathBrngEnd LatLon | number End point of great circle path or initial bearing from great circle start point.
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, pathBrngEnd, radiusopt) → {number}

Returns (signed) distance from ‘this’ point to great circle defined by start-point and end-point/bearing.
Parameters:
Name Type Attributes Default Description
pathStart LatLon Start point of great circle path.
pathBrngEnd LatLon | number End point of great circle path or initial bearing from great circle start point.
radius number <optional>
 6371e3 (Mean) radius of earth (defaults to radius in metres).
Source:
Throws:
Invalid parameter.
Type
TypeError
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), brng = 96.0;
  const d = pCurrent.crossTrackDistanceTo(p1, brng); // Number(d.toPrecision(4)): -305.7

  const p1 = new LatLon(53.3206, -1.7297), p2 = new LatLon(53.1887, 0.1334);
  const d = pCurrent.crossTrackDistanceTo(p1, p2);   // Number(d.toPrecision(4)): -307.5

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 on the surface of the sphere from ‘this’ point to destination point.
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 point/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 km

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:
Throws:
Invalid point.
Type
TypeError
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:
Throws:
Invalid point.
Type
TypeError
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:
Throws:
Invalid point.
Type
TypeError
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°

intermediatePointOnChordTo(point, fraction) → {LatLon}

Returns the latitude/longitude point projected from the point at given fraction on a straight line between 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:
Throws:
Invalid point.
Type
TypeError
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.3723°N, 000.7072°E

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:
Throws:
Invalid point/fraction.
Type
TypeError
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.7072°E

isEnclosedBy(polygon) → {bool}

Tests whether ‘this’ point is enclosed by the polygon defined by a set of points.
Parameters:
Name Type Description
polygon Array.<LatLon> Ordered array of points defining vertices of polygon.
Source:
Returns:
Whether this point is enclosed by polygon.
Type
bool
Example
const bounds = [ new LatLon(45,1), new LatLon(45,2), new LatLon(46,2), new LatLon(46,1) ];
  const p = new LatLon(45.1, 1.1);
  const inside = p.isEnclosedBy(bounds); // true

isWithinExtent(point1, point2) → {boolean}

Returns whether this point is within the extent of a line segment joining point 1 & point 2. If this point is not on the great circle defined by point1 & point 2, returns whether it is within the area bound by perpendiculars to the great circle at each point (in the same hemisphere).
Parameters:
Name Type Description
point1 LatLon First point defining segment.
point2 LatLon Second point defining segment.
Source:
Returns:
Whether this point is within extent of segment.
Type
boolean
Example
const p1 = new LatLon(51, 1), p2 = new LatLon(52, 2);
  const within1 = new LatLon(52, 1).isWithinExtent(p1, p2); // true
  const within2 = new LatLon(51, 0).isWithinExtent(p1, p2); // false

midpointTo(point) → {LatLon}

Returns the midpoint between ‘this’ point and destination point.
Parameters:
Name Type Description
point LatLon Latitude/longitude of destination point.
Source:
Throws:
Invalid point.
Type
TypeError
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

nearestPointOnSegment(point1, point2) → {LatLon}

Returns closest point on great circle segment between point1 & point2 to ‘this’ point. If this point is ‘within’ the extent of the segment, the point is on the segment between point1 & point2; otherwise, it is the closer of the endpoints defining the segment.
Parameters:
Name Type Description
point1 LatLon Start point of great circle segment.
point2 LatLon End point of great circle segment.
Source:
Returns:
Closest point on segment.
Type
LatLon
Example
const p1 = new LatLon(51.0, 1.0);
  const p2 = new LatLon(51.0, 2.0);

  const p0 = new LatLon(51.0, 1.9);
  const p = p0.nearestPointOnSegment(p1, p2); // 51.0004°N, 001.9000°E
  const d = p.distanceTo(p);                  // 42.71 m

  const p0 = new LatLon(51.0, 2.1);
  const p = p0.nearestPointOnSegment(p1, p2); // 51.0000°N, 002.0000°E

toGeoJSON() → {Object}

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

toNvector() → {Nvector}

Converts ‘this’ latitude/longitude point to an n-vector (normal to earth's surface).
Source:
Returns:
Normalised n-vector representing lat/lon point.
Type
Nvector
Example
const p = new LatLon(45, 45);
  const v = p.toNvector();      // [0.5000,0.5000,0.7071]

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:
Returns:
Comma-separated formatted latitude/longitude.
Type
string
Example
const greenwich = new LatLon(51.47788, -0.00147);
  const d = greenwich.toString();                        // 51.4778°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.4778, -0.0015