cheap-ruler - npm Package Compare versions

Comparing version 2.4.1 to 2.5.0

bench/bench-distance.js

@@ -23,3 +23,3 @@ 'use strict';
         for (var i = 0; i < lines.length; i++) {
-            var sum = 0;
+            var sum = 0; // eslint-disable-line
             for (var j = 0; j < lines[i].length - 1; j++) {
@@ -26,0 +26,0 @@ var p1 = lines[i][j];

cheap-ruler.js

@@ -6,2 +6,12 @@ (function(f){if(typeof exports==="object"&&typeof module!=="undefined"){module.exports=f()}else if(typeof define==="function"&&define.amd){define([],f)}else{var g;if(typeof window!=="undefined"){g=window}else if(typeof global!=="undefined"){g=global}else if(typeof self!=="undefined"){g=self}else{g=this}g.cheapRuler = f()}})(function(){var define,module,exports;return (function e(t,n,r){function s(o,u){if(!n[o]){if(!t[o]){var a=typeof require=="function"&&require;if(!u&&a)return a(o,!0);if(i)return i(o,!0);var f=new Error("Cannot find module '"+o+"'");throw f.code="MODULE_NOT_FOUND",f}var l=n[o]={exports:{}};t[o][0].call(l.exports,function(e){var n=t[o][1][e];return s(n?n:e)},l,l.exports,e,t,n,r)}return n[o].exports}var i=typeof require=="function"&&require;for(var o=0;o<r.length;o++)s(r[o]);return s})({1:[function(require,module,exports){
 
+/**
+ * A collection of very fast approximations to common geodesic measurements. Useful for performance-sensitive code that measures things on a city scale.
+ *
+ * @param {number} lat latitude
+ * @param {string} [units='kilometers']
+ * @returns {CheapRuler}
+ * @example
+ * var ruler = cheapRuler(35.05, 'miles');
+ * //=ruler
+ */
 function cheapRuler(lat /*: number */, units /*: ?string */) {
@@ -11,3 +21,9 @@ return new CheapRuler(lat, units);
 
-// unit multipliers for conversion from kilometers
+/**
+ * Multipliers for converting between units.
+ *
+ * @example
+ * // convert 50 meters to yards
+ * 50 * cheapRuler.units.yards / cheapRuler.units.meters;
+ */
 var factors = cheapRuler.units = {
@@ -24,2 +40,13 @@ kilometers: 1,
 
+/**
+ * Creates a ruler object from tile coordinates (y and z). Convenient in tile-reduce scripts.
+ *
+ * @param {number} y
+ * @param {number} z
+ * @param {string} [units='kilometers']
+ * @returns {CheapRuler}
+ * @example
+ * var ruler = cheapRuler.fromTile(1567, 12);
+ * //=ruler
+ */
 cheapRuler.fromTile = function (y, z, units) {
@@ -43,7 +70,18 @@ var n = Math.PI * (1 - 2 * (y + 0.5) / Math.pow(2, z));
 
-    this.kx = m * (111.41513 * cos - 0.09455 * cos3 + 0.00012 * cos5); // longitude correction
-    this.ky = m * (111.13209 - 0.56605 * cos2 + 0.0012 * cos4);        // latitude correction
+    // multipliers for converting longitude and latitude degrees into distance (http://1.usa.gov/1Wb1bv7)
+    this.kx = m * (111.41513 * cos - 0.09455 * cos3 + 0.00012 * cos5);
+    this.ky = m * (111.13209 - 0.56605 * cos2 + 0.0012 * cos4);
 }
 
 CheapRuler.prototype = {
+    /**
+     * Given two points of the form [longitude, latitude], returns the distance.
+     *
+     * @param {Array<number>} a point [longitude, latitude]
+     * @param {Array<number>} b point [longitude, latitude]
+     * @returns {number} distance
+     * @example
+     * var distance = ruler.distance([30.5, 50.5], [30.51, 50.49]);
+     * //=distance
+     */
     distance: function (a, b) {
@@ -55,2 +93,12 @@ var dx = (a[0] - b[0]) * this.kx;
 
+    /**
+     * Returns the bearing between two points in angles.
+     *
+     * @param {Array<number>} a point [longitude, latitude]
+     * @param {Array<number>} b point [longitude, latitude]
+     * @returns {number} bearing
+     * @example
+     * var bearing = ruler.bearing([30.5, 50.5], [30.51, 50.49]);
+     * //=bearing
+     */
     bearing: function (a, b) {
@@ -65,10 +113,50 @@ var dx = (b[0] - a[0]) * this.kx;
 
+    /**
+     * Returns a new point given distance and bearing from the starting point.
+     *
+     * @param {Array<number>} p point [longitude, latitude]
+     * @param {number} dist distance
+     * @param {number} bearing
+     * @returns {Array<number>} point [longitude, latitude]
+     * @example
+     * var point = ruler.destination([30.5, 50.5], 0.1, 90);
+     * //=point
+     */
     destination: function (p, dist, bearing) {
         var a = (90 - bearing) * Math.PI / 180;
+        return this.offset(p,
+            Math.cos(a) * dist,
+            Math.sin(a) * dist);
+    },
+
+    /**
+     * Returns a new point given easting and northing offsets (in ruler units) from the starting point.
+     *
+     * @param {Array<number>} p point [longitude, latitude]
+     * @param {number} dx easting
+     * @param {number} dy northing
+     * @returns {Array<number>} point [longitude, latitude]
+     * @example
+     * var point = ruler.offset([30.5, 50.5], 10, 10);
+     * //=point
+     */
+    offset: function (p, dx, dy) {
         return [
-            p[0] + Math.cos(a) * dist / this.kx,
-            p[1] + Math.sin(a) * dist / this.ky
+            p[0] + dx / this.kx,
+            p[1] + dy / this.ky
         ];
     },
 
+    /**
+     * Given a line (an array of points), returns the total line distance.
+     *
+     * @param {Array<Array<number>>} points [longitude, latitude]
+     * @returns {number} total line distance
+     * @example
+     * var length = ruler.lineDistance([
+     *     [-67.031, 50.458], [-67.031, 50.534],
+     *     [-66.929, 50.534], [-66.929, 50.458]
+     * ]);
+     * //=length
+     */
     lineDistance: function (points) {
@@ -82,2 +170,14 @@ var total = 0;
 
+    /**
+     * Given a polygon (an array of rings, where each ring is an array of points), returns the area.
+     *
+     * @param {Array<Array<Array<number>>>} polygon
+     * @returns {number} area value in the specified units (square kilometers by default)
+     * @example
+     * var area = ruler.area([[
+     *     [-67.031, 50.458], [-67.031, 50.534], [-66.929, 50.534],
+     *     [-66.929, 50.458], [-67.031, 50.458]
+     * ]]);
+     * //=area
+     */
     area: function (polygon) {
@@ -97,2 +197,12 @@ var sum = 0;
 
+    /**
+     * Returns the point at a specified distance along the line.
+     *
+     * @param {Array<Array<number>>} line
+     * @param {number} dist distance
+     * @returns {Array<number>} point [longitude, latitude]
+     * @example
+     * var point = ruler.along(line, 2.5);
+     * //=point
+     */
     along: function (line, dist) {
@@ -114,2 +224,13 @@ var sum = 0;
 
+    /**
+     * 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.
+     *
+     * @pointOnLine
+     * @param {Array<Array<number>>} line
+     * @param {Array<number>} p point [longitude, latitude]
+     * @returns {Object} {point, index}
+     * @example
+     * var point = ruler.pointOnLine(line, [-67.04, 50.5]).point;
+     * //=point
+     */
     pointOnLine: function (line, p) {
@@ -160,2 +281,13 @@ var minDist = Infinity;
 
+    /**
+     * Returns a part of the given line between the start and the stop points (or their closest points on the line).
+     *
+     * @param {Array<number>} start point [longitude, latitude]
+     * @param {Array<number>} stop point [longitude, latitude]
+     * @param {Array<Array<number>>} line
+     * @returns {Array<Array<number>>} line part of a line
+     * @example
+     * var line2 = ruler.lineSlice([-67.04, 50.5], [-67.05, 50.56], line1);
+     * //=line2
+     */
     lineSlice: function (start, stop, line) {
@@ -189,2 +321,13 @@ var p1 = this.pointOnLine(line, start);
 
+    /**
+     * Returns a part of the given line between the start and the stop points indicated by distance along the line.
+     *
+     * @param {number} start distance
+     * @param {number} stop distance
+     * @param {Array<Array<number>>} line
+     * @returns {Array<Array<number>>} line part of a line
+     * @example
+     * var line2 = ruler.lineSliceAlong(10, 20, line1);
+     * //=line2
+     */
     lineSliceAlong: function (start, stop, line) {
@@ -216,2 +359,12 @@ var sum = 0;
 
+    /**
+     * Given a point, returns a bounding box object ([w, s, e, n]) created from the given point buffered by a given distance.
+     *
+     * @param {Array<number>} p point [longitude, latitude]
+     * @param {number} buffer
+     * @returns {Array<number>} box object ([w, s, e, n])
+     * @example
+     * var bbox = ruler.bufferPoint([30.5, 50.5], 0.01);
+     * //=bbox
+     */
     bufferPoint: function (p, buffer) {
@@ -228,2 +381,12 @@ var v = buffer / this.ky;
 
+    /**
+     * Given a bounding box, returns the box buffered by a given distance.
+     *
+     * @param {Array<number>} box object ([w, s, e, n])
+     * @param {number} buffer
+     * @returns {Array<number>} box object ([w, s, e, n])
+     * @example
+     * var bbox = ruler.bufferBBox([30.5, 50.5, 31, 51], 0.2);
+     * //=bbox
+     */
     bufferBBox: function (bbox, buffer) {
@@ -240,2 +403,12 @@ var v = buffer / this.ky;
 
+    /**
+     * Returns true if the given point is inside in the given bounding box, otherwise false.
+     *
+     * @param {Array<number>} p point [longitude, latitude]
+     * @param {Array<number>} box object ([w, s, e, n])
+     * @returns {boolean}
+     * @example
+     * var inside = ruler.insideBBox([30.5, 50.5], [30, 50, 31, 51]);
+     * //=inside
+     */
     insideBBox: function (p, bbox) {
@@ -242,0 +415,0 @@ return p[0] >= bbox[0] &&

index.js

@@ -5,2 +5,12 @@ 'use strict'; /* @flow */
 
+/**
+ * A collection of very fast approximations to common geodesic measurements. Useful for performance-sensitive code that measures things on a city scale.
+ *
+ * @param {number} lat latitude
+ * @param {string} [units='kilometers']
+ * @returns {CheapRuler}
+ * @example
+ * var ruler = cheapRuler(35.05, 'miles');
+ * //=ruler
+ */
 function cheapRuler(lat /*: number */, units /*: ?string */) {
@@ -10,3 +20,9 @@ return new CheapRuler(lat, units);
 
-// unit multipliers for conversion from kilometers
+/**
+ * Multipliers for converting between units.
+ *
+ * @example
+ * // convert 50 meters to yards
+ * 50 * cheapRuler.units.yards / cheapRuler.units.meters;
+ */
 var factors = cheapRuler.units = {
@@ -23,2 +39,13 @@ kilometers: 1,
 
+/**
+ * Creates a ruler object from tile coordinates (y and z). Convenient in tile-reduce scripts.
+ *
+ * @param {number} y
+ * @param {number} z
+ * @param {string} [units='kilometers']
+ * @returns {CheapRuler}
+ * @example
+ * var ruler = cheapRuler.fromTile(1567, 12);
+ * //=ruler
+ */
 cheapRuler.fromTile = function (y, z, units) {
@@ -42,7 +69,18 @@ var n = Math.PI * (1 - 2 * (y + 0.5) / Math.pow(2, z));
 
-    this.kx = m * (111.41513 * cos - 0.09455 * cos3 + 0.00012 * cos5); // longitude correction
-    this.ky = m * (111.13209 - 0.56605 * cos2 + 0.0012 * cos4);        // latitude correction
+    // multipliers for converting longitude and latitude degrees into distance (http://1.usa.gov/1Wb1bv7)
+    this.kx = m * (111.41513 * cos - 0.09455 * cos3 + 0.00012 * cos5);
+    this.ky = m * (111.13209 - 0.56605 * cos2 + 0.0012 * cos4);
 }
 
 CheapRuler.prototype = {
+    /**
+     * Given two points of the form [longitude, latitude], returns the distance.
+     *
+     * @param {Array<number>} a point [longitude, latitude]
+     * @param {Array<number>} b point [longitude, latitude]
+     * @returns {number} distance
+     * @example
+     * var distance = ruler.distance([30.5, 50.5], [30.51, 50.49]);
+     * //=distance
+     */
     distance: function (a, b) {
@@ -54,2 +92,12 @@ var dx = (a[0] - b[0]) * this.kx;
 
+    /**
+     * Returns the bearing between two points in angles.
+     *
+     * @param {Array<number>} a point [longitude, latitude]
+     * @param {Array<number>} b point [longitude, latitude]
+     * @returns {number} bearing
+     * @example
+     * var bearing = ruler.bearing([30.5, 50.5], [30.51, 50.49]);
+     * //=bearing
+     */
     bearing: function (a, b) {
@@ -64,10 +112,50 @@ var dx = (b[0] - a[0]) * this.kx;
 
+    /**
+     * Returns a new point given distance and bearing from the starting point.
+     *
+     * @param {Array<number>} p point [longitude, latitude]
+     * @param {number} dist distance
+     * @param {number} bearing
+     * @returns {Array<number>} point [longitude, latitude]
+     * @example
+     * var point = ruler.destination([30.5, 50.5], 0.1, 90);
+     * //=point
+     */
     destination: function (p, dist, bearing) {
         var a = (90 - bearing) * Math.PI / 180;
+        return this.offset(p,
+            Math.cos(a) * dist,
+            Math.sin(a) * dist);
+    },
+
+    /**
+     * Returns a new point given easting and northing offsets (in ruler units) from the starting point.
+     *
+     * @param {Array<number>} p point [longitude, latitude]
+     * @param {number} dx easting
+     * @param {number} dy northing
+     * @returns {Array<number>} point [longitude, latitude]
+     * @example
+     * var point = ruler.offset([30.5, 50.5], 10, 10);
+     * //=point
+     */
+    offset: function (p, dx, dy) {
         return [
-            p[0] + Math.cos(a) * dist / this.kx,
-            p[1] + Math.sin(a) * dist / this.ky
+            p[0] + dx / this.kx,
+            p[1] + dy / this.ky
         ];
     },
 
+    /**
+     * Given a line (an array of points), returns the total line distance.
+     *
+     * @param {Array<Array<number>>} points [longitude, latitude]
+     * @returns {number} total line distance
+     * @example
+     * var length = ruler.lineDistance([
+     *     [-67.031, 50.458], [-67.031, 50.534],
+     *     [-66.929, 50.534], [-66.929, 50.458]
+     * ]);
+     * //=length
+     */
     lineDistance: function (points) {
@@ -81,2 +169,14 @@ var total = 0;
 
+    /**
+     * Given a polygon (an array of rings, where each ring is an array of points), returns the area.
+     *
+     * @param {Array<Array<Array<number>>>} polygon
+     * @returns {number} area value in the specified units (square kilometers by default)
+     * @example
+     * var area = ruler.area([[
+     *     [-67.031, 50.458], [-67.031, 50.534], [-66.929, 50.534],
+     *     [-66.929, 50.458], [-67.031, 50.458]
+     * ]]);
+     * //=area
+     */
     area: function (polygon) {
@@ -96,2 +196,12 @@ var sum = 0;
 
+    /**
+     * Returns the point at a specified distance along the line.
+     *
+     * @param {Array<Array<number>>} line
+     * @param {number} dist distance
+     * @returns {Array<number>} point [longitude, latitude]
+     * @example
+     * var point = ruler.along(line, 2.5);
+     * //=point
+     */
     along: function (line, dist) {
@@ -113,2 +223,13 @@ var sum = 0;
 
+    /**
+     * 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.
+     *
+     * @pointOnLine
+     * @param {Array<Array<number>>} line
+     * @param {Array<number>} p point [longitude, latitude]
+     * @returns {Object} {point, index}
+     * @example
+     * var point = ruler.pointOnLine(line, [-67.04, 50.5]).point;
+     * //=point
+     */
     pointOnLine: function (line, p) {
@@ -159,2 +280,13 @@ var minDist = Infinity;
 
+    /**
+     * Returns a part of the given line between the start and the stop points (or their closest points on the line).
+     *
+     * @param {Array<number>} start point [longitude, latitude]
+     * @param {Array<number>} stop point [longitude, latitude]
+     * @param {Array<Array<number>>} line
+     * @returns {Array<Array<number>>} line part of a line
+     * @example
+     * var line2 = ruler.lineSlice([-67.04, 50.5], [-67.05, 50.56], line1);
+     * //=line2
+     */
     lineSlice: function (start, stop, line) {
@@ -188,2 +320,13 @@ var p1 = this.pointOnLine(line, start);
 
+    /**
+     * Returns a part of the given line between the start and the stop points indicated by distance along the line.
+     *
+     * @param {number} start distance
+     * @param {number} stop distance
+     * @param {Array<Array<number>>} line
+     * @returns {Array<Array<number>>} line part of a line
+     * @example
+     * var line2 = ruler.lineSliceAlong(10, 20, line1);
+     * //=line2
+     */
     lineSliceAlong: function (start, stop, line) {
@@ -215,2 +358,12 @@ var sum = 0;
 
+    /**
+     * Given a point, returns a bounding box object ([w, s, e, n]) created from the given point buffered by a given distance.
+     *
+     * @param {Array<number>} p point [longitude, latitude]
+     * @param {number} buffer
+     * @returns {Array<number>} box object ([w, s, e, n])
+     * @example
+     * var bbox = ruler.bufferPoint([30.5, 50.5], 0.01);
+     * //=bbox
+     */
     bufferPoint: function (p, buffer) {
@@ -227,2 +380,12 @@ var v = buffer / this.ky;
 
+    /**
+     * Given a bounding box, returns the box buffered by a given distance.
+     *
+     * @param {Array<number>} box object ([w, s, e, n])
+     * @param {number} buffer
+     * @returns {Array<number>} box object ([w, s, e, n])
+     * @example
+     * var bbox = ruler.bufferBBox([30.5, 50.5, 31, 51], 0.2);
+     * //=bbox
+     */
     bufferBBox: function (bbox, buffer) {
@@ -239,2 +402,12 @@ var v = buffer / this.ky;
 
+    /**
+     * Returns true if the given point is inside in the given bounding box, otherwise false.
+     *
+     * @param {Array<number>} p point [longitude, latitude]
+     * @param {Array<number>} box object ([w, s, e, n])
+     * @returns {boolean}
+     * @example
+     * var inside = ruler.insideBBox([30.5, 50.5], [30, 50, 31, 51]);
+     * //=inside
+     */
     insideBBox: function (p, bbox) {
@@ -241,0 +414,0 @@ return p[0] >= bbox[0] &&

package.json

 {
   "name": "cheap-ruler",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "description": "A collection of fast approximations to common geographic measurements.",
   "main": "index.js",
+  "types": "index.d.ts",
   "dependencies": {},
   "devDependencies": {
-    "benchmark": "^2.1.0",
-    "browserify": "^13.0.0",
-    "eslint": "^2.7.0",
+    "benchmark": "^2.1.3",
+    "browserify": "^14.1.0",
+    "eslint": "^3.17.0",
     "eslint-config-mourner": "^2.0.1",
-    "istanbul": "^0.4.3",
-    "tape": "^4.5.1",
-    "turf": "^2.0.2"
+    "istanbul": "^0.4.5",
+    "node-vincenty": "0.0.6",
+    "tape": "^4.6.3",
+    "@turf/turf": "^3.12.2",
+    "typescript": "^2.2.1"
   },
   "scripts": {
-    "pretest": "eslint index.js bench test/test.js",
+    "pretest": "eslint index.js bench test/*.js && npm run types",
     "test": "tape test/test.js",
+    "types": "tsc test/types.ts && rm test/types.js",
     "build": "browserify index.js -s cheapRuler > cheap-ruler.js",
@@ -20,0 +24,0 @@ "prepublish": "npm run build",

README.md

@@ -193,3 +193,3 @@ # cheap-ruler [![Build Status](https://travis-ci.org/mapbox/cheap-ruler.svg?branch=master)](https://travis-ci.org/mapbox/cheap-ruler) [![](https://img.shields.io/badge/simply-awesome-brightgreen.svg)](https://github.com/mourner/projects)
 - NPM: `npm install cheap-ruler`
-- Browser build (CDN): https://npmcdn.com/cheap-ruler@1.3.0/cheap-ruler.js
+- Browser build (CDN): https://unpkg.com/cheap-ruler@2.4.1/cheap-ruler.js
 
@@ -196,0 +196,0 @@ ## Precision

test/test.js

@@ -5,3 +5,3 @@ 'use strict';
 var createRuler = require('../');
-var turf = require('turf');
+var turf = require('@turf/turf');
 var lines = require('./fixtures/lines.json');
@@ -69,3 +69,3 @@ var points = Array.prototype.concat.apply([], lines);
     for (var i = 0; i < lines.length; i++) {
-        var expected = turf.lineDistance(turf.linestring(lines[i]));
+        var expected = turf.lineDistance(turf.lineString(lines[i]));
         var actual = ruler.lineDistance(lines[i]);
@@ -92,3 +92,3 @@ assertErr(t, expected, actual, 0.003, 'lineDistance');
     for (var i = 0; i < lines.length; i++) {
-        var line = turf.linestring(lines[i]);
+        var line = turf.lineString(lines[i]);
         var dist = turf.lineDistance(line) / 2;
@@ -124,4 +124,2 @@ var expected = turf.along(line, dist, 'kilometers').geometry.coordinates;
     for (var i = 0; i < lines.length; i++) {
-        if (i === 46) continue; // skip due to Turf bug https://github.com/Turfjs/turf/issues/351
-
         var line = lines[i];
@@ -133,9 +131,9 @@ var dist = ruler.lineDistance(line);
         var expected = ruler.lineDistance(turf.lineSlice(
-            turf.point(start), turf.point(stop), turf.linestring(line)).geometry.coordinates);
+            turf.point(start), turf.point(stop), turf.lineString(line)).geometry.coordinates);
 
         var actual = ruler.lineDistance(ruler.lineSlice(start, stop, line));
 
-        assertErr(t, expected, actual, 0, 'lineSlice length');
+        assertErr(t, expected, actual, 1e-5, 'lineSlice length');
     }
-    t.pass('lineSlice length the same');
+    t.pass('lineSlice length within 1e-5');
     t.end();
@@ -154,8 +152,8 @@ });
         var expected = ruler.lineDistance(turf.lineSlice(
-            turf.point(start), turf.point(stop), turf.linestring(line)).geometry.coordinates);
+            turf.point(start), turf.point(stop), turf.lineString(line)).geometry.coordinates);
         var actual = ruler.lineDistance(ruler.lineSliceAlong(dist * 0.3, dist * 0.7, line));
 
-        assertErr(t, expected, actual, 1e-10, 'lineSliceAlong length');
+        assertErr(t, expected, actual, 1e-5, 'lineSliceAlong length');
     }
-    t.pass('lineSliceAlong length within 1e-10');
+    t.pass('lineSliceAlong length within 1e-5');
     t.end();
@@ -162,0 +160,0 @@ });

No alert changes

Improved metrics

Total package byte prevSize

186004

increased by109.21%

Number of package files

26

increased by8.33%

Lines of code

1262

increased by46.06%

Worsened metrics

Dev dependency count

9

increased by28.57%

No dependency changes