Rhumb line modules

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.

packages/turf-rhumb-bearing/README.md

@@ -0,0 +1,68 @@
+# @turf/rhumb-bearing
+
+# rhumb-bearing
+
+Takes two [points](http://geojson.org/geojson-spec.html#point) and finds bearing the angle between them along a [Rhumb line](https://en.wikipedia.org/wiki/Rhumb_line),
+i.e. the angle measured in degrees from the north line (0 degrees)
+
+**Parameters**
+
+-   `start` **[Feature](http://geojson.org/geojson-spec.html#feature-objects)<[Point](http://geojson.org/geojson-spec.html#point)>** starting Point
+-   `end` **[Feature](http://geojson.org/geojson-spec.html#feature-objects)<[Point](http://geojson.org/geojson-spec.html#point)>** 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": {},
+  "geometry": {
+    "type": "Point",
+    "coordinates": [-75.343, 39.984]
+  }
+};
+var point2 = {
+  "type": "Feature",
+  "properties": {},
+  "geometry": {
+    "type": "Point",
+    "coordinates": [-75.534, 39.123]
+  }
+};
+
+var bearing = turf.rhumbBearing(point1, point2);
+
+//addToMap
+var addToMap = [point1, point2]
+point1.properties['marker-color'] = '#f00'
+point2.properties['marker-color'] = '#0f0'
+point1.properties.bearing = bearing
+```
+
+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
+```

packages/turf-rhumb-bearing/bench.js

@@ -0,0 +1,20 @@
+var Benchmark = require('benchmark');
+var point = require('@turf/helpers').point;
+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();

packages/turf-rhumb-bearing/index.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="geojson" />
+
+type Point = GeoJSON.Feature<GeoJSON.Point>;
+
+/**
+ * http://turfjs.org/docs/#rhumb-bearing
+ */
+declare function rhumbBearing(start: Point, end: Point): number;
+declare namespace rhumbBearing { }
+export = rhumbBearing;

packages/turf-rhumb-bearing/index.js

@@ -0,0 +1,60 @@
+// https://en.wikipedia.org/wiki/Rhumb_line
+// http://www.movable-type.co.uk/scripts/latlong.html#rhumblines
+var getCoords = require('@turf/invariant').getCoords;
+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 rhumb-bearing
+ * @param {Feature<Point>} start starting Point
+ * @param {Feature<Point>} 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": {},
+ *   "geometry": {
+ *     "type": "Point",
+ *     "coordinates": [-75.343, 39.984]
+ *   }
+ * };
+ * var point2 = {
+ *   "type": "Feature",
+ *   "properties": {},
+ *   "geometry": {
+ *     "type": "Point",
+ *     "coordinates": [-75.534, 39.123]
+ *   }
+ * };
+ *
+ * var bearing = turf.rhumbBearing(point1, point2);
+ *
+ * //addToMap
+ * var addToMap = [point1, point2]
+ * point1.properties['marker-color'] = '#f00'
+ * point2.properties['marker-color'] = '#0f0'
+ * point1.properties.bearing = bearing
+ */
+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 = getCoords(start);
+    var coordsEnd = getCoords(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;
+};

packages/turf-rhumb-bearing/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@turf/rhumb-bearing",
+  "version": "4.2.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",
+  "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": "^1.0.0",
+    "tape": "^3.5.0",
+    "write-json-file": "^2.0.0"
+  },
+  "dependencies": {
+    "@turf/invariant": "^4.2.0",
+    "geodesy": "1.1.1"
+  }
+}

packages/turf-rhumb-bearing/test.js

@@ -0,0 +1,64 @@
+const path = require('path');
+// const {point, lineString, featureCollection} = require('@turf/helpers');
+const {point} = require('@turf/helpers');
+// const rhumbDestination = require('@turf/rhumb-destination');
+const load = require('load-json-file');
+const fs = require('fs');
+const test = require('tape');
+const write = require('write-json-file');
+// const getCoords = require('@turf/invariant').getCoords;
+const rhumbBearing = require('./');
+
+const directories = {
+    in: path.join(__dirname, 'test', 'in') + path.sep,
+    out: path.join(__dirname, 'test', 'out') + path.sep
+};
+
+let fixtures = fs.readdirSync(directories.in).map(filename => {
+    return {
+        filename,
+        name: path.parse(filename).name,
+        geojson: load.sync(directories.in + filename)
+    };
+});
+
+test('bearing', t => {
+    for (const {name, filename, geojson} of fixtures) {
+
+        const start = geojson.features[0];
+        const end = geojson.features[1];
+
+        const initialBearing = rhumbBearing(start, end);
+        const finalBearing = rhumbBearing(start, end, true);
+
+        const result = {
+            "initialBearing": initialBearing,
+            "finalBearing": finalBearing
+        };
+        if (process.env.REGEN) write.sync(directories.out + name +'.json', result);
+        t.deepEqual(load.sync(directories.out + name + '.json'), result, name);
+
+        // TODO adopt the following graphical output once rhumbDestination is published
+        //
+        // const initialDestination = rhumbDestination(start, 1000, initialBearing);
+        // const initialLine = lineString([getCoords(start), getCoords(initialDestination)], {
+        //     'stroke': '#F00',
+        //     'stroke-width': 6
+        // });
+        //
+        // const finalDestination = rhumbDestination(end, 1000, finalBearing - 180);
+        // const finalLine = lineString([getCoords(end), getCoords(finalDestination)], {
+        //     'stroke': '#00F',
+        //     'stroke-width': 6
+        // });
+        //
+        // const result = featureCollection([start, end, initialLine, finalLine]);
+        //
+        // if (process.env.REGEN) write.sync(directories.out + filename, result);
+        // t.deepEqual(load.sync(directories.out + filename), result, name);
+    }
+
+    t.throws(() => { rhumbBearing(point([12, -54]), 'point'); }, 'invalid point');
+
+    t.end();
+});

packages/turf-rhumb-bearing/test/in/pair1.geojson

@@ -0,0 +1,31 @@
+{
+  "type": "FeatureCollection",
+  "features": [
+    {
+      "type": "Feature",
+      "properties": {
+        "marker-color": "#F00"
+      },
+      "geometry": {
+        "type": "Point",
+        "coordinates": [
+          -75,
+          45
+        ]
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": {
+        "marker-color": "#00F"
+      },
+      "geometry": {
+        "type": "Point",
+        "coordinates": [
+          20,
+          60
+        ]
+      }
+    }
+  ]
+}

packages/turf-rhumb-bearing/test/out/pair1.geojson

@@ -0,0 +1,71 @@
+{
+	"type": "FeatureCollection",
+	"features": [
+		{
+			"type": "Feature",
+			"properties": {
+				"marker-color": "#F00"
+			},
+			"geometry": {
+				"type": "Point",
+				"coordinates": [
+					-75,
+					45
+				]
+			}
+		},
+		{
+			"type": "Feature",
+			"properties": {
+				"marker-color": "#00F"
+			},
+			"geometry": {
+				"type": "Point",
+				"coordinates": [
+					20,
+					60
+				]
+			}
+		},
+		{
+			"type": "Feature",
+			"properties": {
+				"stroke": "#F00",
+				"stroke-width": 6
+			},
+			"geometry": {
+				"type": "LineString",
+				"coordinates": [
+					[
+						-75,
+						45
+					],
+					[
+						-66.10068737769872,
+						51.79325008492101
+					]
+				]
+			}
+		},
+		{
+			"type": "Feature",
+			"properties": {
+				"stroke": "#00F",
+				"stroke-width": 6
+			},
+			"geometry": {
+				"type": "LineString",
+				"coordinates": [
+					[
+						20,
+						60
+					],
+					[
+						2.3844816279733956,
+						63.440396381483744
+					]
+				]
+			}
+		}
+	]
+}