cheap-ruler

What is cheap-ruler?

The cheap-ruler npm package provides fast and accurate approximations for common geospatial calculations. It is designed to be efficient and lightweight, making it suitable for applications that require quick distance and area calculations, point projections, and bounding box manipulations.

What are cheap-ruler's main functionalities?

Distance Calculation

Calculates the distance between two points. The example calculates the distance in miles between two coordinates.

const CheapRuler = require('cheap-ruler');
const ruler = new CheapRuler(35.05, 'miles');
const distance = ruler.distance([30.5, 50.5], [30.51, 50.49]);
console.log(distance);

Area Calculation

Calculates the area of a polygon. The example calculates the area in square miles of a polygon defined by a set of coordinates.

const CheapRuler = require('cheap-ruler');
const ruler = new CheapRuler(35.05, 'miles');
const area = ruler.area([[30.5, 50.5], [30.51, 50.49], [30.52, 50.48], [30.5, 50.5]]);
console.log(area);

Point Projection

Projects a point to a new location given a distance and bearing. The example projects a point 10 miles to the east (90 degrees) from the original point.

const CheapRuler = require('cheap-ruler');
const ruler = new CheapRuler(35.05, 'miles');
const point = ruler.destination([30.5, 50.5], 10, 90);
console.log(point);

Bounding Box Calculation

Calculates a bounding box around a point given a buffer distance. The example calculates a bounding box 10 miles around the given point.

const CheapRuler = require('cheap-ruler');
const ruler = new CheapRuler(35.05, 'miles');
const bbox = ruler.bufferBBox([30.5, 50.5], 10);
console.log(bbox);

Other packages similar to cheap-ruler

turf

Turf is a comprehensive geospatial analysis library for JavaScript. It provides a wide range of geospatial functions, including distance and area calculations, point projections, and more. Compared to cheap-ruler, Turf offers more extensive functionality but may be less performant for simple tasks.

geolib

Geolib is a library for geospatial calculations in JavaScript. It includes functions for distance and area calculations, point projections, and more. Geolib is similar to cheap-ruler in terms of functionality but may not be as optimized for performance.

geodesy

Geodesy is a library for geodesic calculations in JavaScript. It provides tools for distance and area calculations, point projections, and more. Geodesy focuses on high-precision calculations, which may be more accurate but slower compared to cheap-ruler.

README

cheap-ruler

A collection of fast approximations to common geographic measurements, along with some utility functions. Useful for speeding up analysis scripts when measuring things on a city scale, replacing Turf calls in key places.

For distances under a hundred miles and not on the poles, the results are typically within 0.1% of corresponding Turf functions.

Performance

Compared to corresponding Turf methods (using Node v5.10):

• distance: ~26x faster
• bearing: ~3.5x faster
• destination: ~6.4x faster
• lineDistance: ~26x faster
• area: ~3.6x faster
• along: ~21x faster
• pointOnLine: ~72x faster
• lineSlice: ~56x faster

Additional utility methods:

• lineSliceAlong: ~268x faster than turf.lineSlice(turf.along(...
• bufferPoint: ~210x faster than creating a bounding box with two diagonal turf.destination calls
• bufferBBox: ~210x faster (likewise)
• insideBBox: ~24x faster than turf.inside(turf.point(p), turf.bboxPolygon(bbox))

Usage

var ruler = cheapRuler(35.05, 'miles');

var distance = ruler.distance([30.51, 50.32], [30.52, 50.312]);
var lineLength = ruler.lineDistance(line.geometry.coordinates);
var bbox = ruler.bufferPoint([30.5, 50.5], 0.01);

Note: to get the full performance benefit, create the ruler object once per an area of calculation (such as a tile), and then reuse it as much as possible.

Creating a ruler object

cheapRuler(latitude[, units])

Creates a ruler object that will approximate measurements around the given latitude. Units are either kilometers (default) or miles.

cheapRuler.fromTile(y, z[, units])

Creates a ruler object from tile coordinates (y and z). Convenient in tile-reduce scripts.

var ruler = cheapRuler.fromTile(1567, 12);

Ruler methods

distance(a, b)

Given two points of the form [longitude, latitude], returns the distance.

var distance = ruler.distance([30.5, 50.5], [30.51, 50.49]);

bearing(a, b)

Returns the bearing between two points in angles.

var bearing = ruler.bearing([30.5, 50.5], [30.51, 50.49]);

destination(p, dist, bearing)

Returns a new point given distance and bearing from the starting point.

var point = ruler.destination([30.5, 50.5], 0.1, 90);

lineDistance(line)

Given a line (an array of points), returns the total line distance.

var length = ruler.lineDistance([
    [-67.031, 50.458], [-67.031, 50.534],
    [-66.929, 50.534], [-66.929, 50.458]
]);

area(polygon)

Given a polygon (an array of rings, where each ring is an array of points), returns the area. Note that it returns the value in the specified units (square kilometers by default) rather than square meters as in turf.area.

var area = ruler.area([[
    [-67.031, 50.458], [-67.031, 50.534], [-66.929, 50.534],
    [-66.929, 50.458], [-67.031, 50.458]
]]);

along(line, dist)

Returns the point at a specified distance along the line.

var point = ruler.along(line, 2.5);

pointOnLine(line, p)

Returns an object of the form {point, index} where point is closest point on the line from the given point, and index is the start index of the segment with the closest point.

var point = ruler.pointOnLine(line, [-67.04, 50.5]).point;

lineSlice(start, stop, line)

Returns a part of the given line between the start and the stop points (or their closest points on the line).

ruler.lineSlice([-67.04, 50.5], [-67.05, 50.56], line);

lineSliceAlong(startDist, stopDist, line)

Returns a part of the given line between the start and the stop points indicated by distance along the line.

ruler.lineSliceAlong(10, 20, line);

bufferPoint(p, buffer)

Given a point, returns a bounding box object ([w, s, e, n]) created from the given point buffered by a given distance.

var bbox = ruler.bufferPoint([30.5, 50.5], 0.01);

bufferBBox(bbox, buffer)

Given a bounding box, returns the box buffered by a given distance.

var bbox = ruler.bufferBBox([30.5, 50.5, 31, 51], 0.2);

insideBBox(p, bbox)

Returns true if the given point is inside in the given bounding box, otherwise false.

var inside = ruler.insideBBox([30.5, 50.5], [30, 50, 31, 51]);

Install

• NPM: npm install cheap-ruler
• Browser build (CDN): https://npmcdn.com/cheap-ruler@1.3.0/cheap-ruler.js

Precision

A table that shows the margin of error for ruler.distance compared to turf.distance:

lat	0°	10°	20°	30°	40°	50°	60°	70°	80°
1km	0.08%	0.08%	0.08%	0.08%	0.08%	0.08%	0.08%	0.08%	0.08%
100km	0.08%	0.08%	0.08%	0.08%	0.08%	0.08%	0.08%	0.09%	0.11%
1000km	0.11%	0.11%	0.12%	0.14%	0.18%	0.25%	0.42%	0.89%	3.48%

The same table for a much more precise Vincenty distance formula (using node-vincenty module):

lat	0°	10°	20°	30°	40°	50°	60°	70°	80°
1km	0.34%	0.32%	0.26%	0.17%	0.06%	0.06%	0.17%	0.26%	0.31%
100km	0.34%	0.32%	0.26%	0.17%	0.06%	0.06%	0.16%	0.25%	0.28%
1000km	0.36%	0.34%	0.3%	0.23%	0.16%	0.11%	0.17%	0.55%	3.08%

Errors for all other methods are similar.