Add error handling for incorrect input. Add more doco on inputs.

Author: rowanwins

CHANGES.md

@@ -0,0 +1,3 @@
+# 1.0.0
+- Add support for input validation to ensure rings are closed
+

LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Rowan Winsemius
+
+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.

README.md

@@ -1,49 +1,73 @@
-Based on the paper [Optimal Reliable Point-in-Polygon Test and
-Differential Coding Boolean Operations on Polygons](https://www.researchgate.net/publication/328261365_Optimal_Reliable_Point-in-Polygon_Test_and_Differential_Coding_Boolean_Operations_on_Polygons)
+A small library for detecting in a point lies inside a polygon
 
+**Features**
 - Works on polygons with holes
-- Works with degenerate polyons
-- Reports 0 if on the edge
+- Works with degenerate/self-intersecting polyons 
+- Returns `0` if on the edge
 - Not effected by floating point errors
 
 
 ### Usage
 Install via `npm install point-in-polygon-hao`
 
 ````
-const inside = require('point-in-polygon-hao')
-const polygon = [ [ [ 1, 1 ], [ 1, 2 ], [ 2, 2 ], [ 2, 1 ], [ 1, 1 ] ] ];
+import inside from 'point-in-polygon-hao'
+
+const polygon = [
+  [
+    [1, 1],
+    [1, 2],
+    [2, 2],
+    [2, 1],
+    [1, 1]
+  ]
+];
+
 inside([ 1.5, 1.5 ], polygon)
-// returns true
+// => true
 
 inside([ 4.9, 1.2 ], polygon)
-// returns false
+// => false
 
 inside([1, 2], polygon)
-// returns 0 to indicate on edge
+// => 0 to indicate on edge
 ````
 
+**Note:** The input polygon format aligns with the GeoJson specification for polygons. This means that the first and last coordinate in a polygon must be repeated, if not this library will throw an error.
+````
+const polygonWithHole = [
+  [
+    [0, 0], [1, 0], [1, 1], [0, 1], [0, 0]
+  ],
+  [
+    [0.1, 0.1], [0.1, 0.9], [0.9, 0.9], [0.9, 0.1], [0.1, 0.1]
+  ]
+]
+````
+The library does not support multi-polygons.
 
 ### Comparisons
 Some rough comparisons to similar libraries. 
 While `point-in-polygon` is slightly faster in most cases it does not support polygons with holes or degenerate polygons.
 
+````
+// For a point in a much larger geometry (700+ vertices)
+point-in-poly-hao x 474,180 ops/sec ±0.55% (93 runs sampled)
+point-in-polygon x 489,649 ops/sec ±0.75% (91 runs sampled)
+robust-point-in-polygon x 376,268 ops/sec ±0.79% (89 runs sampled)
+````
+
 ````
 // For a point in bounding box check
 point-in-poly-hao x 29,365,704 ops/sec ±1.30% (90 runs sampled)
-turf-point-in-polygon x 7,142,567 ops/sec ±0.61% (93 runs sampled)
 point-in-polygon x 42,339,450 ops/sec ±0.78% (95 runs sampled)
 robust-point-in-polygon x 20,675,569 ops/sec ±0.65% (95 runs sampled)
 ````
 
-````
-// For a point in a much larger geometry (700+ vertices)
-point-in-poly-hao x 474,180 ops/sec ±0.55% (93 runs sampled)
-turf-point-in-polygon x 214,584 ops/sec ±0.74% (95 runs sampled)
-point-in-polygon x 489,649 ops/sec ±0.75% (91 runs sampled)
-robust-point-in-polygon x 376,268 ops/sec ±0.79% (89 runs sampled)
-````
+### Algorithm
+This library is based on the paper [Optimal Reliable Point-in-Polygon Test and
+Differential Coding Boolean Operations on Polygons](https://www.researchgate.net/publication/328261365_Optimal_Reliable_Point-in-Polygon_Test_and_Differential_Coding_Boolean_Operations_on_Polygons)
 
 ### Other notes
 * Works irrespective of winding order of polygon
-* Does not appear to be effected by flaoting point errors compared to `point-in-polygon`
+* Does not appear to be effected by floating point errors compared to `point-in-polygon` or `robust-point-in-polygon`

package.json

@@ -1,6 +1,6 @@
 {
   "name": "point-in-polygon-hao",
-  "version": "0.0.7",
+  "version": "1.0.0",
   "description": "A point in polygon based on the paper Optimal Reliable Point-in-Polygon Test and Differential Coding Boolean Operations on Polygons",
   "main": "dist/pointInPolygon.js",
   "module": "src/index.js",
@@ -9,17 +9,17 @@
   "scripts": {
     "bench": "npm run build && node test/bench.js",
     "build": "rollup -c",
-    "test": "ava -v"
+    "test": "ava"
+  },
+  "dependencies": {
   },
-  "dependencies": {},
   "devDependencies": {
     "@turf/boolean-point-in-polygon": "^6.0.1",
-    "ava": "^1.3.1",
+    "ava": "^3.15.0",
     "benchmark": "^2.1.4",
     "eslint": "^5.15.3",
     "eslint-config-mourner": "^3.0.0",
     "esm": "^3.2.20",
-    "jsts": "^2.0.3",
     "load-json-file": "^5.2.0",
     "point-in-polygon": "^1.0.1",
     "robust-point-in-polygon": "^1.0.3",
@@ -28,11 +28,12 @@
   },
   "ava": {
     "files": [
-      "test/*spec.js"
+      "test/*.spec.js"
     ],
     "require": [
       "esm"
-    ]
+    ],
+    "verbose": true
   },
   "keywords": [
     "point-in-polygon",

src/index.js

@@ -20,6 +20,11 @@ export default function pointInPolygon(p, polygon) {
         const contour = polygon[i]
 
         currentP = contour[0]
+        if (currentP[0] !== contour[contourLen][0] &&
+            currentP[1] !== contour[contourLen][1]) {
+            throw new Error('First and last coordinates in a ring must be the same')
+        }
+
         u1 = currentP[0] - x
         v1 = currentP[1] - y
 

test/biggeom.spec.js

@@ -1,6 +1,6 @@
 import test from 'ava'
-const loadJsonFile = require('load-json-file')
-const path = require('path')
+import loadJsonFile from 'load-json-file'
+import path from 'path'
 
 import inside from '../src/index'
 

test/test.spec.js

@@ -1,4 +1,4 @@
-import test from 'ava';
+import test from 'ava'
 import inside from '../src/index'
 
 const polygon = [[[1, 1], [1, 2], [2, 2], [2, 1], [1, 1]]];
@@ -57,18 +57,16 @@ test('is on edge of the outside', t => {
     t.is(inside([1.2, 1], polygonWithHole), 0)
 });
 
-// https://github.com/substack/point-in-polygon/issues/2
-test('point-in-polygon issues solved', t => {
-    const poly = [[[1, 1], [2, 1], [2, 2], [1, 2]]]
-    t.is(inside([2, 2], poly), 0)
-    t.is(inside([1, 1], poly), 0)
-});
 
-// https://github.com/mikolalysenko/robust-point-in-polygon/issues/3
-test('robust-point-in-polygon issues solved', t => {
+test('error is thrown when not the same first and last coords', t => {
     const poly = [[[0, 0], [1, 0], [1, 1]]]
-    t.is(inside([1, 1], poly), 0)
-    const anotherPoly = [[[1, 1], [1, 2], [2, 3], [2, 2]]]
-    t.is(inside([1, 1], anotherPoly), 0)
-    t.is(inside([2, 3], anotherPoly), 0)
+
+    const fn = () => {
+        inside([1, 1], poly)
+    };
+
+    const error = t.throws(() => {
+        fn()
+    }, {instanceOf: Error})
+    t.is(error.message, 'First and last coordinates in a ring must be the same');
 });