@thi.ng/geom-clip-line 2.2.3 → 2.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-12-22T21:47:07Z
+- **Last updated**: 2023-01-10T15:20:18Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,12 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [2.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/geom-clip-line@2.3.0) (2023-01-10)
+
+#### 🚀 Features
+
+- add clipPolylineWith() ([372db85](https://github.com/thi-ng/umbrella/commit/372db85))
+
 ## [2.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/geom-clip-line@2.2.0) (2022-12-10)
 
 #### 🚀 Features

package/README.md

@@ -22,11 +22,17 @@ This project is part of the
 
 2D line clipping (Liang-Barsky). This is a support package for [@thi.ng/geom](https://github.com/thi-ng/umbrella/tree/develop/packages/geom).
 
-Current implementation is based on [toxiclibs](http://toxiclibs.org)
-(Java) and Clojure version [thi.ng/geom-clj](http://thi.ng/geom-clj).
+Current implementation is partially based on [toxiclibs](http://toxiclibs.org)
+(Java) and Clojure version [thi.ng/geom-clj](http://thi.ng/geom-clj). Also see
+[@thi.ng/geom-clip-poly](https://github.com/thi-ng/umbrella/blob/develop/packages/geom-clip-poly)
+sister package.
 
-This package has been extracted from the former (now obsolete)
-@thi.ng/geom-clip package.
+The following main functions are provided:
+
+- [`clipLinePoly()`](https://docs.thi.ng/umbrella/geom-clip-line/functions/clipLinePoly.html)
+- [`clipLineSegmentPoly()`](https://docs.thi.ng/umbrella/geom-clip-line/functions/clipLineSegmentPoly.html)
+- [`clipPolylinePoly()`](https://docs.thi.ng/umbrella/geom-clip-line/functions/clipPolylinePoly.html)
+- [`liangBarsky2()`](https://docs.thi.ng/umbrella/geom-clip-line/functions/liangBarsky2.html)
 
 ## Status
 
@@ -58,7 +64,7 @@ For Node.js REPL:
 const geomClipLine = await import("@thi.ng/geom-clip-line");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 661 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 757 bytes
 
 ## Dependencies
 
@@ -70,12 +76,24 @@ Package sizes (brotli'd, pre-treeshake): ESM: 661 bytes
 
 [Generated API docs](https://docs.thi.ng/umbrella/geom-clip-line/)
 
-- `liangBarsky2`
-- `liangBarksy2Raw`
-
 ```ts
-import { liangBarsky2 } from "@thi.ng/geom-clip-line";
-
+import { clipPolylinePoly, liangBarsky2 } from "@thi.ng/geom-clip-line";
+
+clipPolylinePoly(
+    // polyline vertices
+    [[10, -50], [30, 30], [-50, 50], [150, 50], [70, 70], [90, 150]],
+    // boundary polygon vertices
+    [[0, 0], [100, 0], [100, 100], [0, 100]]
+);
+// result is 3 polylines:
+// (since the original is temporarily leaving the poly)
+// [
+//   [ [ 22.5, 0 ], [ 30, 30 ], [ 0, 37.5 ] ],
+//   [ [ 0, 50 ], [ 100, 50 ] ],
+//   [ [ 100, 62.5 ], [ 70, 70 ], [ 77.5, 100 ] ]
+// ]
+
+// Liang-Barsky is optimized for rectangular clipping regions
 liangBarsky2(
     // line end points
     [-10, -20], [30, 400],
@@ -111,4 +129,4 @@ If this project contributes to an academic publication, please cite it as:
 
 ## License
 
-© 2013 - 2022 Karsten Schmidt // Apache License 2.0
+© 2013 - 2023 Karsten Schmidt // Apache License 2.0

package/clip-poly.d.ts

@@ -1,14 +1,27 @@
 import type { ReadonlyVec, Vec } from "@thi.ng/vectors";
 /**
- * Computes all intersection points of the infinite line defined by `a`,
- * `b` with the given polygon. Returns an array of segments where the
- * line is inside the polygon.
+ * Computes all intersection points of the **infinite** line defined by `a`, `b`
+ * with the given polygon. Returns an array of segments where the line is inside
+ * the polygon.
  *
- * @param a -
- * @param b -
- * @param poly -
+ * @remarks
+ * "Infinite" here means the line extends indefinitely on either side and
+ * intersections are found also outside the segment a..b. If only intra-segment
+ * intersections are desired, use {@link clipLineSegmentPoly} instead.
+ *
+ * @param a
+ * @param b
+ * @param poly
  */
 export declare const clipLinePoly: (a: ReadonlyVec, b: ReadonlyVec, poly: ReadonlyVec[]) => Vec[][] | undefined;
+/**
+ * Similar to {@link clipLinePoly}, but only considers intersections within the
+ * given line segment.
+ *
+ * @param a
+ * @param b
+ * @param poly
+ */
 export declare const clipLineSegmentPoly: (a: ReadonlyVec, b: ReadonlyVec, poly: ReadonlyVec[]) => Vec[][] | undefined;
 /**
  * Similar to {@link clipLineSegmentPoly}, but for polylines. Returns array of

package/clip-poly.js

@@ -3,18 +3,31 @@ import { pointInPolygon2 } from "@thi.ng/geom-isec/point";
 import { intersectRayPolylineAll } from "@thi.ng/geom-isec/ray-poly";
 import { direction2 } from "@thi.ng/vectors/direction";
 /**
- * Computes all intersection points of the infinite line defined by `a`,
- * `b` with the given polygon. Returns an array of segments where the
- * line is inside the polygon.
+ * Computes all intersection points of the **infinite** line defined by `a`, `b`
+ * with the given polygon. Returns an array of segments where the line is inside
+ * the polygon.
  *
- * @param a -
- * @param b -
- * @param poly -
+ * @remarks
+ * "Infinite" here means the line extends indefinitely on either side and
+ * intersections are found also outside the segment a..b. If only intra-segment
+ * intersections are desired, use {@link clipLineSegmentPoly} instead.
+ *
+ * @param a
+ * @param b
+ * @param poly
  */
 export const clipLinePoly = (a, b, poly) => {
     const isecs = intersectRayPolylineAll(a, direction2([], a, b), poly, true).isec;
     return isecs ? collectSegments(isecs) : undefined;
 };
+/**
+ * Similar to {@link clipLinePoly}, but only considers intersections within the
+ * given line segment.
+ *
+ * @param a
+ * @param b
+ * @param poly
+ */
 export const clipLineSegmentPoly = (a, b, poly) => {
     const isecs = intersectLinePolylineAll(a, b, poly, true).isec;
     const isAInside = pointInPolygon2(a, poly);

package/clip-with.d.ts

@@ -0,0 +1,41 @@
+import type { Predicate2 } from "@thi.ng/api";
+import type { ReadonlyVec } from "@thi.ng/vectors";
+/**
+ * Segments given polyline based on given predicate and `step` size. Returns
+ * array of segmented vertex chunks.
+ *
+ * @remarks
+ * Vertices are processed pairwise using given `step` size (default: 1). As long
+ * as the predicate is true, vertices are collected into the current chunk. If
+ * the predicate returns false, the current chunk is terminated and depending on
+ * `keepLast`, the current vertex (i.e. for which the predicate failed) is still
+ * added or not. If `keepLast` is false and the current chunk only included one
+ * other vertex, that entire chunk will be discarded.
+ *
+ * @example
+ * ```ts
+ * const pts = [[0, 0], [1, 0], [1, 1], [2, 1], [3, 1], [4, 0], [5, 0]];
+ *
+ * // isolate horizontal chunks
+ * clipPolylineWith((a, b) => a[1] == b[1], pts)
+ * // [
+ * //   [[0, 0], [1, 0]],
+ * //   [[1, 1], [2, 1], [3, 1]],
+ * //   [[4, 0], [5, 0]]
+ * // ]
+ *
+ * // isolate sloped chunks
+ * clipPolylineWith((a, b) => a[1] != b[1], pts)
+ * // [
+ * //   [[1, 0], [1, 1]],
+ * //   [[3, 1], [4, 0]]
+ * // ]
+ * ```
+ *
+ * @param pred
+ * @param pts
+ * @param step
+ * @param keepLast
+ */
+export declare const clipPolylineWith: (pred: Predicate2<ReadonlyVec>, pts: ReadonlyVec[], step?: number, keepLast?: boolean) => ReadonlyVec[][];
+//# sourceMappingURL=clip-with.d.ts.map

package/clip-with.js

@@ -0,0 +1,68 @@
+/**
+ * Segments given polyline based on given predicate and `step` size. Returns
+ * array of segmented vertex chunks.
+ *
+ * @remarks
+ * Vertices are processed pairwise using given `step` size (default: 1). As long
+ * as the predicate is true, vertices are collected into the current chunk. If
+ * the predicate returns false, the current chunk is terminated and depending on
+ * `keepLast`, the current vertex (i.e. for which the predicate failed) is still
+ * added or not. If `keepLast` is false and the current chunk only included one
+ * other vertex, that entire chunk will be discarded.
+ *
+ * @example
+ * ```ts
+ * const pts = [[0, 0], [1, 0], [1, 1], [2, 1], [3, 1], [4, 0], [5, 0]];
+ *
+ * // isolate horizontal chunks
+ * clipPolylineWith((a, b) => a[1] == b[1], pts)
+ * // [
+ * //   [[0, 0], [1, 0]],
+ * //   [[1, 1], [2, 1], [3, 1]],
+ * //   [[4, 0], [5, 0]]
+ * // ]
+ *
+ * // isolate sloped chunks
+ * clipPolylineWith((a, b) => a[1] != b[1], pts)
+ * // [
+ * //   [[1, 0], [1, 1]],
+ * //   [[3, 1], [4, 0]]
+ * // ]
+ * ```
+ *
+ * @param pred
+ * @param pts
+ * @param step
+ * @param keepLast
+ */
+export const clipPolylineWith = (pred, pts, step = 1, keepLast = true) => {
+    const segs = [];
+    let last = -1;
+    const $terminate = (i) => {
+        if (last !== -1) {
+            if (keepLast) {
+                segs[segs.length - 1].push(pts[i]);
+            }
+            else if (segs[segs.length - 1].length < 2) {
+                segs.pop();
+            }
+        }
+        last = -1;
+    };
+    for (let i = 0, n = pts.length - step; i < n; i++) {
+        if (pred(pts[i], pts[i + step])) {
+            if (last === -1) {
+                segs.push([pts[i]]);
+                last = i;
+            }
+            else {
+                segs[segs.length - 1].push(pts[i]);
+            }
+        }
+        else {
+            $terminate(i);
+        }
+    }
+    $terminate(pts.length - step);
+    return segs;
+};

package/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./clip-poly.js";
+export * from "./clip-with.js";
 export * from "./liang-barsky.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,2 +1,3 @@
 export * from "./clip-poly.js";
+export * from "./clip-with.js";
 export * from "./liang-barsky.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/geom-clip-line",
-  "version": "2.2.3",
+  "version": "2.3.0",
   "description": "2D line clipping (Liang-Barsky)",
   "type": "module",
   "module": "./index.js",
@@ -34,13 +34,13 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.6.2",
-    "@thi.ng/geom-isec": "^2.1.40",
-    "@thi.ng/vectors": "^7.5.29"
+    "@thi.ng/api": "^8.6.3",
+    "@thi.ng/geom-isec": "^2.1.42",
+    "@thi.ng/vectors": "^7.5.31"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.33.7",
-    "@thi.ng/testament": "^0.3.8",
+    "@thi.ng/testament": "^0.3.9",
     "rimraf": "^3.0.2",
     "tools": "^0.0.1",
     "typedoc": "^0.23.22",
@@ -73,6 +73,9 @@
     "./clip-poly": {
       "default": "./clip-poly.js"
     },
+    "./clip-with": {
+      "default": "./clip-with.js"
+    },
     "./liang-barsky": {
       "default": "./liang-barsky.js"
     }
@@ -84,5 +87,5 @@
     ],
     "year": 2013
   },
-  "gitHead": "bc6f7f5e2765bb96fe64db804eaf4b2443b47fc6\n"
+  "gitHead": "3f0b3e2a7c82aefc7e46fb4338369836b5e1b8cf\n"
 }