Merge pull request #791 from Turfjs/grid-mask

Adds mask option to `@turf/point-grid`

packages/turf-point-grid/README.md

@@ -10,6 +10,7 @@ Creates a [Point](http://geojson.org/geojson-spec.html#point) grid from a boundi
 -   `cellSize` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** the distance across each cell
 -   `units` **\[[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** used in calculating cellSize, can be degrees, radians, miles, or kilometers (optional, default `kilometers`)
 -   `centered` **\[[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)]** adjust points position to center the grid into bbox (optional, default `false`)
+-   `bboxIsMask` **\[[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)]** if true, and bbox is a Polygon or MultiPolygon, the grid Point will be created only if inside the bbox Polygon(s) (optional, default `false`)
 
 **Examples**
 

packages/turf-point-grid/bench.js

@@ -1,16 +1,29 @@
 var grid = require('./');
+var polygon = require('@turf/helpers').polygon;
 var Benchmark = require('benchmark');
 
 var bbox = [-95, 30, -85, 40];
+var mask = polygon([[[6.5, 44.6 ], [ 9.2, 44.8 ], [ 8.3, 46.4 ], [ 6.5, 44.6 ]]]);
 
 var highres = grid(bbox, 100, 'miles').features.length;
 var midres = grid(bbox, 10, 'miles').features.length;
 var lowres = grid(bbox, 1, 'miles').features.length;
+var masked = grid(mask, 1, 'miles', true, true).features.length;
 var suite = new Benchmark.Suite('turf-square-grid');
+
+/**
+ * Benchmark Results
+ *
+ * highres -- 42 cells x 274,666 ops/sec ±1.96% (77 runs sampled)
+ * midres  -- 4200 cells x 2,725 ops/sec ±3.86% (73 runs sampled)
+ * lowres  -- 414508 cells x 2.09 ops/sec ±21.02% (10 runs sampled)
+ * masked  -- 7658 cells x 9,794 ops/sec ±2.08% (75 runs sampled)
+ */
 suite
   .add('highres -- ' + highres + ' cells', () => grid(bbox, 100, 'miles'))
   .add('midres  -- ' + midres + ' cells', () => grid(bbox, 10, 'miles'))
   .add('lowres  -- ' + lowres + ' cells', () => grid(bbox, 1, 'miles'))
+  .add('masked  -- ' + masked + ' cells', () => grid(mask, 10, 'miles', true, true))
   .on('cycle', e => console.log(String(e.target)))
   .on('complete', () => {})
   .run();

packages/turf-point-grid/index.d.ts

@@ -3,6 +3,6 @@ import {BBox, Points, Units, Feature, Features} from '@turf/helpers';
 /**
  * http://turfjs.org/docs/#pointgrid
  */
-declare function pointGrid(bbox: BBox | Feature<any> | Features<any>, cellSize: number, units?: Units, centered?: boolean): Points;
+declare function pointGrid(bbox: BBox | Feature<any> | Features<any>, cellSize: number, units?: Units, centered?: boolean, bboxIsMask?: boolean): Points;
 declare namespace pointGrid { }
 export = pointGrid;

packages/turf-point-grid/index.js

@@ -1,6 +1,9 @@
 var distance = require('@turf/distance');
 var turfBBox = require('@turf/bbox');
 var helpers = require('@turf/helpers');
+var inside = require('@turf/inside');
+var invariant = require('@turf/invariant');
+var getGeomType = invariant.getGeomType;
 var point = helpers.point;
 var featureCollection = helpers.featureCollection;
 
@@ -12,6 +15,8 @@ var featureCollection = helpers.featureCollection;
  * @param {number} cellSize the distance across each cell
  * @param {string} [units=kilometers] used in calculating cellSize, can be degrees, radians, miles, or kilometers
  * @param {boolean} [centered=false] adjust points position to center the grid into bbox
+ * @param {boolean} [bboxIsMask=false] if true, and bbox is a Polygon or MultiPolygon, the grid Point will be created
+ * only if inside the bbox Polygon(s)
  * @returns {FeatureCollection<Point>} grid of points
  * @example
  * var extent = [-70.823364, -33.553984, -70.473175, -33.302986];
@@ -23,9 +28,10 @@ var featureCollection = helpers.featureCollection;
  * //addToMap
  * var addToMap = [grid];
  */
-module.exports = function (bbox, cellSize, units, centered) {
+module.exports = function (bbox, cellSize, units, centered, bboxIsMask) {
     var results = [];
 
+    var bboxMask = bbox;
     // validation
     if (!bbox) throw new Error('bbox is required');
     if (!Array.isArray(bbox)) bbox = turfBBox(bbox); // Convert GeoJSON to bbox
@@ -51,13 +57,22 @@ module.exports = function (bbox, cellSize, units, centered) {
         var deltaY = (bboxVerticalSide - rows * cellHeight) / 2;
     }
 
+    var isPoly = !Array.isArray(bboxMask) && (getGeomType(bboxMask) === 'Polygon' || getGeomType(bboxMask) === 'MultiPolygon');
+
     var currentX = west;
     if (centered === true) currentX += deltaX;
     while (currentX <= east) {
         var currentY = south;
         if (centered === true) currentY += deltaY;
         while (currentY <= north) {
-            results.push(point([currentX, currentY]));
+            var pt = point([currentX, currentY]);
+            if (bboxIsMask === true && isPoly) {
+                if (inside(pt, bboxMask)) {
+                    results.push(pt);
+                }
+            } else {
+                results.push(pt);
+            }
             currentY += cellHeight;
         }
         currentX += cellWidth;

packages/turf-point-grid/package.json

@@ -23,6 +23,9 @@
     "geojson"
   ],
   "author": "Turf Authors",
+  "contributors": [
+    "Stefano Borghi <@stebogit>"
+  ],
   "license": "MIT",
   "bugs": {
     "url": "/~https://github.com/Turfjs/turf/issues"
@@ -39,6 +42,8 @@
   "dependencies": {
     "@turf/bbox": "^4.4.0",
     "@turf/distance": "^4.4.0",
-    "@turf/helpers": "^4.4.0"
+    "@turf/helpers": "^4.4.0",
+    "@turf/inside": "^4.4.0",
+    "@turf/invariant": "^4.4.0"
   }
 }

packages/turf-point-grid/test.js

@@ -26,6 +26,7 @@ test('turf-point-grid', t => {
         const grid5 = grid(geojson, 5, 'miles');
         const grid20 = grid(geojson, 20, 'miles');
         const gridCentered = grid(geojson, 12.5, 'miles', true);
+        const gridMasked = grid(geojson, 15, 'miles', true, true);
 
         // Add current GeoJSON to grid results
         featureEach(geojson, feature => {
@@ -37,17 +38,26 @@ test('turf-point-grid', t => {
             grid5.features.push(feature);
             grid20.features.push(feature);
             gridCentered.features.push(feature);
+            gridMasked.features.push(feature);
         });
 
         if (process.env.REGEN) {
             mkdirp.sync(directories.out + name);
             write.sync(path.join(directories.out, name, '5-miles.geojson'), grid5);
             write.sync(path.join(directories.out, name, '20-miles.geojson'), grid20);
             write.sync(path.join(directories.out, name, 'centered.geojson'), gridCentered);
+            write.sync(path.join(directories.out, name, 'masked.geojson'), gridMasked);
         }
         t.deepEqual(grid5, load.sync(path.join(directories.out, name, '5-miles.geojson')), name + ' -- 5 miles');
         t.deepEqual(grid20, load.sync(path.join(directories.out, name, '20-miles.geojson')), name + ' -- 20 miles');
         t.deepEqual(gridCentered, load.sync(path.join(directories.out, name, 'centered.geojson')), name + ' -- centered');
+        t.deepEqual(gridMasked, load.sync(path.join(directories.out, name, 'masked.geojson')), name + ' -- masked');
     }
     t.end();
 });
+
+test('turf-point-grid -- throws', t => {
+    t.throws(() => grid(null, 10), /bbox is required/, 'missing bbox');
+    t.throws(() => grid([-95, 30, 40], 10), /bbox must contain 4 numbers/, 'invalid bbox');
+    t.end();
+});