New @turf-isobands module with MarchingSquares (#619)

* added isobands module

* updated to latest version of @Turf and MarchingSquaresJS

* integrated module.export to MS-isobands, added sandbox

* updated marchingsquare library

* removed sandbox

* modified version and license

* made suggested corrections

* replaced minified marchingsquare

* Refactoring turf-isobands

* Add z coordinate fixture

* Separate isobands into methods
- Include npm marchingsquares
- Add points-random test/in
- change property as optional

* Add isolines test fixture

* added methods to accept random points as input

* corrected linting issues

* corrected linting issues

* rinamed function dividePointsByLatitude

* Update test/out fixtures
CC: @stebogit

* reordered methods

* - removed random points tests;
- set aside z-coordinate test;
- fixed output dimensions issue;
- added grid-to-matrix dependancy;

* adds matrix outer frame;
adds grid test;

* simplified code

* set matrix json as valid test input

* fixed output;
added tests;
updated benchmark;
updated readme;
introduced common and per isoband options;

.eslintignore

@@ -4,5 +4,6 @@ test.js
 bench.js
 packages/turf/turf.js
 packages/turf/turf.min.js
+marchingsquares-isobands.js
 rollup.config.js
 simplepolygon.js

packages/turf-isobands/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 turf
+
+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-isobands/README.md

@@ -0,0 +1,59 @@
+# turf-isobands
+
+# isobands
+
+Takes a grid [FeatureCollection](http://geojson.org/geojson-spec.html#feature-collection-objects) of [Point](http://geojson.org/geojson-spec.html#point) features with z-values and an array of
+value breaks and generates filled contour isobands.
+
+**Parameters**
+
+-   `points` **[FeatureCollection](http://geojson.org/geojson-spec.html#feature-collection-objects)<[Point](http://geojson.org/geojson-spec.html#point)>** a FeatureCollection of [Point](http://geojson.org/geojson-spec.html#point) features
+-   `breaks` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)>** where to draw contours
+-   `zProperty` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** the property name in `points` from which z-values will be pulled (optional, default `'elevation'`)
+ - `options` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** options on output
+   + `isobandProperties` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>** GeoJSON properties passed, in order, to the correspondent isoband (order defined by breaks)
+   + `commonProperties` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** GeoJSON properties passed to ALL isobands
+
+**Examples**
+
+```javascript
+// create random points with random
+// z-values in their properties
+var extent = [-70.823364, -33.553984, -69.823364, -32.553984];
+var cellWidth = 5;
+var units = 'miles';
+var pointGrid = turf.pointGrid(extent, cellWidth, units);
+for (var i = 0; i < pointGrid.features.length; i++) {
+    pointGrid.features[i].properties.elevation = Math.random() * 10;
+}
+var breaks = [0, 5, 8.5];
+var isobands = turf.isobands(pointGrid, breaks, 'elevation');
+//=isobands
+```
+
+Returns **[FeatureCollection](http://geojson.org/geojson-spec.html#feature-collection-objects)&lt;[MultiPolygon](http://geojson.org/geojson-spec.html#multipolygon)>** a FeatureCollection of [MultiPolygon](http://geojson.org/geojson-spec.html#multipolygon) features representing isobands
+
+<!-- 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-isobands
+```
+
+Or install the Turf module that includes it as a function:
+
+```sh
+$ npm install @turf/turf
+```

packages/turf-isobands/bench.js

@@ -0,0 +1,64 @@
+const path = require('path');
+const Benchmark = require('benchmark');
+const load = require('load-json-file');
+const fs = require('fs');
+const matrixToGrid = require('matrix-to-grid');
+const isobands = require('./');
+
+// Define Fixtures
+const directory = path.join(__dirname, 'test', 'in') + path.sep;
+const fixtures = fs.readdirSync(directory).map(filename => {
+    return {
+        filename,
+        name: path.parse(filename).name,
+        jsondata: load.sync(directory + filename)
+    };
+});
+
+/**
+ * Benchmark Results
+ *
+ * bigMatrix x 73.43 ops/sec ±2.12% (62 runs sampled)
+ * matrix1 x 5,205 ops/sec ±3.13% (78 runs sampled)
+ * matrix2 x 2,333 ops/sec ±9.38% (71 runs sampled)
+ * pointGrid x 3,201 ops/sec ±1.81% (78 runs sampled)
+ */
+const suite = new Benchmark.Suite('turf-isobands');
+for (const {name, jsondata, filename} of fixtures) {
+
+    let breaks, points, zProperty, isobandProperties, commonProperties;
+    // allow geojson featureCollection...
+    if (filename.includes('geojson')) {
+        breaks = jsondata.properties.breaks;
+        zProperty = jsondata.properties.zProperty;
+        commonProperties = jsondata.properties.commonProperties;
+        isobandProperties = jsondata.properties.isobandProperties;
+        points = jsondata;
+    } else {
+        // ...or matrix input
+        const matrix = jsondata.matrix;
+        const cellSize = jsondata.cellSize;
+        const origin = jsondata.origin;
+        breaks = jsondata.breaks;
+        zProperty = jsondata.zProperty;
+        points = matrixToGrid(matrix, origin, cellSize, {zProperty, units: jsondata.units});
+        commonProperties = jsondata.commonProperties;
+        isobandProperties = jsondata.isobandProperties;
+    }
+
+    isobands(points, breaks, zProperty, {
+        commonProperties,
+        isobandProperties
+    });
+
+    // isobands(geojson, 'elevation', [5, 45, 55, 65, 85,  95, 105, 120, 180]);
+    suite.add(name, () => isobands(points, breaks, zProperty, {
+            commonProperties,
+            isobandProperties
+        })
+    );
+}
+suite
+  .on('cycle', e => console.log(String(e.target)))
+  .on('complete', () => {})
+  .run();

packages/turf-isobands/index.d.ts

@@ -0,0 +1,8 @@
+import {Points, MultiPolygons} from '@turf/helpers'
+
+/**
+ * http://turfjs.org/docs/#isobands
+ */
+declare function isobands(points: Points, breaks: Array<number>, property?: string): MultiPolygons;
+declare namespace isobands { }
+export = isobands;