docs(geom-clip-line): add docs, update readme

thi-ng · Jan 4, 2023 · 2b9a11b · 2b9a11b
1 parent c00cedd
commit 2b9a11b
Show file tree

Hide file tree

Showing 3 changed files with 74 additions and 25 deletions.
diff --git a/packages/geom-clip-line/README.md b/packages/geom-clip-line/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
 
@@ -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
 
-&copy; 2013 - 2022 Karsten Schmidt // Apache License 2.0
+&copy; 2013 - 2023 Karsten Schmidt // Apache License 2.0
diff --git a/packages/geom-clip-line/src/clip-poly.ts b/packages/geom-clip-line/src/clip-poly.ts
@@ -5,13 +5,18 @@ import type { ReadonlyVec, Vec } from "@thi.ng/vectors";
 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: ReadonlyVec,
@@ -27,6 +32,14 @@ export const clipLinePoly = (
 	return isecs ? collectSegments(<Vec[]>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: ReadonlyVec,
 	b: ReadonlyVec,

diff --git a/packages/geom-clip-line/tpl.readme.md b/packages/geom-clip-line/tpl.readme.md
@@ -6,11 +6,17 @@
 
 {{pkg.description}}
 
-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)
 
 {{meta.status}}
 
@@ -36,12 +42,24 @@ This package has been extracted from the former (now obsolete)
 
 {{pkg.docs}}
 
-- `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],