n-vector

Stability: 1 - Experimental

Normal vector and a distance function to determine central angle between normal vectors.

Contributors

@tristanls, @mikedeboer

Installation

npm install n-vector

Tests

npm test

Visual test

npm run sketch

Usage

var NVector = require('n-vector');
 
var position1 = NVector.fromLatLon(31.565665, -96.811523);
var position2 = NVector.fromLatLon(31.465952, -97.026443);
var centralAngle = NVector.distance(position1, position2);
// 0.0036406600953623955
var greatCircleDistanceInKm = centralAngle * 6371; // Earth radius ~6371km
// 23.194645467553823 km
var greatCircleDistanceInMi = centralAngle * 3959; // Earth radius ~3959mi
// 14.413373317539724 mi

Overview

The normal vector to the Earth ellipsoid (called n-vector) is a non-singular position representation that turns out to be very convenient for practical position calculations.

source: A Non-singular Horizontal Position Representation

The non-singular aspect of n-vector makes the calculations required simple and without special cases to consider that are present when dealing with crossing prime meridian and at the Earth poles. For a deeper and more precise explanation see A Non-singular Horizontal Position Representation.

Documentation

NVector

Public API

• NVector.DEGREES_TO_RADIANS
• NVector.distance(a, b)
• NVector.fromLatLon(latitude, longitude)
• new NVector(x, y, z)

NVector.DEGREES_TO_RADIANS

• DEGREES_TO_RADIANS: Number 0.0174532925, multiplier to convert decimal degrees into radians.

NVector.distance(a, b)

• a: NVector First normal vector.
• b: NVector Second normal vector.
• Return: Number Central angle between a and b (multiply by sphere radius to determine the great circle distance).

Returns a central angle between two instances of NVector. To get actual distance, multiply the central angle by the estimate of Earth's radius (if it was a perfect sphere), 6371km or 3959mi.

NVector.fromLatLon(latitude, longitude)

• latitude: Number Latitude in decimal degrees (ex: 31.565665).
• longitude: Number Longitude in decimal degrees (ex: -96.811523).
• Return: NVector Normal vector corresponding to given latitude and longitude.

Creates a new NVector instance from given latitude and longitude.

new NVector(x, y, z)

• x: Number NVector "x" component.
• y: Number NVector "y" component.
• z: Number NVector "z" component.
• Return: NVector Normal vector with x, y, and z components.

Creates a new NVector instance.

Sources

The implementation has been sourced from:

• A Non-singular Horizontal Position Representation