plotboilerplate 1.23.2 → 1.24.0

package/src/ts/VertTuple.ts

@@ -10,7 +10,13 @@
  * @modified 2021-01-20 Added UID.
  * @modified 2022-02-02 Added the `destroy` method.
  * @modified 2023-09-29 Fixed a calculation error in the VertTuple.hasPoint() function; distance measure was broken!
- * @version 1.2.1
+ * @modified 2024-09-10 Chaging the first param of `pointDistance` from `Vertex` to less strict type `XYCoords`. This should not break anything.
+ * @modified 2024-09-10 Adding the optional `epsilon` param to the `hasPoint` method.
+ * @modified 2024-12-02 Added the `epsilon` param to the `colinear` method. Default is 1.0e-6.
+ * @modified 2025-03-31 Added the `VertTuple.revert` method.
+ * @modified 2025-04-15 Changed param of `VertTuple.moveTo` method from `Vertex` to `XYCoords`.
+ * @modified 2025-04-15 Added method `VertTuple.move` method.
+ * @version 1.4.0
  */
 
 import { Vertex } from "./Vertex";
@@ -121,9 +127,9 @@ export class VertTuple<T extends VertTuple<T>> {
    *
    * @method add
    * @param {XYCoords} amount The amount (x,y) to add.
-   * @return {Line} this
    * @instance
    * @memberof VertTuple
+   * @return {VertTuple<T>} this
    **/
   add(amount: XYCoords): VertTuple<T> {
     this.a.add(amount);
@@ -131,6 +137,23 @@ export class VertTuple<T extends VertTuple<T>> {
     return this;
   }
 
+  /**
+   * Reverse this vertex tuple: a becomes b, and b becomes a.
+   * This operation is in-place.
+   *
+   * @method add
+   * @param {XYCoords} amount The amount (x,y) to add.
+   * @instance
+   * @memberof VertTuple
+   * @return {VertTuple<T>} this
+   */
+  revert(): VertTuple<T> {
+    const tmp: Vertex = this.a;
+    this.a = this.b;
+    this.b = tmp;
+    return this;
+  }
+
   /**
    * Normalize this line (set to length 1).
    *
@@ -162,18 +185,33 @@ export class VertTuple<T extends VertTuple<T>> {
    * Move this line to a new location.
    *
    * @method moveTo
-   * @param {Vertex} newA - The new desired location of 'a'. Vertex 'b' will be moved, too.
+   * @param {XYCoords} newA - The new desired location of 'a'. Vertex 'b' will be moved, too.
    * @return {VertTuple} this
    * @instance
    * @memberof VertTuple
    **/
-  moveTo(newA: Vertex): VertTuple<T> {
+  moveTo(newA: XYCoords): VertTuple<T> {
     let diff = this.a.difference(newA);
     this.a.add(diff);
     this.b.add(diff);
     return this;
   }
 
+  /**
+   * Move this line by the given amount
+   *
+   * @method move
+   * @param {XYCoords} amount - The amount to move both point of this tuple.
+   * @return {VertTuple} this
+   * @instance
+   * @memberof VertTuple
+   **/
+  move(amount: XYCoords): VertTuple<T> {
+    this.a.add(amount);
+    this.b.add(amount);
+    return this;
+  }
+
   /**
    * Get the angle between this and the passed line (in radians).
    *
@@ -234,12 +272,13 @@ export class VertTuple<T extends VertTuple<T>> {
    *
    * @method colinear
    * @param {VertTuple} line
+   * @param {epsilon?=1.0e-6} epsilon - The epsilon to use (default is 1.0e-6).
    * @instance
    * @memberof VertTuple
    * @return true if both lines are co-linear.
    */
-  colinear(line: VertTuple<T>): boolean {
-    return Math.abs(this.denominator(line)) < Vertex.EPSILON;
+  colinear(line: VertTuple<T>, epsilon?: number): boolean {
+    return Math.abs(this.denominator(line)) < (typeof epsilon === "undefined" ? Vertex.EPSILON : epsilon);
   }
 
   /**
@@ -269,20 +308,21 @@ export class VertTuple<T extends VertTuple<T>> {
    * that point is located between point `a` and `b`.
    *
    * @method hasPoint
-   * @param {Vertex} point The point to check.
-   * @param {boolean=} insideBoundsOnly If set to to true (default=false) the point must be between start and end point of the line.
+   * @param {Vertex} point - The point to check.
+   * @param {boolean=} insideBoundsOnly - [optional] If set to to true (default=false) the point must be between start and end point of the line.
+   * @param {number=Vertex.EPSILON} epsilon - [optional] A tolerance.
    * @return {boolean} True if the given point is on this line.
    * @instance
    * @memberof VertTuple
    */
-  hasPoint(point: XYCoords, insideBoundsOnly?: boolean): boolean {
+  hasPoint(point: XYCoords, insideBoundsOnly?: boolean, epsilon?: number): boolean {
     const t: number = this.getClosestT(point);
     // Compare to pointDistance?
     const distance: number = Math.sqrt(VertTuple.vtutils.dist2(point, this.vertAt(t)));
     if (typeof insideBoundsOnly !== "undefined" && insideBoundsOnly) {
-      return distance < Vertex.EPSILON && t >= 0 && t <= 1;
+      return distance < (epsilon ?? Vertex.EPSILON) && t >= 0 && t <= 1;
     } else {
-      return distance < Vertex.EPSILON; // t >= 0 && t <= 1;
+      return distance < (epsilon ?? Vertex.EPSILON); // t >= 0 && t <= 1;
     }
   }
 
@@ -304,12 +344,12 @@ export class VertTuple<T extends VertTuple<T>> {
    * The the minimal distance between this line and the specified point.
    *
    * @method pointDistance
-   * @param {Vertex} p The point (vertex) to measre the distance to.
+   * @param {XYCoords} p The point (vertex) to measre the distance to.
    * @return {number} The absolute minimal distance.
    * @instance
    * @memberof VertTuple
    **/
-  pointDistance(p: Vertex): number {
+  pointDistance(p: XYCoords): number {
     // Taken From:
     // https://stackoverflow.com/questions/849211/shortest-distance-between-a-point-and-a-line-segment
     return Math.sqrt(VertTuple.vtutils.dist2(p, this.vertAt(this.getClosestT(p))));

package/src/ts/Vertex.ts

@@ -32,7 +32,10 @@
  * @modified 2023-09-29 Downgraded types for the `Vertex.utils.buildArrowHead` function (replacing Vertex params by more generic XYCoords type).
  * @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.
- * @version  2.9.0
+ * @modified 2024-12-17 Outsourced the euclidean distance calculation of `Vertex.distance` to `geomutils.dist4`.
+ * @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
@@ -42,6 +45,7 @@ import { IVertexAttr, VertexAttr } from "./VertexAttr";
 import { UIDGenerator } from "./UIDGenerator";
 import { VertexListeners } from "./VertexListeners";
 import { XYCoords, SVGSerializable, UID } from "./interfaces";
+import { geomutils } from "./geomutils";
 
 /**
  * @classdesc A vertex is a pair of two numbers.<br>
@@ -270,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.
    *
@@ -430,7 +450,8 @@ export class Vertex implements XYCoords, SVGSerializable {
    * @memberof Vertex
    **/
   distance(vert: XYCoords): number {
-    return Math.sqrt(Math.pow(vert.x - this.x, 2) + Math.pow(vert.y - this.y, 2));
+    // return Math.sqrt(Math.pow(vert.x - this.x, 2) + Math.pow(vert.y - this.y, 2));
+    return geomutils.dist4(this.x, this.y, vert.x, vert.y);
   }
 
   /**
@@ -551,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/draw.ts

@@ -56,6 +56,7 @@
  * @modified 2023-09-29 Added the `lineDashes` attribute.
  * @modified 2023-09-30 Adding `strokeOptions` param to these draw function: line, arrow, cubicBezierArrow, cubicBezier, cubicBezierPath, circle, circleArc, ellipse, square, rect, polygon, polyline.
  * @modified 2023-10-07 Adding the optional `arrowHeadBasePositionBuffer` param to the arrowHead(...) method.
+ * @modified 2024-09-13 Remoed the scaling of `lineWidth` in the `polygon` and `polyline` methods. This makes no sense here and doesn't match up with the behavior of other line functions.
  * @version  1.13.0
  **/
 
@@ -1209,7 +1210,7 @@ export class drawutils implements DrawLib<void> {
     this.ctx.save();
     this.applyStrokeOpts(strokeOptions);
     this.ctx.beginPath();
-    this.ctx.lineWidth = (lineWidth || 1.0) * this.scale.x;
+    this.ctx.lineWidth = lineWidth || 1.0;
     this.ctx.moveTo(this.offset.x + vertices[0].x * this.scale.x, this.offset.y + vertices[0].y * this.scale.y);
     for (var i = 0; i < vertices.length; i++) {
       this.ctx.lineTo(this.offset.x + vertices[i].x * this.scale.x, this.offset.y + vertices[i].y * this.scale.y);

package/src/ts/drawutilssvg.ts

@@ -1288,6 +1288,35 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
    * @memberof drawutilssvg
    */
   grid(center: XYCoords, width: number, height: number, sizeX: number, sizeY: number, color: string) {
+    // console.log("grid");
+    // const node: SVGElement = this.makeNode("pattern");
+    // var patternId = "pattern_id_" + Math.floor(Math.random() * 65365);
+    // node.setAttribute("id", patternId);
+    // node.setAttribute("viewBox", `0,0,${sizeX},${sizeY}`);
+    // node.setAttribute("width", `${sizeX}`);
+    // node.setAttribute("height", `${sizeX}`);
+
+    // var pattern: SVGElement = this.makeNode("path");
+    // const d: SVGPathParams = [];
+    // d.push("M", sizeX / 2.0, 0);
+    // d.push("L", sizeX / 2.0, sizeY);
+    // d.push("M", 0, sizeY / 2.0);
+    // d.push("L", sizeX, sizeY / 2.0);
+    // node.setAttribute("d", d.join(" "));
+
+    // this.bufferedNodeDefs.append(pattern);
+
+    // const fillNode: SVGElement = this.makeNode("rect");
+    // // For some strange reason SVG rotation transforms use degrees instead of radians
+    // // Note that the background does not scale with the zoom level (always covers full element)
+    // fillNode.setAttribute("x", "0");
+    // fillNode.setAttribute("y", "0");
+    // fillNode.setAttribute("width", `${this.canvasSize.width}`);
+    // fillNode.setAttribute("height", `${this.canvasSize.height}`);
+    // fillNode.setAttribute("fill", `url(#${patternId})`);
+
+    // return this._bindFillDraw(fillNode, "grid", "red", 1);
+
     const node: SVGElement = this.makeNode("path");
     const d: SVGPathParams = [];
 

package/src/ts/geomutils.ts

@@ -2,12 +2,16 @@
  * @author   Ikaros Kappler
  * @date     2019-02-03
  * @modified 2021-03-01 Added `wrapMax` function.
- * @version  1.1.0
+ * @modified 2024-11-15 Adding helper function `geomutils.mapAngleTo2PI(number)` for mapping any value into the interval [0,2*PI).
+ * @modified 2024-11-22 Adding helper function `geomutils.dotProduct(number)` for calculating the dot product of two vertices (as vectors).
+ *
+ * @version  1.2.0
  **/
 
 import { Line } from "./Line";
 import { Triangle } from "./Triangle";
 import { Vertex } from "./Vertex";
+import { XYCoords } from "./interfaces";
 
 /**
  * A collection of usefull geometry utilities.
@@ -15,6 +19,50 @@ import { Vertex } from "./Vertex";
  * @global
  **/
 export const geomutils = {
+  /**
+   * Map any angle (any numeric value) to [0, Math.PI).
+   *
+   * @param {number} angle - The numeric value to map.
+   * @return {number} The mapped angle inside [0,PI*2].
+   **/
+  mapAngleTo2PI(angle: number): number {
+    // Source: https://forums.codeguru.com/showthread.php?384172-get-angle-into-range-0-2*pi
+    const new_angle: number = Math.asin(Math.sin(angle));
+    if (Math.cos(angle) < 0) {
+      return Math.PI - new_angle;
+    } else if (new_angle < 0) {
+      return new_angle + 2 * Math.PI;
+    } else {
+      return new_angle;
+    }
+  },
+
+  /**
+   * Calculate the euclidean distance between two points given by four coordinates (two coordinates each).
+   *
+   * @param {number} x1
+   * @param {number} y1
+   * @param {number} x2
+   * @param {number} y2
+   * @returns {number}
+   */
+  dist4(x1: number, y1: number, x2: number, y2: number): number {
+    return Math.sqrt(Math.pow(x2 - x1, 2) + Math.pow(y1 - y2, 2));
+  },
+
+  /**
+   * Map any angle (any numeric value) to [0, Math.PI).
+   *
+   * A × B := (A.x * B.x) + (A.y * B.y)
+   *
+   * @param {XYCoords} vertA - The first vertex.
+   * @param {XYCoords} vertB - The second vertex.
+   * @return {number} The dot product of the two vertices.
+   **/
+  dotProduct(vertA: XYCoords, vertB: XYCoords): number {
+    return vertA.x * vertB.x + vertA.y * vertB.y;
+  },
+
   /**
    * Compute the n-section of the angle – described as a triangle (A,B,C) – in point A.
    *

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