node-geo-box

A node.js module that provides useful geographic box information (including geohash boxes!) for unit conversion, distortion measurement and equivelency.

Box distortion as a function of latitude, conversion from degrees to meters, and meters to degrees. Similarly useful information about geohash boxes are provided in this module as well, including geohash box distortion, geohash box size in meters, and equivelency of geohash bit depth to box size in meters.

This module uses general estimate calculations. Please leave feedback in the module's GitHub issues tracker or consider contributing for more precise calculations.

Installation

npm install geo-box

Usage

var geoBox = require('geo-box');

Creating a Box

There are a two main ways of defining a box: using latitude, longitude, width and height (either degree or meter units), or with a geohash.

var box;

// box defined by lat, lon, width and height
box = geoBox.box(44.614163, -63.435301, 3000, 2000, "meters");
box = geoBox.box(44.614163, -63.435301, 0.0372433965, 0.0179664099, "degrees");

// box defined by either a base32 or integer geohash.
box = geoBox.box().fromGeohash("dxfvu3zb6");
box = geoBox.box().fromGeohash(1818436824900377, 52); // must specify bit depth with integer geohashes

Box Properties

Once you've defined your geo-box, you can then get or set any of its values. Related values will automatically be updated.

console.log(box.lat); // latitude value of box
console.log(box.lon); // longitude value of box
console.log(box.center); // center lat/lon of box

console.log(box.degWidth); // how wide the box is in degrees
console.log(box.degHeight); // how high the box is in degrees

console.log(box.width); // how wide the box is in meters
console.log(box.height); // how high the box is in meters
console.log(box.diagonal); // the trigonometric diagonal of the box
console.log(box.distortion); // the meter width/height distortion ratio of the box

API

geoBox.box(lat, lon, width, height, units);

Returns a new box object at the specified latitude and longitude.

If the units are set to degrees, when changing the latitude, the meter width (box.width) will adjust, and the box.degWidth will remain locked. If the units are set to meters, when changing the latitude of the box, the box.degWidth will adjust, and the meter width will remain locked.

box = geoBox.box(44.614163, -63.435301, 3000, 2000, "meters");
box = geoBox.box(44.614163, -63.435301, 0.0372433965, 0.0179664099, "degrees");

geoBox.box().fromGeohash(geohash, bitDepth);

Returns a new box object generated from a geohash.

Because geohases are actually just boxes, you can get the bounds of the box generated by the geohash. The box size and location will be deduced from the geohash value and bit depth. Large bit depth/more imprecise geohashes will have larger boxes.

Boxes generated using geohashes will have a default baseUnit of degrees.

If you are using an integer geohash, you must specify the bit depth of the geohash, otherwise the geohash will be decoded improperly.

box = geoBox.box().fromGeohash("dxfvu3zb6");
box = geoBox.box().fromGeohash(1818436824900377, 52);

Box Properties

box.lat

The latitude value of the west edge of the box.

If the base unit (box.baseUnit) of the box is degrees, changing the latitude will change the meter width of the box. If the base unit is meters, then the degWidth property of the box will change.

box.lon

The longitude value of the south edge of the box.

box.center

The center latitude and longitude point within the box, taking account the degree width and degree height. Return value is an array.

Can be set, and will automatically update box.lat, box.lon.

box.degWidth

The number of longitudinal degrees the box spans. Can be set, and will automatically adjust box.width and box.center.

box.degHeight

The number of latitudinal degrees the box spans. Can be set and will automatically adjust box.height and box.center.

box.width

The number of meters the box spans east to west. Can be set and will automatically adjust box.degWidth and box.center.

box.height

The number of meters the box spans north to south. Can be set and will automatically adjust box.height and box.center.

box.diagonal

A convenience property to get the diagonal distance from the southwest to the northeast corner of the box in meters.

box.distortion

The width/height box distortion ratio of the box's meter values. Taller, skinnier boxes will have a lower number, wider boxes will have a higher number. Perfectly square boxes (in meters) will have a value of 1.

box.latitudinalDegreeDistortion

The per degree height/width difference of the box. As latitude increases this number gets bigger. As the box's latitude gets closer to the equator the value approaches 1.

License

The MIT License (MIT)

Copyright (c) 2014 Arjun Mehta

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.