New module @turf/sector (#653)

* added turf-sector module

* Add dynamic geojson testing

* extract required params from GeoJSON properties

* Add benchmark

* truncate coordinate decimals
Different OS has minor differences in coordinate decimals, truncate normalizes the results to pass on all different OS

* Remove extract required params from properties

* Update benchmark results

* Update Typescript defintion with distance Units

* Add getCoords from `invariant`
CC: @stebogit

* Fix sector4 test

* Add test case with error
This `sector-error.geojson` seems to be having some issues, it should be the inverse.
- bearing1 = -15 (345)
- bearing2 = -50 (310)
CC: @stebogit

* corrected bearing2 error message

* fixed error with bearing1 > bearing2

* removed debug variable

* replaced getArcLine() with @turf/line-arc

packages/turf-sector/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-sector/README.md

@@ -0,0 +1,57 @@
+# @turf/sector
+
+# sector
+
+Creates a circular sector of a circle of given radius and center [Point](http://geojson.org/geojson-spec.html#point),
+between (clockwise) bearing1 and bearing2; 0 bearing is North of center point, positive clockwise.
+
+**Parameters**
+
+-   `center` **[Feature](http://geojson.org/geojson-spec.html#feature-objects)<[Point](http://geojson.org/geojson-spec.html#point)>** center point
+-   `radius` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** radius of the circle
+-   `bearing1` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** angle, in decimal degrees, of the first radius of the sector
+-   `bearing2` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** angle, in decimal degrees, of the second radius of the sector
+-   `steps` **\[[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** number of steps (optional, default `64`)
+-   `units` **\[[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** miles, kilometers, degrees, or radians (optional, default `kilometers`)
+
+**Examples**
+
+```javascript
+var center = turf.point([-75.343, 39.984]);
+var radius = 5;
+var bearing1 = 25;
+var bearing2 = 47;
+var steps = 30;
+var units = 'kilometers';
+
+var sector = turf.sector(center, radius, bearing1, bearing2, steps, units);
+
+//=sector
+```
+
+Returns **[Feature](http://geojson.org/geojson-spec.html#feature-objects)<[Polygon](http://geojson.org/geojson-spec.html#polygon)>** sector polygon
+
+<!-- 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/sector
+```
+
+Or install the Turf module that includes it as a function:
+
+```sh
+$ npm install @turf/turf
+```

packages/turf-sector/bench.js

@@ -0,0 +1,36 @@
+const Benchmark = require('benchmark');
+const path = require('path');
+const fs = require('fs');
+const load = require('load-json-file');
+const sector = require('./');
+
+const directory = path.join(__dirname, 'test', 'in') + path.sep;
+const fixtures = fs.readdirSync(directory).map(filename => {
+    return {
+        name: path.parse(filename).name,
+        geojson: load.sync(directory + filename)
+    };
+});
+
+/**
+ * Benchmark Results
+ *
+ * sector-full-360 x 29,179 ops/sec ±2.42% (76 runs sampled)
+ * sector-greater-360 x 296,103 ops/sec ±10.92% (65 runs sampled)
+ * sector1 x 189,709 ops/sec ±3.46% (75 runs sampled)
+ * sector2 x 72,365 ops/sec ±2.11% (77 runs sampled)
+ * sector3 x 38,093 ops/sec ±2.97% (77 runs sampled)
+ * sector4 x 210,468 ops/sec ±2.58% (78 runs sampled)
+ * sector5 x 26,438 ops/sec ±9.98% (70 runs sampled)
+ * sector6 x 29,032 ops/sec ±2.36% (70 runs sampled)
+ */
+const suite = new Benchmark.Suite('turf-sector');
+for (const {name, geojson} of fixtures) {
+    const {radius, bearing1, bearing2} = geojson.properties;
+    suite.add(name, () => sector(geojson, radius, bearing1, bearing2));
+}
+
+suite
+    .on('cycle', e => console.log(String(e.target)))
+    .on('complete', () => {})
+    .run();

packages/turf-sector/index.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="geojson" />
+
+import {Point, Polygon, Units} from '@turf/helpers';
+
+/**
+ * http://turfjs.org/docs/#sector
+ */
+declare function sector(center: Point, radius: number, bearing1: number, bearing2: number, steps?: number, units?: Units): Polygon;
+declare namespace sector {}
+export = sector;

packages/turf-sector/index.js

@@ -0,0 +1,76 @@
+var circle = require('@turf/circle');
+var coordEach = require('@turf/meta').coordEach;
+var helpers = require('@turf/helpers');
+var getCoords = require('@turf/invariant').getCoords;
+var polygon = helpers.polygon;
+var lineArc = require('@turf/line-arc');
+
+/**
+ * Creates a circular sector of a circle of given radius and center {@link Point},
+ * between (clockwise) bearing1 and bearing2; 0 bearing is North of center point, positive clockwise.
+ *
+ * @name sector
+ * @param {Feature<Point>} center center point
+ * @param {number} radius radius of the circle
+ * @param {number} bearing1 angle, in decimal degrees, of the first radius of the sector
+ * @param {number} bearing2 angle, in decimal degrees, of the second radius of the sector
+ * @param {number} [steps=64] number of steps
+ * @param {string} [units=kilometers] miles, kilometers, degrees, or radians
+ * @returns {Feature<Polygon>} sector polygon
+ * @example
+ * var center = {
+ *   "type": "Feature",
+ *   "properties": {},
+ *   "geometry": {
+ *     "type": "Point",
+ *     "coordinates": [-75, 40]
+ *   }
+ * }
+ * var radius = 5;
+ * var bearing1 = 25;
+ * var bearing2 = 45;
+ *
+ * var sector = turf.sector(center, radius, bearing1, bearing2);
+ *
+ * //addToMap
+ * var addToMap = [center, sector]
+ */
+module.exports = function (center, radius, bearing1, bearing2, steps, units) {
+    // validation
+    if (!center) throw new Error('center is required');
+    if (bearing1 === undefined || bearing1 === null) throw new Error('bearing1 is required');
+    if (bearing2 === undefined || bearing2 === null) throw new Error('bearing2 is required');
+    if (!radius) throw new Error('radius is required');
+
+    // default params
+    steps = steps || 64;
+
+    if (convertAngleTo360(bearing1) === convertAngleTo360(bearing2)) {
+        return circle(center, radius, steps, units);
+    }
+    var coords = getCoords(center);
+    var arc = lineArc(center, radius, bearing1, bearing2, steps, units);
+    var sliceCoords = [[coords]];
+    coordEach(arc, function (currentCoords) {
+        sliceCoords[0].push(currentCoords);
+    });
+    sliceCoords[0].push(coords);
+
+    return polygon(sliceCoords);
+};
+
+/**
+ * Takes any angle in degrees
+ * and returns a valid angle between 0-360 degrees
+ *
+ * @private
+ * @param {number} alfa angle between -180-180 degrees
+ * @returns {number} angle between 0-360 degrees
+ */
+function convertAngleTo360(alfa) {
+    var beta = alfa % 360;
+    if (beta < 0) {
+        beta += 360;
+    }
+    return beta;
+}

packages/turf-sector/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@turf/sector",
+  "version": "4.0.0",
+  "description": "turf sector 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",
+    "gif"
+  ],
+  "author": "Turf Authors",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Turfjs/turf/issues"
+  },
+  "homepage": "https://github.com/Turfjs/turf",
+  "devDependencies": {
+    "@turf/truncate": "^4.0.1",
+    "benchmark": "^2.1.4",
+    "load-json-file": "^2.0.0",
+    "tape": "^4.6.3",
+    "write-json-file": "^2.0.0"
+  },
+  "dependencies": {
+    "@turf/circle": "^4.0.1",
+    "@turf/line-arc": "^4.0.1",
+    "@turf/helpers": "^4.0.1",
+    "@turf/invariant": "^4.0.1",
+    "@turf/meta": "^4.0.1"
+  }
+}

packages/turf-sector/test.js

@@ -0,0 +1,33 @@
+const test = require('tape');
+const fs = require('fs');
+const path = require('path');
+const load = require('load-json-file');
+const write = require('write-json-file');
+const truncate = require('@turf/truncate');
+const featureCollection = require('@turf/helpers').featureCollection;
+const sector = require('./');
+
+const directories = {
+    in: path.join(__dirname, 'test', 'in') + path.sep,
+    out: path.join(__dirname, 'test', 'out') + path.sep
+};
+
+const fixtures = fs.readdirSync(directories.in).map(filename => {
+    return {
+        filename,
+        name: path.parse(filename).name,
+        geojson: load.sync(directories.in + filename)
+    };
+});
+
+test('turf-sector', t => {
+    for (const {filename, name, geojson}  of fixtures) {
+        const {radius, bearing1, bearing2} = geojson.properties;
+        const sectored = truncate(sector(geojson, radius, bearing1, bearing2));
+        const results = featureCollection([geojson, sectored]);
+
+        if (process.env.REGEN) write.sync(directories.out + filename, results);
+        t.deepEquals(results, load.sync(directories.out + filename), name);
+    }
+    t.end();
+});

packages/turf-sector/test/in/sector-full-360.geojson

@@ -0,0 +1,15 @@
+{
+  "type": "Feature",
+  "properties": {
+    "radius": 5,
+    "bearing1": 180,
+    "bearing2": -180
+  },
+  "geometry": {
+    "type": "Point",
+    "coordinates": [
+      11.343,
+      44.495
+    ]
+  }
+}

packages/turf-sector/test/in/sector-greater-360.geojson

@@ -0,0 +1,15 @@
+{
+  "type": "Feature",
+  "properties": {
+    "radius": 5,
+    "bearing1": 0,
+    "bearing2": 380
+  },
+  "geometry": {
+    "type": "Point",
+    "coordinates": [
+      11.343,
+      44.495
+    ]
+  }
+}

packages/turf-sector/test/in/sector1.geojson

@@ -0,0 +1,15 @@
+{
+  "type": "Feature",
+  "properties": {
+    "radius": 5,
+    "bearing1": 20,
+    "bearing2": 60
+  },
+  "geometry": {
+    "type": "Point",
+    "coordinates": [
+      11.343,
+      44.495
+    ]
+  }
+}

packages/turf-sector/test/in/sector2.geojson

@@ -0,0 +1,15 @@
+{
+  "type": "Feature",
+  "properties": {
+    "radius": 5,
+    "bearing1": 90,
+    "bearing2": -135
+  },
+  "geometry": {
+    "type": "Point",
+    "coordinates": [
+      11.343,
+      44.495
+    ]
+  }
+}

packages/turf-sector/test/in/sector3.geojson

@@ -0,0 +1,15 @@
+{
+  "type": "Feature",
+  "properties": {
+    "radius": 5,
+    "bearing1": 45,
+    "bearing2": -45
+  },
+  "geometry": {
+    "type": "Point",
+    "coordinates": [
+      11.343,
+      44.495
+    ]
+  }
+}

packages/turf-sector/test/in/sector4.geojson

@@ -0,0 +1,15 @@
+{
+  "type": "Feature",
+  "properties": {
+    "radius": 5,
+    "bearing1": -50,
+    "bearing2": -15
+  },
+  "geometry": {
+    "type": "Point",
+    "coordinates": [
+      11.343,
+      44.495
+    ]
+  }
+}