Rhumb line modules (#728)

* added turf-rhumb-destination * added rhum-distance module; removed distance test in rhumb-destination (requires rhumb-distance) * update package and bench on rhumb-distance and rhumb-destination * added turf-rhumb-bearing * added validation tests to rhumb-distance and rhumb-destination * fixed linting errors * Update package.json module names * Compact test results @turf/rhumb-distance * Add more test cases in @turf/rhumb-destination * Update Benchmark to ES6 syntax * Remove entire switch statement @turf/rhumb-destination * Remove entire switch statement @turf/rhumb-distance * Update JSDocs * Update typescript definitions * Update JSDocs for other bearing/distance/destination modules * Remove JSDocs extra comment in example * added note on failing rhumb-distance test
Turfjs · May 11, 2017 · dc48afe · dc48afe
1 parent 1764837
commit dc48afe
Show file tree

Hide file tree

Showing 45 changed files with 1,290 additions and 19 deletions.
diff --git a/packages/turf-bearing/README.md b/packages/turf-bearing/README.md
@@ -7,8 +7,8 @@ i.e. the angle measured in degrees from the north line (0 degrees)
 
 **Parameters**
 
--   `start` **[Feature](http://geojson.org/geojson-spec.html#feature-objects)&lt;[Point](http://geojson.org/geojson-spec.html#point)>** starting Point
--   `end` **[Feature](http://geojson.org/geojson-spec.html#feature-objects)&lt;[Point](http://geojson.org/geojson-spec.html#point)>** ending Point
+-   `start` **([Geometry](http://geojson.org/geojson-spec.html#geometry) \| [Feature](http://geojson.org/geojson-spec.html#feature-objects)&lt;[Point](http://geojson.org/geojson-spec.html#point)> | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)>)** starting Point
+-   `end` **([Geometry](http://geojson.org/geojson-spec.html#geometry) \| [Feature](http://geojson.org/geojson-spec.html#feature-objects)&lt;[Point](http://geojson.org/geojson-spec.html#point)> | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)>)** ending Point
 -   `final` **\[[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)]** calculates the final bearing if true (optional, default `false`)
 
 **Examples**

diff --git a/packages/turf-bearing/index.d.ts b/packages/turf-bearing/index.d.ts
@@ -1,10 +1,10 @@
 /// <reference types="geojson" />
 
-type Point = GeoJSON.Feature<GeoJSON.Point>;
+type Point = GeoJSON.Feature<GeoJSON.Point> | GeoJSON.Point | number[];
 
 /**
  * http://turfjs.org/docs/#bearing
  */
-declare function bearing(start: Point, end: Point): number;
+declare function bearing(start: Point, end: Point, final?: boolean): number;
 declare namespace bearing { }
 export = bearing;
diff --git a/packages/turf-bearing/index.js b/packages/turf-bearing/index.js
@@ -7,8 +7,8 @@ var getCoord = require('@turf/invariant').getCoord;
  * i.e. the angle measured in degrees from the north line (0 degrees)
  *
  * @name bearing
- * @param {Feature<Point>} start starting Point
- * @param {Feature<Point>} end ending Point
+ * @param {Geometry|Feature<Point>|Array<number>} start starting Point
+ * @param {Geometry|Feature<Point>|Array<number>} end ending Point
  * @param {boolean} [final=false] calculates the final bearing if true
  * @returns {number} bearing in decimal degrees, between -180 and 180 degrees (positive clockwise)
  * @example

diff --git a/packages/turf-destination/README.md b/packages/turf-destination/README.md
@@ -6,8 +6,8 @@ Takes a [Point](http://geojson.org/geojson-spec.html#point) and calculates the l
 
 **Parameters**
 
--   `from` **([Geometry](http://geojson.org/geojson-spec.html#geometry) \| [Feature](http://geojson.org/geojson-spec.html#feature-objects)&lt;[Point](http://geojson.org/geojson-spec.html#point)> | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)>)** starting point
--   `distance` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** distance from the starting point
+-   `origin` **([Geometry](http://geojson.org/geojson-spec.html#geometry) \| [Feature](http://geojson.org/geojson-spec.html#feature-objects)&lt;[Point](http://geojson.org/geojson-spec.html#point)> | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)>)** starting point
+-   `distance` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** distance from the origin point
 -   `bearing` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** ranging from -180 to 180
 -   `units` **\[[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** miles, kilometers, degrees, or radians (optional, default `kilometers`)
 

diff --git a/packages/turf-destination/index.d.ts b/packages/turf-destination/index.d.ts
@@ -1,10 +1,12 @@
 /// <reference types="geojson" />
 
+import {Units} from '@turf/helpers'
+
 type Point = GeoJSON.Feature<GeoJSON.Point> | GeoJSON.Point | number[];
 
 /**
  * http://turfjs.org/docs/#destination
  */
-declare function destination(from: Point, distance: number, bearing: number, units?: string): Point;
+declare function destination(origin: Point, distance: number, bearing: number, units?: Units): GeoJSON.Feature<GeoJSON.Point>;
 declare namespace destination { }
 export = destination;
diff --git a/packages/turf-destination/index.js b/packages/turf-destination/index.js
@@ -9,8 +9,8 @@ var distanceToRadians = helpers.distanceToRadians;
  * Takes a {@link Point} and calculates the location of a destination point given a distance in degrees, radians, miles, or kilometers; and bearing in degrees. This uses the [Haversine formula](http://en.wikipedia.org/wiki/Haversine_formula) to account for global curvature.
  *
  * @name destination
- * @param {Geometry|Feature<Point>|Array<number>} from starting point
- * @param {number} distance distance from the starting point
+ * @param {Geometry|Feature<Point>|Array<number>} origin starting point
+ * @param {number} distance distance from the origin point
  * @param {number} bearing ranging from -180 to 180
  * @param {string} [units=kilometers] miles, kilometers, degrees, or radians
  * @returns {Feature<Point>} destination point
@@ -34,10 +34,10 @@ var distanceToRadians = helpers.distanceToRadians;
  * point.properties['marker-color'] = '#0f0';
  * var addToMap = [point, destination]
  */
-module.exports = function (from, distance, bearing, units) {
+module.exports = function (origin, distance, bearing, units) {
     var degrees2radians = Math.PI / 180;
     var radians2degrees = 180 / Math.PI;
-    var coordinates1 = getCoord(from);
+    var coordinates1 = getCoord(origin);
     var longitude1 = degrees2radians * coordinates1[0];
     var latitude1 = degrees2radians * coordinates1[1];
     var bearing_rad = degrees2radians * bearing;

diff --git a/packages/turf-distance/README.md b/packages/turf-distance/README.md
@@ -9,8 +9,8 @@ to account for global curvature.
 
 **Parameters**
 
--   `from` **[Feature](http://geojson.org/geojson-spec.html#feature-objects)&lt;[Point](http://geojson.org/geojson-spec.html#point)>** origin point
--   `to` **[Feature](http://geojson.org/geojson-spec.html#feature-objects)&lt;[Point](http://geojson.org/geojson-spec.html#point)>** destination point
+-   `from` **([Geometry](http://geojson.org/geojson-spec.html#geometry) \| [Feature](http://geojson.org/geojson-spec.html#feature-objects)&lt;[Point](http://geojson.org/geojson-spec.html#point)> | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)>)** origin point
+-   `to` **([Geometry](http://geojson.org/geojson-spec.html#geometry) \| [Feature](http://geojson.org/geojson-spec.html#feature-objects)&lt;[Point](http://geojson.org/geojson-spec.html#point)> | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)>)** destination point
 -   `units` **\[[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** can be degrees, radians, miles, or kilometers (optional, default `kilometers`)
 
 **Examples**

diff --git a/packages/turf-distance/index.d.ts b/packages/turf-distance/index.d.ts
@@ -1,10 +1,12 @@
 /// <reference types="geojson" />
 
-type Point = GeoJSON.Feature<GeoJSON.Point>;
+import {Units} from '@turf/helpers'
+
+type Point = GeoJSON.Feature<GeoJSON.Point> | GeoJSON.Point | number[];
 
 /**
  * http://turfjs.org/docs/#distance
  */
-declare function distance(from: Point, to: Point, units?: string): number;
+declare function distance(from: Point, to: Point, units?: Units): number;
 declare namespace distance { }
 export = distance;
diff --git a/packages/turf-distance/index.js b/packages/turf-distance/index.js
@@ -10,8 +10,8 @@ var radiansToDistance = require('@turf/helpers').radiansToDistance;
  * to account for global curvature.
  *
  * @name distance
- * @param {Feature<Point>} from origin point
- * @param {Feature<Point>} to destination point
+ * @param {Geometry|Feature<Point>|Array<number>} from origin point
+ * @param {Geometry|Feature<Point>|Array<number>} to destination point
  * @param {string} [units=kilometers] can be degrees, radians, miles, or kilometers
  * @returns {number} distance between the two points
  * @example

diff --git a/packages/turf-rhumb-bearing/LICENSE b/packages/turf-rhumb-bearing/LICENSE
@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 TurfJS
+
+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.
diff --git a/packages/turf-rhumb-bearing/README.md b/packages/turf-rhumb-bearing/README.md
@@ -0,0 +1,71 @@
+# @turf/rhumb-bearing
+
+# rhumbBearing
+
+Takes two [points](http://geojson.org/geojson-spec.html#point) and finds the bearing angle between them along a Rhumb line
+i.e. the angle measured in degrees start the north line (0 degrees)
+
+**Parameters**
+
+-   `start` **([Geometry](http://geojson.org/geojson-spec.html#geometry) \| [Feature](http://geojson.org/geojson-spec.html#feature-objects)&lt;[Point](http://geojson.org/geojson-spec.html#point)> | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)>)** starting Point
+-   `end` **([Geometry](http://geojson.org/geojson-spec.html#geometry) \| [Feature](http://geojson.org/geojson-spec.html#feature-objects)&lt;[Point](http://geojson.org/geojson-spec.html#point)> | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)>)** ending Point
+-   `final` **\[[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)]** calculates the final bearing if true (optional, default `false`)
+
+**Examples**
+
+```javascript
+var point1 = {
+  "type": "Feature",
+  "properties": {
+    "marker-color": "#F00"
+  },
+  "geometry": {
+    "type": "Point",
+    "coordinates": [-75.343, 39.984]
+  }
+};
+var point2 = {
+  "type": "Feature",
+  "properties": {
+    "marker-color": "#00F"
+  },
+  "geometry": {
+    "type": "Point",
+    "coordinates": [-75.534, 39.123]
+  }
+};
+
+var bearing = turf.rhumbBearing(point1, point2);
+
+//addToMap
+point1.properties.bearing = bearing
+point2.properties.bearing = bearing
+var addToMap = [point1, point2]
+```
+
+Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** bearing from north in decimal degrees, between -180 and 180 degrees (positive clockwise)
+
+<!-- This file is automatically generated. Please don't edit it directly:
+if you find an error, edit the source file (likely index.js), and re-run
+./scripts/generate-readmes in the turf project. -->
+
+---
+
+This module is part of the [Turfjs project](http://turfjs.org/), an open source
+module collection dedicated to geographic algorithms. It is maintained in the
+[Turfjs/turf](https://github.com/Turfjs/turf) repository, where you can create
+PRs and issues.
+
+### Installation
+
+Install this module individually:
+
+```sh
+$ npm install @turf/rhumb-bearing
+```
+
+Or install the Turf module that includes it as a function:
+
+```sh
+$ npm install @turf/turf
+```
diff --git a/packages/turf-rhumb-bearing/bench.js b/packages/turf-rhumb-bearing/bench.js
@@ -0,0 +1,20 @@
+var {point} = require('@turf/helpers');
+var Benchmark = require('benchmark');
+var rhumbBearing = require('./');
+
+var start = point([-75.4, 39.4]);
+var end = point([-75.534, 39.123]);
+
+/**
+ * Benchmark Results
+ *
+ * initial bearing x 1,108,233 ops/sec ±3.22% (86 runs sampled)
+ * final bearing x 1,144,822 ops/sec ±2.01% (88 runs sampled)
+ */
+var suite = new Benchmark.Suite('turf-rhumb-bearing');
+suite
+    .add('initial bearing', () => rhumbBearing(start, end))
+    .add('final bearing', () => rhumbBearing(start, end, true))
+    .on('cycle', e => console.log(String(e.target)))
+    .on('complete', () => {})
+    .run();
diff --git a/packages/turf-rhumb-bearing/index.d.ts b/packages/turf-rhumb-bearing/index.d.ts
@@ -0,0 +1,10 @@
+/// <reference types="geojson" />
+
+type Point = GeoJSON.Feature<GeoJSON.Point> | GeoJSON.Point | number[];
+
+/**
+ * http://turfjs.org/docs/#rhumb-bearing
+ */
+declare function rhumbBearing(start: Point, end: Point, final?: boolean): number;
+declare namespace rhumbBearing { }
+export = rhumbBearing;
diff --git a/packages/turf-rhumb-bearing/index.js b/packages/turf-rhumb-bearing/index.js
@@ -0,0 +1,63 @@
+// https://en.wikipedia.org/wiki/Rhumb_line
+// http://www.movable-type.co.uk/scripts/latlong.html#rhumblines
+var getCoord = require('@turf/invariant').getCoord;
+var GeodesyLatLon = require('geodesy').LatLonSpherical;
+
+/**
+ * Takes two {@link Point|points} and finds the bearing angle between them along a Rhumb line
+ * i.e. the angle measured in degrees start the north line (0 degrees)
+ *
+ * @name rhumbBearing
+ * @param {Geometry|Feature<Point>|Array<number>} start starting Point
+ * @param {Geometry|Feature<Point>|Array<number>} end ending Point
+ * @param {boolean} [final=false] calculates the final bearing if true
+ * @returns {number} bearing from north in decimal degrees, between -180 and 180 degrees (positive clockwise)
+ * @example
+ * var point1 = {
+ *   "type": "Feature",
+ *   "properties": {
+ *     "marker-color": "#F00"
+ *   },
+ *   "geometry": {
+ *     "type": "Point",
+ *     "coordinates": [-75.343, 39.984]
+ *   }
+ * };
+ * var point2 = {
+ *   "type": "Feature",
+ *   "properties": {
+ *     "marker-color": "#00F"
+ *   },
+ *   "geometry": {
+ *     "type": "Point",
+ *     "coordinates": [-75.534, 39.123]
+ *   }
+ * };
+ *
+ * var bearing = turf.rhumbBearing(point1, point2);
+ *
+ * //addToMap
+ * point1.properties.bearing = bearing
+ * point2.properties.bearing = bearing
+ * var addToMap = [point1, point2]
+ */
+module.exports = function (start, end, final) {
+    // validation
+    if (!start) throw new Error('start point is required');
+    if (!end) throw new Error('end point is required');
+
+    var coordsStart = getCoord(start);
+    var coordsEnd = getCoord(end);
+    var origin = new GeodesyLatLon(coordsStart[1], coordsStart[0]);
+    var destination = new GeodesyLatLon(coordsEnd[1], coordsEnd[0]);
+    var bear360;
+    if (final) {
+        bear360 = destination.rhumbBearingTo(origin);
+    } else {
+        bear360 = origin.rhumbBearingTo(destination);
+    }
+
+    var bear180 = (bear360 > 180) ? -(360 - bear360) : bear360;
+
+    return bear180;
+};
diff --git a/packages/turf-rhumb-bearing/package.json b/packages/turf-rhumb-bearing/package.json
@@ -0,0 +1,47 @@
+{
+  "name": "@turf/rhumb-bearing",
+  "version": "4.0.0",
+  "description": "turf rhumb-bearing module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts"
+  ],
+  "scripts": {
+    "test": "node test.js",
+    "bench": "node bench.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/Turfjs/turf.git"
+  },
+  "keywords": [
+    "turf",
+    "bearing",
+    "loxodrome",
+    "rhumb",
+    "rhumb line"
+  ],
+  "author": "Turf Authors",
+  "contributors": [
+    "Stefano Borghi <@stebogit>",
+    "Denis Carriere <@DenisCarriere>"
+  ],
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Turfjs/turf/issues"
+  },
+  "homepage": "https://github.com/Turfjs/turf",
+  "devDependencies": {
+    "@turf/destination": "^4.2.0",
+    "@turf/helpers": "^4.2.0",
+    "benchmark": "^2.1.4",
+    "tape": "^4.6.3",
+    "write-json-file": "^2.0.0"
+  },
+  "dependencies": {
+    "@turf/invariant": "^4.2.0",
+    "geodesy": "1.1.1"
+  }
+}