plotboilerplate 1.23.3 → 1.25.0

package/src/ts/Vertex.ts

@@ -33,7 +33,10 @@
  * @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).
+ * @modified 2025-05-07 Class `Vertex` is now implementing interface `IBounded` (to meet convention).
+ * @version  2.11.0
  *
  * @file Vertex
  * @public
@@ -42,8 +45,9 @@
 import { IVertexAttr, VertexAttr } from "./VertexAttr";
 import { UIDGenerator } from "./UIDGenerator";
 import { VertexListeners } from "./VertexListeners";
-import { XYCoords, SVGSerializable, UID } from "./interfaces";
+import { XYCoords, SVGSerializable, UID, IBounded } from "./interfaces";
 import { geomutils } from "./geomutils";
+import { Bounds } from "./Bounds";
 
 /**
  * @classdesc A vertex is a pair of two numbers.<br>
@@ -59,7 +63,7 @@ import { geomutils } from "./geomutils";
  * @requires XYCoords
  *
  */
-export class Vertex implements XYCoords, SVGSerializable {
+export class Vertex implements IBounded, XYCoords, SVGSerializable {
   private static readonly ZERO = new Vertex(0, 0);
 
   /**
@@ -272,6 +276,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 +574,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 };
     }
@@ -627,6 +647,22 @@ export class Vertex implements XYCoords, SVGSerializable {
     return this;
   }
 
+  //--- BEGIN --- Implement interface `IBounded`
+  /**
+   * Get the bounding box (bounds) of this Vertex.
+   * This is just by convention – any vertex is just a position without any useful with or height (0).
+   *
+   * @method getBounds
+   * @instance
+   * @memberof Vertex
+   * @return {Bounds} The rectangular bounds of this Vertex (width and height are zero).
+   **/
+  getBounds(): Bounds {
+    // return Bounds.computeFromVertices([this.a, this.b, this.c]);
+    return Bounds.computeFromVertices([this]);
+  }
+  //--- END --- Implement interface `IBounded`
+
   /**
    * Get a string representation of this vertex.
    *

package/src/ts/interfaces/core.ts

@@ -20,6 +20,10 @@
  * @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`.
+ * @modified 2025-05-07 Added callback `onContentChanged` to PB to track if the drawable content changed.
+ * @modified 2025-06-07 Adding helper type `PolygonIntersectionTuple` for re-usability.
  **/
 
 import { Vertex } from "../Vertex";
@@ -37,6 +41,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.
@@ -111,6 +116,18 @@ export interface CanvasWrapper {
   setSize: (width: number, height: number) => void;
   element: HTMLCanvasElement | SVGElement;
 }
+
+/**
+ * The interface for PB change events.
+ */
+export interface IPBChangeEvent {
+  type: "DRAWABLES_ADDED" | "DRAWABLES_REMOVED";
+  addedDrawables: Array<Drawable>;
+  removedDrawables: Array<Drawable>;
+}
+
+export type PBContentChangeListener = (event: IPBChangeEvent) => void; // A callback function that will be triggered after content changed.
+
 /**
  * The config that's used by PB.
  */
@@ -261,3 +278,59 @@ 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;
+}
+
+export interface IShapeInteractionHelper {
+  /**
+   * Let this shape helper draw it's handle lines. It's up to the helper what they look like.
+   * @param {DrawLib<any>} draw - The draw library to use.
+   * @param {DrawLib<any>} fill - The fill library to use.
+   */
+  drawHandleLines(draw: DrawLib<any>, fill: DrawLib<any>): void;
+
+  /**
+   * Destroys this helper. This means that all listeners get released and this helper
+   * will not receive or handle any events.
+   */
+  destroy(): void;
+}
+
+export type PolygonIntersectionTuple<T> = { edgeIndex: number; intersection: T };

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;
+};