Magellan

Introducing Magellan

From validating the rules of composition for latitudes and longitudes to deciding on the format of the output, working with geo-coordinates can be a pretty big pain.

Until Magellan, that is...

Now, working with coordinates can be as simple as:

// decimal-degrees to degrees-minutes-seconds
magellan(12.3456).latitude().toDMS()      // 12°20'44.1600"N
magellan(-12.3456).latitude().toDMS(' ')  // 12° 20' 44.1600" S
magellan(123.456).longitude().toDMS()     // 123°27'21.6000"E
magellan(-123.456).longitude().toDMS(' ') // 123° 27' 21.6000" W

// or degrees-minutes-seconds to decimal-degrees
magellan('12°20\'44.1600"N').latitude().toDD()   // 12.3456
magellan('12°20\'44.1600"S').latitude().toDD()   // -12.3456
magellan('123°27\'21.6000"E').longitude().toDD() // 123.4560
magellan('123°27\'21.6000"W').longitude().toDD() // -123.4560

// or degrees and decimal minutes
magellan('12°20.7402\'N').latitude().toDD()   // 12.3456
magellan('12°20.7402\'S').latitude().toDD()   // -12.3456
magellan('123°27.4020\'E').longitude().toDD() // 123.4560
magellan('123°27.4020\'W').longitude().toDD() // -123.4560

All nice and gussied up for ya'!

Getting Started

Magellan is designed to fit seamlessly into your application environment. It can be used standalone, as a <script> include on your page, or can be loaded as a CommonJS or AMD module.

To start using Magellan is simple. First, download the source file and include in your project. You can embed Magellan into your app using one of the following methods:

In an HTML Document

<!-- Somewhere in your HTML file -->
<script src="/path/to/magellan.js" type="text/javascript"></script>

In a CommonJS environment (e.g. NodeJS)

var magellan = require('/path/to/magellan')

In an AMD environment (e.g. RequireJS)

require(['/path/to/magellan'], function(magellan) { ... }

Basic Usage

Initializing a Magellan chain

Magellan was designed with flexibility in mind, and is capable of receiving your coordinate inputs in a number of ways:

// degrees-decimal input formats
magellan(12.3456)                         // positive number
magellan(-12.3456)                        // negative number
magellan('12.3456')                       // string in degrees-decimal format (can also start with +/-)
magellan(12.3456, 'E')                    // with a 2nd argument indicating the compass direction [NSEW]

// degrees-minutes-seconds input formats
magellan('123')                           // just degrees (or just degrees and minutes)
magellan('12°34\'56.7890"S')              // degrees, minutes, seconds, milliseconds and direction
magellan('12 34 56 N')                    // space-delimited string in degrees-minutes-seconds format
magellan('N12 34 56')                     // same as above, with leading compass direction

// degrees-minutes-decimal input formats
magellan('12°34.56S')              // degrees, minutes, seconds, milliseconds and direction
magellan('12 34.56 N')                    // space-delimited string in degrees-minutes-seconds format
magellan('N12 34.56')                     // same as above, with leading compass direction

Working with a parsed coordinate

Once you have an initialized Magellan chain, you can grab your parsed coordinate:

magellan('12°34\'56.7890"S').coordinate  // {degrees: 12, minutes: 34, seconds: 56.789, direction: 'S'}

Or if you are interested in formatting your coordinate, you can use the more interesting features below:

magellan(12.3456).toDD()        // print 12.3456 in +/-DD.dddd format
magellan('123').toDMS()                    // print 12.3456 in DD°MM'SS.mmmmm" format
magellan('123').toDMS('_')                 // same as above, except delimit the output with '_' character
magellan(12.3456).latitude()               // treat 12.3456 as latitude
magellan(12.3456).latitude().toDD()        // print 12.3456 as latitude in +/-DD.dddd format

magellan(12.3456).longitude()              // treat as longitude, ready for chained methods seen above

Comparing coordinates

With version 1.0.2, the ability to compare equality in coordinates has been added. So now, for example, you can do the following:

var coord1 = magellan(123.456).longitude();
var coord2 = magellan('123°27\'21.6000"E')
coord1.equals(coord2)                       // true
coord2.equals(magellan(123.456)             // true
coord1.equals(magellan(-123.456))           // false

A word on using .latitude() and .longitude()

.latitude() and .longitude() applied to a Magellan chain act as casts, essentially converting the parsed coordinates into a latitude or longitude, respectively. In doing so, these functions perform basic validation. In the event that a validation rule fails, the function will return null, breaking the chain.

The validation rules are as follows:

1. A latitude must not exceed +/- 90 degrees. A longitude must not exceed +/- 180 degrees.

2. Minutes and seconds must be less than 60.

3. If chaining .latitude(), compass direction (if present) must be either 'N' or 'S'. 
   'E' or 'W' when chaining .longitude()

Authors and Contributors

If interested in contributing, contact Dave Barbalato (@dbarbalato)