New module @turf/boolean-overlaps (#856)

* imported turf-overlaps from

* first refactoring

* refactored tests; updated bench;

* added new tests; restored clockwise files removed by mistake;

* added geometries test

* updated bench results with all tests

* refactored with segment each; still in progress...

* completed implementation:
- added equal check;
- updated tests;
- updated bench;
- updated types;

* updated readme and package.json

* renamed module to

packages/turf-boolean-clockwise/index.d.ts

@@ -6,5 +6,6 @@ type Line = GeoJSON.Feature<GeoJSON.LineString> | GeoJSON.LineString | Array<Arr
  * http://turfjs.org/docs/#boolean-clockwise
  */
 declare function clockwise(line: Line): boolean;
-declare namespace clockwise { }
-export = clockwise;
+declare namespace clockwise {
+}
+export = clockwise;

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

@@ -0,0 +1,51 @@
+# @turf/boolean-overlap
+
+# booleanOverlap
+
+Compares two geometries of the same dimension and returns true if their intersection set results in a geometry different from both but of the same dimension. It applies to Polygon/Polygon, LineString/LineString, Multipoint/Multipoint, MultiLineString/MultiLineString and MultiPolygon/MultiPolygon
+
+**Parameters**
+
+-   `feature1` **([Geometry](http://geojson.org/geojson-spec.html#geometry) \| [Feature](http://geojson.org/geojson-spec.html#feature-objects)<any>)** GeoJSON Feature or Geometry
+-   `feature2` **([Geometry](http://geojson.org/geojson-spec.html#geometry) \| [Feature](http://geojson.org/geojson-spec.html#feature-objects)<any>)** GeoJSON Feature or Geometry
+
+**Examples**
+
+```javascript
+var poly1 = turf.polygon([[[0,0],[0,5],[5,5],[5,0],[0,0]]]);
+var poly2 = turf.polygon([[[1,1],[1,6],[6,6],[6,1],[1,1]]]);
+var poly3 = turf.polygon([[[10,10],[10,15],[15,15],[15,10],[10,10]]]);
+
+turf.booleanOverlap(poly1, poly2)
+//=true
+turf.booleanOverlap(poly2, poly3)
+//=false
+```
+
+Returns **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** true/false
+
+<!-- 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/boolean-overlap
+```
+
+Or install the Turf module that includes it as a function:
+
+```sh
+$ npm install @turf/turf
+```
+

packages/turf-boolean-overlap/bench.js

@@ -0,0 +1,57 @@
+const path = require('path');
+const glob = require('glob');
+const load = require('load-json-file');
+const overlap = require('./');
+const Benchmark = require('benchmark');
+
+/**
+ * Benchmark Results
+ *
+ * equal-linear-rings: 2.348ms
+ * equal-lines-inverse: 0.319ms
+ * equal-multipoints: 0.703ms
+ * equal-polygons: 0.343ms
+ * linear-rings: 19.876ms
+ * lines: 1.244ms
+ * multipoints: 1.003ms
+ * polygon-with-hole-polygon: 1.822ms
+ * polygons: 0.242ms
+ * linear-rings: 5.881ms
+ * lines: 8.569ms
+ * multipoints: 0.082ms
+ * polygon-with-hole-polygon: 1.158ms
+ * polygons: 0.114ms
+ * simple-lines: 0.724ms
+ * single-multipoints: 0.055ms
+ * equal-linear-rings x 39,585 ops/sec ±24.47% (40 runs sampled)
+ * equal-lines-inverse x 52,454 ops/sec ±24.98% (59 runs sampled)
+ * equal-multipoints x 24,361 ops/sec ±10.90% (59 runs sampled)
+ * equal-polygons x 36,479 ops/sec ±22.33% (48 runs sampled)
+ * linear-rings x 2,625 ops/sec ±16.13% (47 runs sampled)
+ * lines x 6,756 ops/sec ±5.54% (70 runs sampled)
+ * multipoints x 234,229 ops/sec ±7.44% (64 runs sampled)
+ * polygon-with-hole-polygon x 34,922 ops/sec ±6.70% (61 runs sampled)
+ * polygons x 79,687 ops/sec ±2.98% (79 runs sampled)
+ * linear-rings x 3,252 ops/sec ±5.96% (66 runs sampled)
+ * lines x 4,328 ops/sec ±8.67% (63 runs sampled)
+ * multipoints x 285,695 ops/sec ±2.91% (77 runs sampled)
+ * polygon-with-hole-polygon x 39,154 ops/sec ±2.30% (80 runs sampled)
+ * polygons x 79,419 ops/sec ±2.21% (77 runs sampled)
+ * simple-lines x 7,479 ops/sec ±3.99% (71 runs sampled)
+ * single-multipoints x 232,414 ops/sec ±13.49% (67 runs sampled)
+ */
+const suite = new Benchmark.Suite('turf-boolean-disjoint');
+glob.sync(path.join(__dirname, 'test', '**', '*.geojson')).forEach(filepath => {
+    const {name} = path.parse(filepath);
+    const geojson = load.sync(filepath);
+    const [feature1, feature2] = geojson.features;
+    console.time(name);
+    overlap(feature1, feature2);
+    console.timeEnd(name);
+    suite.add(name, () => overlap(feature1, feature2));
+});
+
+suite
+    .on('cycle', e => console.log(String(e.target)))
+    .on('complete', () => {})
+    .run();

packages/turf-boolean-overlap/index.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="geojson" />
+
+type Feature = GeoJSON.Feature<any> | GeoJSON.GeometryObject
+
+/**
+ * http://turfjs.org/docs/#boolean-overlap
+ */
+declare function overlap(feature1: Feature, feature2: Feature): boolean;
+declare namespace overlap { }
+export = overlap;

packages/turf-boolean-overlap/index.js

@@ -0,0 +1,96 @@
+var meta = require('@turf/meta');
+var helpers = require('@turf/helpers');
+var invariant = require('@turf/invariant');
+var lineOverlap = require('@turf/line-overlap');
+var lineIntersect = require('@turf/line-intersect');
+var GeojsonEquality = require('geojson-equality');
+var coordAll = meta.coordAll;
+var lineString = helpers.lineString;
+var flattenEach = meta.flattenEach;
+var coordReduce = meta.coordReduce;
+var getGeomType = invariant.getGeomType;
+
+/**
+ * Compares two geometries of the same dimension and returns true if their intersection set results in a geometry
+ * different from both but of the same dimension. It applies to Polygon/Polygon, LineString/LineString,
+ * Multipoint/Multipoint, MultiLineString/MultiLineString and MultiPolygon/MultiPolygon
+ *
+ * @name booleanOverlap
+ * @param  {Geometry|Feature<LineString|MultiLineString|Polygon|MultiPolygon>} feature1 input
+ * @param  {Geometry|Feature<LineString|MultiLineString|Polygon|MultiPolygon>} feature2 input
+ * @returns {boolean} true/false
+ * @example
+ * var poly1 = turf.polygon([[[0,0],[0,5],[5,5],[5,0],[0,0]]]);
+ * var poly2 = turf.polygon([[[1,1],[1,6],[6,6],[6,1],[1,1]]]);
+ * var poly3 = turf.polygon([[[10,10],[10,15],[15,15],[15,10],[10,10]]]);
+ *
+ * turf.booleanOverlap(poly1, poly2)
+ * //=true
+ * turf.booleanOverlap(poly2, poly3)
+ * //=false
+ */
+module.exports = function (feature1, feature2) {
+    // validation
+    if (!feature1) throw new Error('feature1 is required');
+    if (!feature2) throw new Error('feature2 is required');
+    var type1 = getGeomType(feature1);
+    var type2 = getGeomType(feature2);
+    if (type1 !== type2) throw new Error('features must be of the same type');
+    if (type1 === 'Point') throw new Error('Point geometry not supported');
+
+    // false if features are equal
+    var considerDirection = (type1 === 'LineString' && feature1.coor);
+    var equality = new GeojsonEquality({direction: considerDirection, precision: 6});
+    if (equality.compare(feature1, feature2)) return false;
+
+    var overlap = 0;
+
+    switch (type1) {
+    case 'MultiPoint':
+        var coords1 = coordAll(feature1);
+        var coords2 = coordAll(feature2);
+        coords1.forEach(function (coord1) {
+            coords2.forEach(function (coord2) {
+                if (coord1[0] === coord2[0] && coord1[1] === coord2[1]) overlap++;
+            });
+        });
+        break;
+
+    case 'LineString':
+    case 'MultiLineString':
+        segmentEach(feature1, function (segment1) {
+            segmentEach(feature2, function (segment2) {
+                if (lineOverlap(segment1, segment2).features.length) overlap++;
+            });
+        });
+        break;
+
+    case 'Polygon':
+    case 'MultiPolygon':
+        segmentEach(feature1, function (segment1) {
+            segmentEach(feature2, function (segment2) {
+                if (lineIntersect(segment1, segment2).features.length) overlap++;
+            });
+        });
+        break;
+    }
+
+    return overlap > 0;
+};
+
+// todo: replace with new @turf/meta.segmentEach
+function segmentEach(geojson, callback) {
+    var currentIndex = 0;
+    flattenEach(geojson, function (feature, featureIndex, featureSubIndex) {
+        // (Multi)Point geometries do not contain segments therefore they are ignored during this operation.
+        var type = feature.geometry.type;
+        if (type === 'Point' || type === 'MultiPoint') return;
+        // Generate 2-vertex line segments
+        coordReduce(feature, function (previousCoords, currentCoords) {
+            var currentSegment = lineString([previousCoords, currentCoords], feature.properties);
+            callback(currentSegment, currentIndex, featureIndex, featureSubIndex);
+            currentIndex++;
+            return currentCoords;
+        });
+    });
+}

packages/turf-boolean-overlap/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@turf/boolean-overlap",
+  "version": "4.5.0",
+  "description": "turf boolean-overlap 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",
+    "gis",
+    "boolean",
+    "de-9im",
+    "overlap"
+  ],
+  "author": "Turf Authors",
+  "contributors": [
+    "Tim Channell <@tcql>",
+    "Stefano Borghi <@stebogit>"
+  ],
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Turfjs/turf/issues"
+  },
+  "homepage": "https://github.com/Turfjs/turf",
+  "devDependencies": {
+    "benchmark": "^2.1.4",
+    "glob": "^7.1.1",
+    "load-json-file": "^2.0.0",
+    "tape": "^4.6.3"
+  },
+  "dependencies": {
+    "@turf/helpers": "^4.5.2",
+    "@turf/invariant": "^4.5.2",
+    "@turf/line-overlap": "^4.5.2",
+    "@turf/line-intersect": "^4.5.2",
+    "@turf/meta": "^4.5.2",
+    "geojson-equality": "0.1.6"
+  }
+}

packages/turf-boolean-overlap/test.js

@@ -0,0 +1,42 @@
+const glob = require('glob');
+const path = require('path');
+const test = require('tape');
+const load = require('load-json-file');
+const {point, lineString} = require('@turf/helpers');
+const overlap = require('./');
+
+test('turf-boolean-overlap', t => {
+    // True Fixtures
+    glob.sync(path.join(__dirname, 'test', 'true', '**', '*.geojson')).forEach(filepath => {
+        const {name} = path.parse(filepath);
+        const geojson = load.sync(filepath);
+        const [feature1, feature2] = geojson.features;
+        const result = overlap(feature1, feature2);
+
+        if (process.env.SHAPELY) shapely.contains(feature1, feature2).then(result => t.true(result, '[true] shapely - ' + name));
+        t.true(result, '[true] ' + name);
+    });
+    // False Fixtures
+    glob.sync(path.join(__dirname, 'test', 'false', '**', '*.geojson')).forEach(filepath => {
+        const {name} = path.parse(filepath);
+        const geojson = load.sync(filepath);
+        const [feature1, feature2] = geojson.features;
+        const result = overlap(feature1, feature2);
+
+        if (process.env.SHAPELY) shapely.contains(feature1, feature2).then(result => t.false(result, '[false] shapely - ' + name));
+        t.false(result, '[false] ' + name);
+    });
+    t.end();
+});
+
+test('turf-boolean-overlap -- throws', t => {
+    const pt = point([9, 50]);
+    const line = lineString([[7, 50], [8, 50], [9, 50]]);
+
+    t.throws(() => overlap(null, line), /feature1 is required/, 'missing feature1');
+    t.throws(() => overlap(line, null), /feature2 is required/, 'missing feature2');
+    t.throws(() => overlap(pt, line), /features must be of the same type/, 'different types');
+    t.throws(() => overlap(pt, pt), /Point geometry not supported/, 'geometry not supported');
+
+    t.end();
+});

packages/turf-boolean-overlap/test/false/equal-linear-rings.geojson

@@ -0,0 +1,55 @@
+{
+	"type": "FeatureCollection",
+	"features": [
+		{
+			"type": "Feature",
+			"properties": {},
+			"geometry": {
+				"type": "LineString",
+				"coordinates": [
+					[
+						-53.674866943359375,
+						28.30135788537988
+					],
+					[
+						-53.337249755859375,
+						28.47412369059679
+					],
+					[
+						-53.524017333984375,
+						28.17492820114568
+					],
+					[
+						-53.674866943359375,
+						28.30135788537988
+					]
+				]
+			}
+		},
+		{
+			"type": "Feature",
+			"properties": {},
+			"geometry": {
+				"type": "LineString",
+				"coordinates": [
+					[
+						-53.674866943359375,
+						28.30135788537988
+					],
+					[
+						-53.337249755859375,
+						28.47412369059679
+					],
+					[
+						-53.524017333984375,
+						28.17492820114568
+					],
+					[
+						-53.674866943359375,
+						28.30135788537988
+					]
+				]
+			}
+		}
+	]
+}