plotboilerplate 1.23.3 → 1.24.0

package/src/ts/Vertex.ts

@@ -33,7 +33,9 @@
  * @modified 2023-09-29 Added the `Vertex.abs()` method as it seems useful.
  * @modified 2024-03-08 Added the optional `precision` param to the `toString` method.
  * @modified 2024-12-17 Outsourced the euclidean distance calculation of `Vertex.distance` to `geomutils.dist4`.
- * @version  2.9.1
+ * @modified 2025-03-24 Making the second parameter `center` of the `Vertex.rotate` method optional.
+ * @modified 2025-04-13 Adding the `Vertex.move(amount: XYCoords)` method (does the same as `add`, added by naming convention).
+ * @version  2.10.0
  *
  * @file Vertex
  * @public
@@ -272,6 +274,22 @@ export class Vertex implements XYCoords, SVGSerializable {
     return this;
   }
 
+  /**
+   * Move this point by the given amount.
+   *
+   * This method just calls `add(amount).
+   *
+   *
+   * @method move
+   * @param {Vertex} amount - The amount to move this vertex.
+   * @return {Vertex} this - For chaining.
+   * @instance
+   * @memberof Vertex
+   */
+  move(amount: XYCoords): Vertex {
+    return this.add(amount);
+  }
+
   /**
    * Add the passed amounts to the x- and y- components of this vertex.
    *
@@ -554,7 +572,7 @@ export class Vertex implements XYCoords, SVGSerializable {
    * @instance
    * @memberof Vertex
    **/
-  rotate(angle: number, center: XYCoords | undefined): Vertex {
+  rotate(angle: number, center?: XYCoords | undefined): Vertex {
     if (!center || typeof center === "undefined") {
       center = { x: 0, y: 0 };
     }

package/src/ts/interfaces/core.ts

@@ -20,6 +20,8 @@
  * @modified 2023-02-10 All non-function attributes of the `Config` interface are now mandatory.
  * @modified 2023-09-29 Added the `randomPoint(...)` function declaration to the IBounds interface.
  * @modified 2024-08-25 Added the `CSSBackdropFilterParams` params to the global params (all optional).
+ * @modified 2025-03-29 Added interface `Intersectable`.
+ * @modified 2025-04-16 Added interface `IBounded`.
  **/
 
 import { Vertex } from "../Vertex";
@@ -37,6 +39,7 @@ import { PlotBoilerplate } from "../PlotBoilerplate";
 import { DrawLib } from "./DrawLib";
 import { PBText } from "../PBText";
 import { CSSBackdropFilterParams } from "./externals";
+import { VertTuple } from "../VertTuple";
 
 /**
  * @classdesc Coordinates (x,y) on the plane.
@@ -261,3 +264,42 @@ export interface IDraggable {
   isVertex(): boolean;
   setVIndex(vindex: number): IDraggable;
 }
+
+/**
+ * Shapes should implement this interface if they support intersection calculation.
+ */
+export interface Intersectable {
+  /**
+   * Get all line intersections with this polygon.
+   *
+   * This method returns all intersections (as vertices) with this shape. The returned array of vertices is in no specific order.
+   *
+   * See demo `47-closest-vector-projection-on-polygon` for how it works.
+   *
+   * @param {VertTuple} line - The line to find intersections with.
+   * @param {boolean} inVectorBoundsOnly - (default=false) If set to true only intersecion points on the passed vector are returned (located strictly between start and end vertex).
+   * @returns {Array<Vertex>} - An array of all intersections within this shape's bounds.
+   */
+  lineIntersections(line: VertTuple<any>, inVectorBoundsOnly?: boolean): Array<Vertex>;
+
+  /**
+   * Get all line intersections of this polygon and their tangents along the shape.
+   *
+   * This method returns all intersection tangents (as vectors) with this shape. The returned array of vectors is in no specific order.
+   *
+   * @param {VertTuple} line - The line to find intersections with.
+   * @param  {boolean} inVectorBoundsOnly - (default=false) If set to true only intersecion points on the passed vector are returned (located strictly between start and end vertex).
+   * @returns {Array<Vector>} - An array of all intersection tangents within this shape's bounds.
+   */
+  lineIntersectionTangents(line: VertTuple<any>, inVectorBoundsOnly?: boolean): Array<Vector>;
+}
+
+export interface IBounded {
+  /**
+   * Get the bounding box (bounds) of this shape.
+   *
+   * @method getBounds
+   * @return {Bounds} The rectangular bounds of this shape.
+   **/
+  getBounds(): IBounds;
+}

package/src/ts/utils/algorithms/convexPolygonIncircle.ts

@@ -1,8 +1,9 @@
-/** 
+/**
  * @author   mbostock, extended and ported to TypeScript by Ikaros Kappler
  * @date     2020-05-19
  * @modified 2021-02-08 Fixed a lot of es2015 compatibility issues.
- * @version  1.0.2
+ * @modified 2024-03-24 Fixing some unstrict types to match with the new Typescript settings.
+ * @version  1.0.3
  * @file     contextPolygonIncircle
  * @public
  */
@@ -14,17 +15,16 @@ import { Polygon } from "../../Polygon";
 import { Triangle } from "../../Triangle";
 import { Vertex } from "../../Vertex";
 
-
 /**
  * For circle-polygon-intersection-count detection we need an epsilon to
  * eliminate smaller precision errors.
  */
-const EPS : number = 0.000001;
+const EPS: number = 0.000001;
 
 export interface PolygonIncircle {
-    circle : Circle;
-    triangle : Triangle;
-};
+  circle: Circle;
+  triangle: Triangle;
+}
 
 /**
  * Compute the max sized inlying circle in the given convex (!) polygon - also called the
@@ -50,54 +50,60 @@ export interface PolygonIncircle {
  * @param {Polygon} convexHull - The actual convex polygon.
  * @return {PolygonIncircle} A pair of a circle (the incircle) and a triangle (the three points where the circle is touching the polygon).
  */
-export const convexPolygonIncircle = ( convexHull:Polygon ) : PolygonIncircle => {
-    var n : number = convexHull.vertices.length;
-    var bestCircle : Circle|undefined = undefined;
-    var bestTriangle : Triangle|undefined = undefined;
-    for( var a = 0; a < n; a++ ) {
-	for( var b = a+1; b < n; b++ ) {
-	    for( var c = b+1; c < n; c++ ) {
-		// As these lines are part of the convex hull, we know that
-		//  * line a preceeds line b and
-		//  * line b preceeds line c :)
-		let lineA : Line = new Line( convexHull.vertices[a], convexHull.vertices[(a+1)%n] );
-		let lineB : Line = new Line( convexHull.vertices[b], convexHull.vertices[(b+1)%n] );
-		let lineC : Line = new Line( convexHull.vertices[c], convexHull.vertices[(c+1)%n] );
-
-		// Find intersections by expanding the lines
-		let vertB : Vertex = lineA.intersection(lineB);
-		let vertC : Vertex = lineB.intersection(lineC);
-
-		// An object: { center: Vertex, radius: number }
-		let triangle : Triangle = getTangentTriangle4( lineA.a, vertB, vertC, lineC.b );
-		// Workaround. There will be a future version where the 'getCircumCircle()' functions
-		// returns a real Circle instance.
-		let _circle : Circle = triangle.getCircumcircle();
-		let circle : Circle = new Circle( _circle.center, _circle.radius );
-
-		// Count the number of intersections with the convex hull:
-		// If there are exactly three, we have found an in-lying circle.
-		//  * Check if this one is better (bigger) than the old one.
-		//  * Also check if the circle is located inside the polygon;
-		//    The construction can, in some cases, produce an out-lying circle.
-		if( !convexHull.containsVert(circle.center) ) {
-		    continue;
-		}
-		var circleIntersections : Array<number> = findCircleIntersections( convexHull, circle );
-		if( circleIntersections.length == 3 && (bestCircle == undefined || bestCircle.radius < circle.radius) ) {
-		    bestCircle = circle;
-		    bestTriangle = triangle;
-		}
-	    }
-	}
+export const convexPolygonIncircle = (convexHull: Polygon): PolygonIncircle => {
+  var n: number = convexHull.vertices.length;
+  var bestCircle: Circle | null = null;
+  var bestTriangle: Triangle | null = null;
+  for (var a = 0; a < n; a++) {
+    for (var b = a + 1; b < n; b++) {
+      for (var c = b + 1; c < n; c++) {
+        // As these lines are part of the convex hull, we know that
+        //  * line a preceeds line b and
+        //  * line b preceeds line c :)
+        let lineA: Line = new Line(convexHull.vertices[a], convexHull.vertices[(a + 1) % n]);
+        let lineB: Line = new Line(convexHull.vertices[b], convexHull.vertices[(b + 1) % n]);
+        let lineC: Line = new Line(convexHull.vertices[c], convexHull.vertices[(c + 1) % n]);
+
+        // Find intersections by expanding the lines
+        let vertB: Vertex | null = lineA.intersection(lineB);
+        let vertC: Vertex | null = lineB.intersection(lineC);
+
+        if (!vertB || !vertC) {
+          continue;
+        }
+
+        // An object: { center: Vertex, radius: number }
+        let triangle: Triangle | null = getTangentTriangle4(lineA.a, vertB, vertC, lineC.b);
+        if (!triangle) {
+          continue;
+        }
+
+        // Workaround. There will be a future version where the 'getCircumCircle()' functions
+        // returns a real Circle instance.
+        let _circle: Circle = triangle.getCircumcircle();
+        let circle: Circle = new Circle(_circle.center, _circle.radius);
+
+        // Count the number of intersections with the convex hull:
+        // If there are exactly three, we have found an in-lying circle.
+        //  * Check if this one is better (bigger) than the old one.
+        //  * Also check if the circle is located inside the polygon;
+        //    The construction can, in some cases, produce an out-lying circle.
+        if (!convexHull.containsVert(circle.center)) {
+          continue;
+        }
+        var circleIntersections: Array<number> = findCircleIntersections(convexHull, circle);
+        if (circleIntersections.length == 3 && (bestCircle == undefined || bestCircle.radius < circle.radius)) {
+          bestCircle = circle;
+          bestTriangle = triangle;
+        }
+      }
     }
-    return { circle : bestCircle,
-	     triangle : bestTriangle };
+  }
+  return { circle: bestCircle as Circle, triangle: bestTriangle as Triangle };
 };
 
-
 /**
- * This function computes the three points for the inner maximum circle 
+ * This function computes the three points for the inner maximum circle
  * lying tangential to the three subsequential lines (given by four points).
  *
  * Compute the circle from that triangle by using Triangle.getCircumcircle().
@@ -114,26 +120,26 @@ export const convexPolygonIncircle = ( convexHull:Polygon ) : PolygonIncircle =>
  * @param {Vertex} vertD - The fourth point of the three connected lines.
  * @return {Triangle} The triangle of the circular tangential points with the given lines (3 or 4 of them).
  */
-const getTangentTriangle4 = ( vertA : Vertex,
-			      vertB : Vertex,
-			      vertC : Vertex,
-			      vertD : Vertex ) : Triangle => {
-    const lineA : Line = new Line(vertA,vertB);
-    const lineB : Line = new Line(vertB,vertC);
-    const lineC : Line = new Line(vertC,vertD);
+const getTangentTriangle4 = (vertA: Vertex, vertB: Vertex, vertC: Vertex, vertD: Vertex): Triangle | null => {
+  const lineA: Line = new Line(vertA, vertB);
+  const lineB: Line = new Line(vertB, vertC);
+  const lineC: Line = new Line(vertC, vertD);
 
-    const bisector1 : Line = geomutils.nsectAngle( vertB, vertA, vertC, 2 )[0]; // bisector of first triangle
-    const bisector2 : Line  = geomutils.nsectAngle( vertC, vertB, vertD, 2 )[0]; // bisector of second triangle
-    const intersection : Vertex = bisector1.intersection( bisector2 );
+  const bisector1: Line = geomutils.nsectAngle(vertB, vertA, vertC, 2)[0]; // bisector of first triangle
+  const bisector2: Line = geomutils.nsectAngle(vertC, vertB, vertD, 2)[0]; // bisector of second triangle
+  const intersection: Vertex | null = bisector1.intersection(bisector2);
 
-    // Find the closest points on one of the polygon lines (all have same distance by construction)
-    const circleIntersA : Vertex = lineA.getClosestPoint( intersection );
-    const circleIntersB : Vertex = lineB.getClosestPoint( intersection );
-    const circleIntersC : Vertex = lineC.getClosestPoint( intersection );
+  if (!intersection) {
+    return null;
+  }
 
-    return new Triangle(circleIntersA, circleIntersB, circleIntersC);
-};
+  // Find the closest points on one of the polygon lines (all have same distance by construction)
+  const circleIntersA: Vertex = lineA.getClosestPoint(intersection);
+  const circleIntersB: Vertex = lineB.getClosestPoint(intersection);
+  const circleIntersC: Vertex = lineC.getClosestPoint(intersection);
 
+  return new Triangle(circleIntersA, circleIntersB, circleIntersC);
+};
 
 /**
  * Find all intersecting lines (indices) on the polyon that intersect the circle.
@@ -142,16 +148,14 @@ const getTangentTriangle4 = ( vertA : Vertex,
  * @param {Circle} circle - The circle to detect the intersections with.
  * @return {Array<number>} The indices of those lines that intersect (or touch) the circle.
  **/
-const findCircleIntersections = ( convexHull:Polygon, circle:Circle ) : Array<number> => {
-    var result = [];
-    for( var i = 0; i < convexHull.vertices.length; i++ ) {
-	var line : Line = new Line( convexHull.vertices[i], convexHull.vertices[(i+1)%convexHull.vertices.length] );
-	// Use an epsilon here because circle coordinates can be kind of unprecise in the detail.
-	if( circle.lineDistance(line) < EPS ) {
-	    result.push( i );
-	}
+const findCircleIntersections = (convexHull: Polygon, circle: Circle): Array<number> => {
+  const result: Array<number> = [];
+  for (var i = 0; i < convexHull.vertices.length; i++) {
+    var line: Line = new Line(convexHull.vertices[i], convexHull.vertices[(i + 1) % convexHull.vertices.length]);
+    // Use an epsilon here because circle coordinates can be kind of unprecise in the detail.
+    if (circle.lineDistance(line) < EPS) {
+      result.push(i);
     }
-    return result;
+  }
+  return result;
 };
-
-

package/src/ts/utils/createRandomizedPolygon.ts

@@ -0,0 +1,31 @@
+/**
+ * A helper function to generate randmoized non-intersecting polygons.
+ *
+ * @author  Ikaros Kappler
+ * @date    2025-03-23 (ported to Typescript from a helper script from 2024)
+ * @version 1.0.0
+ */
+
+import { Bounds } from "../Bounds";
+import { Polygon } from "../Polygon";
+import { Vertex } from "../Vertex";
+
+/**
+ * @param numVertices
+ * @returns
+ */
+
+export const createRandomizedPolygon = (numVertices: number, viewport: Bounds, createClockwise?: boolean) => {
+  const polygon = new Polygon();
+  for (var i = 0; i < numVertices; i++) {
+    const vert = new Vertex(viewport.getMinDimension() * 0.33, 0.0);
+    vert.rotate(((Math.PI * 2) / numVertices) * i);
+    vert.addXY(viewport.width * 0.1 * (1.0 - Math.random() * 2), viewport.height * 0.1 * (1.0 - Math.random() * 2));
+    polygon.addVertex(vert);
+  }
+  if (createClockwise && !polygon.isClockwise()) {
+    // Reverse
+    polygon.vertices = polygon.vertices.reverse();
+  }
+  return polygon;
+};

package/src/ts/utils/helpers/BezierPathInteractionHelper.ts

@@ -22,16 +22,18 @@
  * @modified 2021-03-31 Fixed the issue with the new AlloyFinger (Typescript).
  * @modified 2022-02-03 Changing the element to catch events (eventCatcher instead of canvas).
  * @modified 2024-03-10 Fixing some types for Typescript 5 compatibility.
- * @version  1.1.3
+ * @modified 2025-04-14 Added the `BezierPathInteractionHelper.drawHandleLines` method.
+ * @modified 2025-04-14 Fixing correct event types for touch events in `BezierPathInteractionHelper`.
+ * @modified 2025-04-14 BezierPathInteractionHelper: Changed default value of `HelperOptions.autoAdjustPaths` from `true` to `false`.
+ * @version  1.2.0
  *
  * @file BezierPathInteractionHelper
  * @public
  **/
 
-// import { AlloyFinger } from "alloyfinger"; // node_modules
 // I would like to use AlloyFinger from the node_modules, but it seems
 // AlloyTeam has forgotten to publish their d.ts file.
-import { AlloyFinger } from "../../../../lib/alloy_finger";
+import AlloyFinger from "alloyfinger-typescript";
 import { BezierPath } from "../../BezierPath";
 import { CubicBezierCurve } from "../../CubicBezierCurve";
 import { KeyHandler } from "../../KeyHandler";
@@ -40,7 +42,8 @@ import { PlotBoilerplate } from "../../PlotBoilerplate";
 import { VertListener } from "../../VertexListeners";
 import { Vertex } from "../../Vertex";
 import { XMouseEvent } from "../../MouseHandler";
-import { XYCoords } from "../../interfaces";
+import { DrawLib, XYCoords } from "../../interfaces";
+import { AFTouchEvent } from "alloyfinger-typescript/src/cjs/alloy_finger";
 
 /**
  * Handler type for mouse-pointer-moved listeners.
@@ -153,7 +156,9 @@ export class BezierPathInteractionHelper {
     this.pb = pb;
     this.paths = [];
     this.onPointerMoved =
-      typeof options.onPointerMoved === "function" ? options.onPointerMoved : (i: number, a: Vertex | null, b: Vertex | null, t: number) => {};
+      typeof options.onPointerMoved === "function"
+        ? options.onPointerMoved
+        : (i: number, a: Vertex | null, b: Vertex | null, t: number) => {};
     this.onVertexInserted =
       typeof options.onVertexInserted === "function"
         ? options.onVertexInserted
@@ -163,7 +168,7 @@ export class BezierPathInteractionHelper {
         ? options.onVerticesDeleted
         : (i: number, r: Array<number>, n: BezierPath, o: BezierPath) => {};
     this.onPathRemoved = typeof options.onPathRemoved === "function" ? options.onPathRemoved : (i: number, o: BezierPath) => {};
-    this.autoAdjustPaths = typeof options.autoAdjustPaths === "boolean" ? options.autoAdjustPaths : true;
+    this.autoAdjustPaths = typeof options.autoAdjustPaths === "boolean" ? options.autoAdjustPaths : false; // true;
     this.allowPathRemoval = typeof options.allowPathRemoval === "boolean" ? options.allowPathRemoval : true;
     this.maxDetectDistance = typeof options.maxDetectDistance === "number" ? options.maxDetectDistance : Number.MAX_VALUE;
 
@@ -192,7 +197,9 @@ export class BezierPathInteractionHelper {
     this._keyHandler = this._installKeyListener();
 
     // Paths might have changed by auto-adjustment.
-    if (this.autoAdjustPaths) pb.redraw();
+    if (this.autoAdjustPaths) {
+      pb.redraw();
+    }
   }
 
   /**
@@ -263,6 +270,24 @@ export class BezierPathInteractionHelper {
     this._handleMoveEvent(this.currentB.x, this.currentB.y);
   }
 
+  /**
+   * Draw grey handle lines.
+   *
+   */
+  drawHandleLines() {
+    this.paths.forEach((path: BezierPath) => {
+      path.bezierCurves.forEach((curve: CubicBezierCurve) => {
+        this.pb.draw.line(curve.startPoint, curve.startControlPoint, "rgba(64,192,128,0.333)", 1.0, {
+          dashOffset: 0.0,
+          dashArray: [4, 2]
+        });
+        this.pb.draw.line(curve.endPoint, curve.endControlPoint, "rgba(64,192,128,0.333)", 1.0, {
+          dashOffset: 0.0,
+          dashArray: [4, 2]
+        });
+      });
+    });
+  }
   /**
    * This function should invalidate any installed listeners and invalidate this object.
    * After calling this function the object might not hold valid data any more and
@@ -438,22 +463,31 @@ export class BezierPathInteractionHelper {
     var _self: BezierPathInteractionHelper = this;
     const afProps = {
       // Todo: which event types does AlloyFinger use?
-      touchStart: function (_event: TouchEvent) {
+      // touchStart: function (_event: TouchEvent) {
+      //   _self.mouseIsOver = true;
+      // },
+      // /* TouchMoveEvent , AFTouchEvent<"touchStart"> */
+      touchStart: function (_event: AFTouchEvent<"touchStart">) {
         _self.mouseIsOver = true;
       },
-      touchMove: function (event: TouchEvent) {
+      touchMove: function (event: AFTouchEvent<"touchMove">) {
+        // TouchEvent) {
         if (_self.pb.getDraggedElementCount() == 0 && event.touches.length > 0) {
           // console.log('touchmove');
           _self._handleMoveEvent(event.touches[0].clientX, event.touches[0].clientY);
         }
       },
-      touchEnd: function (_event: TouchEvent) {
+      touchEnd: function (_event: AFTouchEvent<"touchEnd">) {
+        // TouchEvent) {
         _self.mouseIsOver = false;
         _self._clearMoveEvent();
       }
     };
     if (window["createAlloyFinger" as keyof Object]) {
-      return (window["createAlloyFinger" as keyof Object] as any)(this.pb.eventCatcher ? this.pb.eventCatcher : this.pb.eventCatcher, afProps);
+      return (window["createAlloyFinger" as keyof Object] as any)(
+        this.pb.eventCatcher ? this.pb.eventCatcher : this.pb.eventCatcher,
+        afProps
+      );
     } else {
       return new AlloyFinger(this.pb.eventCatcher ? this.pb.eventCatcher : this.pb.eventCatcher, afProps);
     }
@@ -578,24 +612,6 @@ export class BezierPathInteractionHelper {
     path.updateArcLengths();
   }
 
-  /**
-   * A helper function to add drag-start-listener to given vertices.
-   */
-  /* private static _addVertsDragStartListener( verts:Array<Vertex>, dragStartListener:VertListener ) : void {
-	for( var i in verts ) {
-	    verts[i].addDragStartListener( dragStartListener );
-	}
-    }; */
-
-  /**
-   * A helper function to remove drag-start-listener to given vertices.
-   */
-  /* private static _removeVertsDragStartListener( verts:Array<Vertex>, dragEndListener:VertListener ) : void {
-	for( var i in verts ) {
-	    verts[i].removeDragStartListener( dragStartListener );
-	}
-    }; */
-
   /**
    * A helper function to add drag-start listeners to all vertices of the given path.
    *