Class: LatLonSpherical

latlon-spherical~LatLonSpherical

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

Constructor

new LatLonSpherical(lat, lon)

Creates a LatLon point on the earth's surface at the specified latitude / longitude.
Parameters:
Name Type Description
lat number Latitude in degrees.
lon number Longitude in degrees.
Source:

Methods

(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
var p1 = new LatLon(51.8853, 0.2545), brng1 = 108.547;
  var p2 = new LatLon(49.0034, 2.5735), brng2 =  32.435;
  var pInt = LatLon.intersection(p1, brng1, p2, brng2); // 50.9078°N, 004.5084°E

bearingTo(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.
Type
number
Example
var p1 = new LatLon(52.205, 0.119);
  var p2 = new LatLon(48.857, 2.351);
  var b1 = p1.bearingTo(p2); // 156.2°

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
var pCurrent = new LatLon(53.2611, -0.7972);
  var p1 = new LatLon(53.3206, -1.7297);
  var p2 = new LatLon(53.1887, 0.1334);
  var 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
var p1 = new LatLon(51.4778, -0.0015);
  var p2 = p1.destinationPoint(7794, 300.7); // 51.5135°N, 000.0983°W

distanceTo(point, radiusopt) → {number}

Returns the distance from ‘this’ point to destination point (using haversine formula).
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 between this point and destination point, in same units as radius.
Type
number
Example
var p1 = new LatLon(52.205, 0.119);
  var p2 = new LatLon(48.857, 2.351);
  var d = p1.distanceTo(p2);       // 404.3 km
  var m = p1.distanceTo(p2, 3959); // 251.2 miles

finalBearingTo(point) → {number}

Returns final bearing arriving at destination 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.
Type
number
Example
var p1 = new LatLon(52.205, 0.119);
  var p2 = new LatLon(48.857, 2.351);
  var b2 = p1.finalBearingTo(p2); // 157.9°

maxLatitude(bearing, latitude)

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.
latitude number Starting latitude.
Source:

midpointTo(point) → {LatLon}

Returns the midpoint between ‘this’ point and the supplied point.
Parameters:
Name Type Description
point LatLon Latitude/longitude of destination point.
Source:
Returns:
Midpoint between this point and the supplied point.
Type
LatLon
Example
var p1 = new LatLon(52.205, 0.119);
  var p2 = new LatLon(48.857, 2.351);
  var 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
var p1 = new LatLon(51.127, 1.338);
  var p2 = new LatLon(50.964, 1.853);
  var d = p1.rhumbBearingTo(p2); // d.toFixed(1): 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
var p1 = new LatLon(51.127, 1.338);
  var 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
var p1 = new LatLon(51.127, 1.338);
  var p2 = new LatLon(50.964, 1.853);
  var 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
var p1 = new LatLon(51.127, 1.338);
  var p2 = new LatLon(50.964, 1.853);
  var pMid = p1.rhumbMidpointTo(p2); // 51.0455°N, 001.5957°E

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>
 dms Format point as 'd', 'dm', 'dms'.
dp number <optional>
 0|2|4 Number of decimal places to use: default 0 for dms, 2 for dm, 4 for d.
Source:
Returns:
Comma-separated formatted latitude/longitude.
Type
string