Added bbox parameter to @turf/interpolate (#2768)

Expands the interpolation field beyond the default bbox of the input data points.
Turfjs · Dec 16, 2024 · 8f5c407 · 8f5c407
1 parent bf588dd
commit 8f5c407
Show file tree

Hide file tree

Showing 9 changed files with 148,156 additions and 5 deletions.
diff --git a/packages/turf-interpolate/README.md b/packages/turf-interpolate/README.md
@@ -16,6 +16,7 @@ Takes a set of points and estimates their 'property' values on a grid using the
     *   `options.property` **[string][6]** the property name in `points` from which z-values will be pulled, zValue fallbacks to 3rd coordinate if no property exists. (optional, default `'elevation'`)
     *   `options.units` **[string][6]** used in calculating cellSize, can be degrees, radians, miles, or kilometers (optional, default `'kilometers'`)
     *   `options.weight` **[number][4]** exponent regulating the distance-decay weighting (optional, default `1`)
+    *   `options.bbox` **[BBox][7]** Bounding Box Array \[west, south, east, north] associated with the FeatureCollection. (optional, default `bbox(points)`)
 
 ### Examples
 
@@ -33,7 +34,7 @@ var grid = turf.interpolate(points, 100, options);
 var addToMap = [grid];
 ```
 
-Returns **[FeatureCollection][2]<([Point][3] | [Polygon][7])>** grid of points or polygons with interpolated 'property'
+Returns **[FeatureCollection][2]<([Point][3] | [Polygon][8])>** grid of points or polygons with interpolated 'property'
 
 [1]: https://en.wikipedia.org/wiki/Inverse_distance_weighting
 
@@ -47,7 +48,9 @@ Returns **[FeatureCollection][2]<([Point][3] | [Polygon][7])>** grid of points o
 
 [6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
 
-[7]: https://tools.ietf.org/html/rfc7946#section-3.1.6
+[7]: https://tools.ietf.org/html/rfc7946#section-5
+
+[8]: https://tools.ietf.org/html/rfc7946#section-3.1.6
 
 <!-- This file is automatically generated. Please don't edit it directly. If you find an error, edit the source file of the module in question (likely index.js or index.ts), and re-run "yarn docs" from the root of the turf project. -->
 

diff --git a/packages/turf-interpolate/index.d.ts b/packages/turf-interpolate/index.d.ts
@@ -1,4 +1,4 @@
-import { Point, Polygon, FeatureCollection } from "geojson";
+import { Point, Polygon, FeatureCollection, BBox } from "geojson";
 import { Units, Grid } from "@turf/helpers";
 
 /**
@@ -12,6 +12,7 @@ declare function interpolate(
     property?: string;
     units?: Units;
     weight?: number;
+    bbox?: BBox;
   }
 ): FeatureCollection<Point>;
 declare function interpolate(
@@ -22,6 +23,7 @@ declare function interpolate(
     property?: string;
     units?: Units;
     weight?: number;
+    bbox?: BBox;
   }
 ): FeatureCollection<Polygon>;
 

diff --git a/packages/turf-interpolate/index.js b/packages/turf-interpolate/index.js
@@ -6,7 +6,7 @@ import { centroid } from "@turf/centroid";
 import { squareGrid } from "@turf/square-grid";
 import { triangleGrid } from "@turf/triangle-grid";
 import { clone } from "@turf/clone";
-import { featureCollection } from "@turf/helpers";
+import { featureCollection, validateBBox } from "@turf/helpers";
 import { featureEach } from "@turf/meta";
 import { collectionOf } from "@turf/invariant";
 
@@ -21,6 +21,7 @@ import { collectionOf } from "@turf/invariant";
  * @param {string} [options.property='elevation'] the property name in `points` from which z-values will be pulled, zValue fallbacks to 3rd coordinate if no property exists.
  * @param {string} [options.units='kilometers'] used in calculating cellSize, can be degrees, radians, miles, or kilometers
  * @param {number} [options.weight=1] exponent regulating the distance-decay weighting
+ * @param {BBox}   [options.bbox=bbox(points)] Bounding Box Array [west, south, east, north] associated with the FeatureCollection.
  * @returns {FeatureCollection<Point|Polygon>} grid of points or polygons with interpolated 'property'
  * @example
  * var points = turf.randomPoint(30, {bbox: [50, 30, 70, 50]});
@@ -42,6 +43,7 @@ function interpolate(points, cellSize, options) {
   var gridType = options.gridType;
   var property = options.property;
   var weight = options.weight;
+  var box = options.bbox;
 
   // validation
   if (!points) throw new Error("points is required");
@@ -55,7 +57,8 @@ function interpolate(points, cellSize, options) {
   gridType = gridType || "square";
   weight = weight || 1;
 
-  var box = bbox(points);
+  box = box ?? bbox(points);
+  validateBBox(box);
   var grid;
   switch (gridType) {
     case "point":

diff --git a/packages/turf-interpolate/test/in/data-1km-bbox.geojson b/packages/turf-interpolate/test/in/data-1km-bbox.geojson
@@ -0,0 +1,62 @@
+{
+  "type": "FeatureCollection",
+  "properties": {
+    "property": "value",
+    "gridType": "square",
+    "weight": 0.5,
+    "cellSize": 1,
+    "bbox": [9.416249084472656, 45.3391764115696, 9.031605529785156, 45.63689620055365]
+  },
+  "features": [
+    {
+      "type": "Feature",
+      "properties": {
+        "value": 4
+      },
+      "geometry": {
+        "type": "Point",
+        "coordinates": [9.155731201171875, 45.47216977418841]
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": {
+        "value": 99
+      },
+      "geometry": {
+        "type": "Point",
+        "coordinates": [9.195213317871094, 45.53689620055365]
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": {
+        "value": 10
+      },
+      "geometry": {
+        "type": "Point",
+        "coordinates": [9.175300598144531, 45.49912810913339]
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": {
+        "value": 6
+      },
+      "geometry": {
+        "type": "Point",
+        "coordinates": [9.231605529785156, 45.49190839157102]
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": {
+        "value": 7
+      },
+      "geometry": {
+        "type": "Point",
+        "coordinates": [9.116249084472656, 45.4391764115696]
+      }
+    }
+  ]
+}
diff --git a/packages/turf-interpolate/test/in/data-500m-bbox.geojson b/packages/turf-interpolate/test/in/data-500m-bbox.geojson
@@ -0,0 +1,63 @@
+{
+  "type": "FeatureCollection",
+  "properties": {
+    "property": "value",
+    "weight": 0.5,
+    "gridType": "square",
+    "cellSize": 0.5,
+    "units": "kilometers",
+    "bbox": [9.416249084472656, 45.3391764115696, 9.031605529785156, 45.63689620055365]
+  },
+  "features": [
+    {
+      "type": "Feature",
+      "properties": {
+        "value": 4
+      },
+      "geometry": {
+        "type": "Point",
+        "coordinates": [9.155731201171875, 45.47216977418841]
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": {
+        "value": 99
+      },
+      "geometry": {
+        "type": "Point",
+        "coordinates": [9.195213317871094, 45.53689620055365]
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": {
+        "value": 10
+      },
+      "geometry": {
+        "type": "Point",
+        "coordinates": [9.175300598144531, 45.49912810913339]
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": {
+        "value": 6
+      },
+      "geometry": {
+        "type": "Point",
+        "coordinates": [9.231605529785156, 45.49190839157102]
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": {
+        "value": 7
+      },
+      "geometry": {
+        "type": "Point",
+        "coordinates": [9.116249084472656, 45.4391764115696]
+      }
+    }
+  ]
+}
diff --git a/packages/turf-interpolate/test/in/hex-zValue-bbox.geojson b/packages/turf-interpolate/test/in/hex-zValue-bbox.geojson
@@ -0,0 +1,52 @@
+{
+  "type": "FeatureCollection",
+  "properties": {
+    "weight": 2,
+    "gridType": "hex",
+    "cellSize": 0.5,
+    "units": "miles",
+    "bbox": [-6.357258206107161, 53.39023949422162, -6.186614219650437, 53.31219701461626]
+  },
+  "features": [
+    {
+      "type": "Feature",
+      "properties": {},
+      "geometry": {
+        "type": "Point",
+        "coordinates": [-6.3288116455078125, 53.355879304922276, 2]
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": {},
+      "geometry": {
+        "type": "Point",
+        "coordinates": [-6.2615203857421875, 53.38087096356977, 5]
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": {},
+      "geometry": {
+        "type": "Point",
+        "coordinates": [-6.248474121093749, 53.31979992850456, 14]
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": {},
+      "geometry": {
+        "type": "Point",
+        "coordinates": [-6.2697601318359375, 53.352190769802725, 9]
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": {},
+      "geometry": {
+        "type": "Point",
+        "coordinates": [-6.2505340576171875, 53.3648943803576, 11]
+      }
+    }
+  ]
+}