# 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:
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>
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>
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>
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>
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>
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``````

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>
Source:
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:
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:
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:
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:
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:
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``````