turf-oriented-envelope: add new function to calculate rotated envelope, fix #2900

.github/workflows/prerelease.yml

@@ -10,7 +10,7 @@ jobs:
       fail-fast: true
       matrix:
         node:
-          - 18
+          - 20
         platform:
           - ubuntu-latest
     name: "${{matrix.platform}} / Node.js ${{ matrix.node }}"

.github/workflows/release.yml

@@ -14,7 +14,7 @@ jobs:
       fail-fast: true
       matrix:
         node:
-          - 18
+          - 20
         platform:
           - ubuntu-latest
     name: "${{matrix.platform}} / Node.js ${{ matrix.node }}"

.github/workflows/turf.yml

@@ -19,7 +19,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [18.x, 20.x, 22.x]
+        node-version: [20.x, 22.x, 24.x]
 
     steps:
       - name: Checkout

documentation.yml

@@ -13,6 +13,7 @@ toc:
     - envelope
     - length
     - midpoint
+    - orientedEnvelope
     - pointOnFeature
     - polygonTangents
     - pointToLineDistance

packages/turf-oriented-envelope/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-oriented-envelope/README.md

@@ -0,0 +1,63 @@
+# @turf/oriented-envelope
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## orientedEnvelope
+
+Takes any number of features and returns a rotated rectangular [Polygon][1] that encompasses all vertices.
+
+Based on the [geojson-minimum-bounding-rectangle][2]
+package by Matthias Feist.
+
+### Parameters
+
+*   `geoJsonInput` **AllGeoJSON**&#x20;
+*   `options` **{minimizeWidth: [boolean][3]?}**  (optional, default `{}`)
+*   `geojson` **[GeoJSON][4]** input features
+
+### Examples
+
+```javascript
+var features = turf.featureCollection([
+  turf.point([-75.343, 39.984], {"name": "Location A"}),
+  turf.point([-75.833, 39.284], {"name": "Location B"}),
+  turf.point([-75.534, 39.123], {"name": "Location C"})
+]);
+
+var enveloped = turf.orientedEnvelope(features);
+
+//addToMap
+var addToMap = [features, enveloped];
+```
+
+Returns **[Feature][5]<[Polygon][1]>** a rotated rectangular Polygon feature that encompasses all vertices
+
+[1]: https://tools.ietf.org/html/rfc7946#section-3.1.6
+
+[2]: https://www.npmjs.com/package/geojson-minimum-bounding-rectangle
+
+[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+
+[4]: https://tools.ietf.org/html/rfc7946#section-3
+
+[5]: https://tools.ietf.org/html/rfc7946#section-3.2
+
+<!-- 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. -->
+
+---
+
+This module is part of the [Turfjs project](https://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 single module individually:
+
+```sh
+$ npm install @turf/oriented-envelope
+```
+
+Or install the all-encompassing @turf/turf module that includes all modules as functions:
+
+```sh
+$ npm install @turf/turf
+```

packages/turf-oriented-envelope/bench.ts

@@ -0,0 +1,21 @@
+import path from "path";
+import { fileURLToPath } from "url";
+import { loadJsonFileSync } from "load-json-file";
+import Benchmark from "benchmark";
+import { orientedEnvelope } from "./index.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const fixture = loadJsonFileSync(
+  path.join(__dirname, "test", "in", "feature-collection.geojson")
+);
+
+var suite = new Benchmark.Suite("turf-envelope");
+suite
+  .add("turf-envelope", function () {
+    orientedEnvelope(fixture);
+  })
+  .on("cycle", function (event) {
+    console.log(String(event.target));
+  })
+  .run();

packages/turf-oriented-envelope/index.ts

@@ -0,0 +1,93 @@
+import { convex } from "@turf/convex";
+import type { AllGeoJSON } from "@turf/helpers";
+import { coordAll } from "@turf/meta";
+import { centroid } from "@turf/centroid";
+import { transformRotate } from "@turf/transform-rotate";
+import { bearing } from "@turf/bearing";
+import { envelope } from "@turf/envelope";
+import { area } from "@turf/area";
+import { distance } from "@turf/distance";
+import type { Feature, Polygon } from "geojson";
+
+/**
+ * Takes any number of features and returns a rotated rectangular {@link Polygon} that encompasses all vertices.
+ *
+ * Based on the [geojson-minimum-bounding-rectangle](https://www.npmjs.com/package/geojson-minimum-bounding-rectangle)
+ * package by Matthias Feist.
+ *
+ * @function
+ * @param {GeoJSON} geojson input features
+ * @param {boolean} [options.minimizeWidth=false] return the oriented envelope with minimal width not minimal area
+ * @returns {Feature<Polygon>} a rotated rectangular Polygon feature that encompasses all vertices
+ * @example
+ * var features = turf.featureCollection([
+ *   turf.point([-75.343, 39.984], {"name": "Location A"}),
+ *   turf.point([-75.833, 39.284], {"name": "Location B"}),
+ *   turf.point([-75.534, 39.123], {"name": "Location C"})
+ * ]);
+ *
+ * var enveloped = turf.orientedEnvelope(features);
+ *
+ * //addToMap
+ * var addToMap = [features, enveloped];
+ */
+function orientedEnvelope(
+  geoJsonInput: AllGeoJSON,
+  options: {
+    minimizeWidth?: boolean;
+  } = {}
+): Feature<Polygon> {
+  const convexHull = convex(geoJsonInput);
+  if (!convexHull) {
+    throw new Error(`Can't calculate orientedEnvelope for given geometry`);
+  }
+
+  const centroidCoords = centroid(convexHull);
+  const allHullCoords = coordAll(convexHull);
+  if (allHullCoords.length < 2) {
+    throw new Error(`Can't calculate orientedEnvelope for given geometry`);
+  }
+
+  let minAngle = 0;
+  let minValue = Number.MAX_SAFE_INTEGER;
+  let resultPolygon = null;
+  let value;
+  let envelopeOfHull;
+
+  for (let index = 0; index < allHullCoords.length - 1; index++) {
+    let angle = bearing(allHullCoords[index], allHullCoords[index + 1]);
+
+    let rotatedHull = transformRotate(convexHull, -1.0 * angle, {
+      pivot: centroidCoords,
+    });
+
+    envelopeOfHull = envelope(rotatedHull);
+
+    if (options.minimizeWidth) {
+      let envelopeCoords = coordAll(envelopeOfHull);
+      let side1 = distance(envelopeCoords[0], envelopeCoords[1]);
+      let side2 = distance(envelopeCoords[1], envelopeCoords[2]);
+      // Use the smaller side as the value for comparison
+      value = Math.min(side1, side2);
+    } else {
+      // Calculate area of the envelope
+      value = area(envelopeOfHull);
+    }
+
+    if (value < minValue) {
+      minAngle = angle;
+    }
+  }
+
+  if (!envelopeOfHull) {
+    throw new Error(`Can't calculate orientedEnvelope for given geometry`);
+  }
+  resultPolygon = transformRotate(envelopeOfHull, minAngle, {
+    pivot: centroidCoords,
+  });
+
+  return resultPolygon;
+}
+
+export { orientedEnvelope };
+export default orientedEnvelope;

packages/turf-oriented-envelope/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@turf/oriented-envelope",
+  "version": "7.2.0",
+  "description": "Takes any number of features and returns a rectangular Polygon that encompasses all vertices.",
+  "author": "Turf Authors",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Turfjs/turf/issues"
+  },
+  "homepage": "https://github.com/Turfjs/turf",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/Turfjs/turf.git"
+  },
+  "funding": "https://opencollective.com/turf",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "turf",
+    "geojson",
+    "envelope",
+    "polygon",
+    "extent"
+  ],
+  "type": "module",
+  "main": "dist/cjs/index.cjs",
+  "module": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.cts",
+        "default": "./dist/cjs/index.cjs"
+      }
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "bench": "tsx bench.ts",
+    "build": "tsup --config ../../tsup.config.ts",
+    "docs": "tsx ../../scripts/generate-readmes.ts",
+    "test": "npm-run-all --npm-path npm test:*",
+    "test:tape": "tsx test.ts"
+  },
+  "devDependencies": {
+    "@types/benchmark": "^2.1.5",
+    "@types/tape": "^5.8.1",
+    "benchmark": "^2.1.4",
+    "load-json-file": "^7.0.1",
+    "npm-run-all": "^4.1.5",
+    "tape": "^5.9.0",
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "@turf/area": "workspace:*",
+    "@turf/bearing": "workspace:*",
+    "@turf/centroid": "workspace:*",
+    "@turf/convex": "workspace:*",
+    "@turf/distance": "workspace:*",
+    "@turf/envelope": "workspace:*",
+    "@turf/helpers": "workspace:*",
+    "@turf/meta": "workspace:*",
+    "@turf/transform-rotate": "workspace:*",
+    "@types/geojson": "^7946.0.10",
+    "tslib": "^2.8.1"
+  }
+}

packages/turf-oriented-envelope/test.ts

@@ -0,0 +1,35 @@
+import path from "path";
+import { fileURLToPath } from "url";
+import test from "tape";
+import { loadJsonFileSync } from "load-json-file";
+import { orientedEnvelope } from "./index.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Fixtures
+const fc = loadJsonFileSync(
+  path.join(__dirname, "test", "in", "feature-collection.geojson")
+);
+
+test("envelope", (t) => {
+  const enveloped = orientedEnvelope(fc);
+  t.ok(
+    enveloped,
+    "should return a polygon that represents the bbox around a feature or feature collection"
+  );
+  t.equal(enveloped.geometry.type, "Polygon");
+  t.deepEqual(
+    enveloped.geometry.coordinates,
+    [
+      [
+        [130, 4.000000000000015],
+        [111.6032944788385, 46.43169359929018],
+        [20, 3.737151750719632e-14],
+        [36.12291669822969, -40.470374533102486],
+        [130, 4.000000000000015],
+      ],
+    ],
+    "positions are correct"
+  );
+  t.end();
+});

packages/turf-oriented-envelope/test/in/feature-collection.geojson

@@ -0,0 +1,42 @@
+{
+  "type": "FeatureCollection",
+  "features": [
+    {
+      "type": "Feature",
+      "geometry": {
+        "type": "Point",
+        "coordinates": [102.0, 0.5]
+      },
+      "properties": {}
+    },
+    {
+      "type": "Feature",
+      "geometry": {
+        "type": "LineString",
+        "coordinates": [
+          [102.0, -10.0],
+          [103.0, 1.0],
+          [104.0, 0.0],
+          [130.0, 4.0]
+        ]
+      },
+      "properties": {}
+    },
+    {
+      "type": "Feature",
+      "geometry": {
+        "type": "Polygon",
+        "coordinates": [
+          [
+            [20.0, 0.0],
+            [101.0, 0.0],
+            [101.0, 1.0],
+            [100.0, 1.0],
+            [100.0, 0.0]
+          ]
+        ]
+      },
+      "properties": {}
+    }
+  ]
+}

packages/turf-oriented-envelope/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../tsconfig.shared.json"
+}