Home

Awesome

GreatCircle

A set of three functions, useful in geographical calculations of different sorts. Available for PHP, Python, Javascript, Ruby and Go.

Live demo of the JavaScript implementation.

Usage with node.js

Install npm module great-circle

npm install great-circle

Usage in node.js or with browserify

var GreatCircle = require('great-circle')

Usage with Go

Install the module

go get github.com/mwgg/GreatCircle

Import the module and use. Note that due to lack of support for optional arguments and overloading, the unit/radius argument is not optional in Go, and needs to be passed as either GreatCircle.UnitFixed(string) or GreatCircle.UnitValue(float)

import "github.com/mwgg/GreatCircle"
GreatCircle.Distance(51.507222, -0.1275, 48.8567, 2.3508, GreatCircle.UnitFixed("KM"))
GreatCircle.Distance(51.507222, -0.1275, 48.8567, 2.3508, GreatCircle.UnitValue(6371.009))

Distance

Takes two sets of geographic coordinates in decimal degrees and produces distance along the great circle line. Output in kilometers by default.

PHP:

// Distance from London to Paris
echo GreatCircle::distance(51.507222, -0.1275, 48.8567, 2.3508);
// Output: 343.46748684413

Python:

print( GreatCircle.distance(51.507222, -0.1275, 48.8567, 2.3508) )

JavaScript:

document.write ( GreatCircle.distance(51.507222, -0.1275, 48.8567, 2.3508) );

Ruby

puts GreatCircle.distance(51.507222, -0.1275, 48.8567, 2.3508)

Go

fmt.Println(GreatCircle.Distance(51.507222, -0.1275, 48.8567, 2.3508, GreatCircle.UnitFixed("KM")))

The fifth argument (optional in some implementations) and allows to specify desired units, and it can also be passed in form of planet radius in any unit, to produce output in this unit.

// Distance from JFK airport to La Guardia airport in feet
echo GreatCircle::distance(40.63980103, -73.77890015, 40.77719879, -73.87259674, "FT");
// Output: 56425.612628758
// Distance between North and South poles on Mars (3389.5 is mean radius of Mars in kilometers)
echo GreatCircle::distance(90, 0, -90, 0, 3389.5);
// Output: 10648.428299343
// Distance between Moscow and New York in furlongs (31670.092 is Earth radius in furlongs)
echo GreatCircle::distance(55.75, 37.616667, 40.7127, -74.0059, 31670.092);
// Output: 37335.295755141

Bearing

Takes two sets of geographic coordinates in decimal degrees and produces bearing (azimuth) from the first set of coordinates to the second set.

// Bearing from Paris to London in decimal degrees
echo GreatCircle::bearing(48.8567, 2.3508, 51.507222, -0.1275);
// Output: 330.03509575101

Destination

Takes one set of geographic coordinates in decimal degrees, azimuth and distance to produce a new set of coordinates, specified distance and bearing away from original.

// Coordinates of a location 100 KM away from Paris, traveling in the direction of London
$dest = GreatCircle::destination(48.8567, 2.3508, 330.035, 100);
printf("Latitude: %f, Longitude: %f", $dest["LAT"], $dest["LON"]);
// Output: Latitude: 49.633753, Longitude: 1.657274

Just like Distance, Destination assumes entered distance is in kilometers, but takes an optional argument to specify desired unit.

// Coordinates of a location 500 nautical miles away from Paris, traveling in the direction of New York
$brg = GreatCircle::bearing(48.8567, 2.3508, 40.7127, -74.0059);
$dest = GreatCircle::destination(48.8567, 2.3508, $brg, 500, "NM");
printf("Latitude: %f, Longitude: %f", $dest["LAT"], $dest["LON"]);
// Output: Latitude: 51.306719, Longitude: -10.071875