plotboilerplate 1.28.0 → 1.29.0

package/src/ts/Triangle.ts

@@ -27,7 +27,10 @@
  * @modified  2025-14-16 Class `Triangle` now implements interface `IBounded`.
  * @modified  2025-14-16 Class `Triangle` now implements interface `Intersectable`.
  * @modified  2025-14-16 Added method `Triangle.move`.
- * @version   2.10.0
+ * @modified  2026-06-10 Refactoring the `Trianble.bounds` method and added a plain `Triangle.utils.bounds` method.
+ * @modified  2026-06-10 Refactoring the `Trianble.calcCircumCircle` method and added a plain `Triangle.utils.calcCircumCircle` method.
+ * @modified  2026-06-13 Adding `Triangle.getVertices()`.
+ * @version   2.11.0
  *
  * @file Triangle
  * @fileoverview A simple triangle class: three vertices.
@@ -35,7 +38,7 @@
  **/
 
 import { Bounds } from "./Bounds";
-import { Circle } from "./Circle";
+import { Circle, ICircle } from "./Circle";
 import { Line } from "./Line";
 import { Polygon } from "./Polygon";
 import { UIDGenerator } from "./UIDGenerator";
@@ -263,7 +266,7 @@ export class Triangle implements IBounded, SVGSerializable, Intersectable {
    * after triangle vertex changes.
    *
    * @method getCircumcircle
-   * @return {Object} - { center:Vertex, radius:float }
+   * @return {Circle} - The circle touching exactly all three triangle vertices.
    * @instance
    * @memberof Triangle
    */
@@ -273,6 +276,35 @@ export class Triangle implements IBounded, SVGSerializable, Intersectable {
     return new Circle(this.center.clone(), this.radius);
   }
 
+  /**
+   * Calculates the minimun enclosing circle.
+   *
+   * @method getMinimumEnclosingCircle
+   * @return {Object} - { center:Vertex, radius:float }
+   * @instance
+   * @memberof Triangle
+   * @returns
+   */
+  getMinimumEnclosingCircle(): Circle {
+    // First option: two points construct a circle and the third point is contained.
+    var circleAB: ICircle = VertTuple.vtutils.calcCircumcircle(this.a, this.b);
+    if (Circle.circleUtils.containsPoint(circleAB.center, circleAB.radius, this.c)) {
+      return Circle.fromICircle(circleAB);
+    }
+    var circleBC: ICircle = VertTuple.vtutils.calcCircumcircle(this.b, this.c);
+    if (Circle.circleUtils.containsPoint(circleBC.center, circleBC.radius, this.c)) {
+      return Circle.fromICircle(circleBC);
+    }
+    var circleCA: ICircle = VertTuple.vtutils.calcCircumcircle(this.c, this.a);
+    if (Circle.circleUtils.containsPoint(circleCA.center, circleCA.radius, this.c)) {
+      return Circle.fromICircle(circleCA);
+    }
+
+    // If none of the three upper cases applies: return the circumcircle.
+    var circumCircle = Triangle.utils.calcCircumcircle(this.a, this.b, this.c);
+    return Circle.fromICircle(circumCircle);
+  }
+
   /**
    * Check if this triangle and the passed triangle share an
    * adjacent edge.
@@ -311,6 +343,18 @@ export class Triangle implements IBounded, SVGSerializable, Intersectable {
     return this.b;
   }
 
+  /**
+   * Get the three triangele vertices in a 3-element array.
+   *
+   * @method getVertices
+   * @returns {[Vertex, Vertex, Vertex]} - The three vertices – real instances, not copies.
+   * @instance
+   * @memberof Triangle
+   */
+  getVertices(): [Vertex, Vertex, Vertex] {
+    return [this.a, this.b, this.c];
+  }
+
   /**
    * Re-compute the circumcircle of this triangle (if the vertices
    * have changed).
@@ -324,37 +368,41 @@ export class Triangle implements IBounded, SVGSerializable, Intersectable {
    * @memberof Triangle
    */
   calcCircumcircle() {
-    // From
-    //    http://www.exaflop.org/docs/cgafaq/cga1.html
-
-    const A: number = this.b.x - this.a.x;
-    const B: number = this.b.y - this.a.y;
-    const C: number = this.c.x - this.a.x;
-    const D: number = this.c.y - this.a.y;
-
-    const E: number = A * (this.a.x + this.b.x) + B * (this.a.y + this.b.y);
-    const F: number = C * (this.a.x + this.c.x) + D * (this.a.y + this.c.y);
-
-    const G: number = 2.0 * (A * (this.c.y - this.b.y) - B * (this.c.x - this.b.x));
-
-    let dx: number, dy: number;
-
-    if (Math.abs(G) < Triangle.EPSILON) {
-      // Collinear - find extremes and use the midpoint
-      const bounds: Bounds = this.bounds();
-      this.center = new Vertex((bounds.min.x + bounds.max.x) / 2, (bounds.min.y + bounds.max.y) / 2);
-      dx = this.center.x - bounds.min.x;
-      dy = this.center.y - bounds.min.y;
-    } else {
-      const cx: number = (D * E - B * F) / G;
-      const cy: number = (A * F - C * E) / G;
-      this.center = new Vertex(cx, cy);
-      dx = this.center.x - this.a.x;
-      dy = this.center.y - this.a.y;
-    }
-
-    this.radius_squared = dx * dx + dy * dy;
-    this.radius = Math.sqrt(this.radius_squared);
+    // // From
+    // //    http://www.exaflop.org/docs/cgafaq/cga1.html
+
+    // const A: number = this.b.x - this.a.x;
+    // const B: number = this.b.y - this.a.y;
+    // const C: number = this.c.x - this.a.x;
+    // const D: number = this.c.y - this.a.y;
+
+    // const E: number = A * (this.a.x + this.b.x) + B * (this.a.y + this.b.y);
+    // const F: number = C * (this.a.x + this.c.x) + D * (this.a.y + this.c.y);
+
+    // const G: number = 2.0 * (A * (this.c.y - this.b.y) - B * (this.c.x - this.b.x));
+
+    // let dx: number, dy: number;
+
+    // if (Math.abs(G) < Triangle.EPSILON) {
+    //   // Collinear - find extremes and use the midpoint
+    //   const bounds: Bounds = this.bounds();
+    //   this.center = new Vertex((bounds.min.x + bounds.max.x) / 2, (bounds.min.y + bounds.max.y) / 2);
+    //   dx = this.center.x - bounds.min.x;
+    //   dy = this.center.y - bounds.min.y;
+    // } else {
+    //   const cx: number = (D * E - B * F) / G;
+    //   const cy: number = (A * F - C * E) / G;
+    //   this.center = new Vertex(cx, cy);
+    //   dx = this.center.x - this.a.x;
+    //   dy = this.center.y - this.a.y;
+    // }
+
+    // this.radius_squared = dx * dx + dy * dy;
+    // this.radius = Math.sqrt(this.radius_squared);
+    const tmpCircle = Triangle.utils.calcCircumcircle(this.a, this.b, this.c);
+    this.center = new Vertex(tmpCircle.center.x, tmpCircle.center.y);
+    this.radius = tmpCircle.radius;
+    this.radius_squared = tmpCircle.radius_squared;
   } // END calcCircumcircle
 
   /**
@@ -383,10 +431,11 @@ export class Triangle implements IBounded, SVGSerializable, Intersectable {
    * @memberof Triangle
    */
   bounds(): Bounds {
-    return new Bounds(
-      new Vertex(Triangle.utils.min3(this.a.x, this.b.x, this.c.x), Triangle.utils.min3(this.a.y, this.b.y, this.c.y)),
-      new Vertex(Triangle.utils.max3(this.a.x, this.b.x, this.c.x), Triangle.utils.max3(this.a.y, this.b.y, this.c.y))
-    );
+    // return new Bounds(
+    //   new Vertex(Triangle.utils.min3(this.a.x, this.b.x, this.c.x), Triangle.utils.min3(this.a.y, this.b.y, this.c.y)),
+    //   new Vertex(Triangle.utils.max3(this.a.x, this.b.x, this.c.x), Triangle.utils.max3(this.a.y, this.b.y, this.c.y))
+    // );
+    return Triangle.utils.bounds(this.a, this.b, this.c);
   }
 
   //--- BEGIN --- Implement interface `Intersectable`
@@ -521,7 +570,9 @@ export class Triangle implements IBounded, SVGSerializable, Intersectable {
    * @return Vertex The incenter of this triangle.
    **/
   getIncenter(): Vertex {
-    if (!this.center || !this.radius) this.calcCircumcircle();
+    if (!this.center || !this.radius) {
+      this.calcCircumcircle();
+    }
     return this.center.clone();
   }
 
@@ -594,8 +645,64 @@ export class Triangle implements IBounded, SVGSerializable, Intersectable {
      * @param {XYCords} c - The first vertex.
      * @returns {nmber}
      */
-    determinant(a: XYCoords, b: XYCoords, c: XYCoords): number {
+    determinant: (a: XYCoords, b: XYCoords, c: XYCoords): number => {
       return (b.y - a.y) * (c.x - b.x) - (c.y - b.y) * (b.x - a.x);
-    }
+    },
+
+    bounds: (a: XYCoords, b: XYCoords, c: XYCoords): Bounds => {
+      return new Bounds(
+        new Vertex(Triangle.utils.min3(a.x, b.x, c.x), Triangle.utils.min3(a.y, b.y, c.y)),
+        new Vertex(Triangle.utils.max3(a.x, b.x, c.x), Triangle.utils.max3(a.y, b.y, c.y))
+      );
+    },
+
+    /**
+     * Re-compute the circumcircle of this triangle (if the vertices
+     * have changed).
+     *
+     * The circumcenter and radius are stored in this.center and
+     * this.radius. There is a third result: radius_squared (for internal computations).
+     *
+     * @method calcCircumcircle
+     * @return void
+     * @instance
+     * @memberof Triangle
+     */
+    calcCircumcircle: (a: XYCoords, b: XYCoords, c: XYCoords): ICircle => {
+      // From
+      //    http://www.exaflop.org/docs/cgafaq/cga1.html
+
+      const A: number = b.x - a.x;
+      const B: number = b.y - a.y;
+      const C: number = c.x - a.x;
+      const D: number = c.y - a.y;
+
+      const E: number = A * (a.x + b.x) + B * (a.y + b.y);
+      const F: number = C * (a.x + c.x) + D * (a.y + c.y);
+
+      const G: number = 2.0 * (A * (c.y - b.y) - B * (c.x - b.x));
+
+      let dx: number, dy: number;
+
+      let center;
+      if (Math.abs(G) < Triangle.EPSILON) {
+        // Collinear - find extremes and use the midpoint
+        // const bounds: Bounds = this.bounds();
+        const bounds: Bounds = Triangle.utils.bounds(a, b, c);
+        center = new Vertex((bounds.min.x + bounds.max.x) / 2, (bounds.min.y + bounds.max.y) / 2);
+        dx = center.x - bounds.min.x;
+        dy = center.y - bounds.min.y;
+      } else {
+        const cx: number = (D * E - B * F) / G;
+        const cy: number = (A * F - C * E) / G;
+        center = new Vertex(cx, cy);
+        dx = center.x - a.x;
+        dy = center.y - a.y;
+      }
+
+      const radius_squared = dx * dx + dy * dy;
+      const radius = Math.sqrt(radius_squared);
+      return { center: center, radius: radius, radius_squared: radius_squared };
+    } // END calcCircumcircle
   };
 }

package/src/ts/VertTuple.ts

@@ -16,12 +16,14 @@
  * @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
+ * @modified 2026-06-10 Adding helper function `VertTuple.utils.calcCircumcircle`.
+ * @version 1.5.0
  */
 
 import { Vertex } from "./Vertex";
 import { UIDGenerator } from "./UIDGenerator";
 import { XYCoords, UID } from "./interfaces";
+import { ICircle } from "./Circle";
 
 /**
  * @classdesc An abstract base classes for vertex tuple constructs, like Lines or Vectors.
@@ -396,6 +398,17 @@ export class VertTuple<T extends VertTuple<T>> {
   static vtutils = {
     dist2: (v: XYCoords, w: XYCoords) => {
       return (v.x - w.x) * (v.x - w.x) + (v.y - w.y) * (v.y - w.y);
+    },
+
+    calcCircumcircle: (p1: XYCoords, p2: XYCoords): ICircle => {
+      const p1x = p1.x,
+        p1y = p1.y,
+        p2x = p2.x,
+        p2y = p2.y,
+        cx = 0.5 * (p1x + p2x),
+        cy = 0.5 * (p1y + p2y);
+
+      return { center: { x: cx, y: cy }, radius: Math.sqrt((p1x - cx) * (p1x - cx) + (p1y - cy) * (p1y - cy)) };
     }
   };
 }

package/src/ts/Vertex.ts

@@ -36,7 +36,8 @@
  * @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
+ * @modified 2026-06-10 Adding methods `Vertex.findClosestPoint` and `Vertex.findFarestPoint`.
+ * @version  2.12.0
  *
  * @file Vertex
  * @public
@@ -663,6 +664,47 @@ export class Vertex implements IBounded, XYCoords, SVGSerializable {
   }
   //--- END --- Implement interface `IBounded`
 
+  /**
+   * Find the one of two given points that's closest to this point.
+   *
+   * @method findClosestPoint
+   * @instance
+   * @memberof Vertex
+   * @param {XYCoords | Vertex} pointA
+   * @param {XYCoords | Vertex} pointB
+   * @returns  {XYCoords | Vertex}
+   */
+  findClosestPoint<T extends XYCoords | Vertex>(pointA: T, pointB: T): T {
+    // TODO: put this implementation to geomutils?
+    var distA = this.distance(pointA);
+    var distB = this.distance(pointB);
+    if (distA < distB) {
+      return pointA;
+    } else {
+      return pointB;
+    }
+  }
+
+  /**
+   * Find the one of two given points that's farest from this point.
+   *
+   * @method findFarestPoint
+   * @instance
+   * @memberof Vertex
+   * @param {XYCoords | Vertex} pointA
+   * @param {XYCoords | Vertex} pointB
+   * @returns  {XYCoords | Vertex}
+   */
+  findFarestPoint<T extends XYCoords | Vertex>(pointA: T, pointB: T): T {
+    var distA = this.distance(pointA);
+    var distB = this.distance(pointB);
+    if (distA > distB) {
+      return pointA;
+    } else {
+      return pointB;
+    }
+  }
+
   /**
    * Get a string representation of this vertex.
    *
@@ -758,7 +800,7 @@ export class Vertex implements IBounded, XYCoords, SVGSerializable {
      * @param {number?} precision - (optional) The numeric precision to be used (number of precision digits).
      * @returns {string}
      */
-    arrayToJSON(vertices: Array<XYCoords>, precision?: number) {
+    arrayToJSON: (vertices: Array<XYCoords>, precision?: number) => {
       return JSON.stringify(
         vertices.map(function (vert) {
           return typeof precision === undefined

package/src/ts/utils/algorithms/minimalEnclosingCircleFromPoints.ts

@@ -0,0 +1,69 @@
+/**
+ * Calculate the minimal containing circle from a set of points.
+ *
+ * The number of points must be at least 2. Otherwise the function returns null.
+ *
+ * Inspired by https://github.com/rowanwins/smallest-enclosing-circle.
+ *
+ * @param {XYCoords[]} points
+ * @returns
+ */
+
+import { Circle, ICircle } from "../../Circle";
+import { Triangle } from "../../Triangle";
+import { VertTuple } from "../../VertTuple";
+import { Vertex } from "../../Vertex";
+import { XYCoords } from "../../interfaces";
+
+/**
+ * Calculate the minimal containing circle from a set of points.
+ *
+ * The number of points must be at least 2. Otherwise the function returns null.
+ *
+ * @param {XYCoords[]} points
+ * @returns {Circle | null} The minimal containing circle or null if the point count is lower than 2.
+ */
+export const minimalEnclosingCircleFromPoints = (points: XYCoords[]): Circle | null => {
+  if (points.length <= 1) {
+    return null;
+  }
+  const circleObject = wetzlsAlgorithm(points);
+  return new Circle(new Vertex(circleObject.center.x, circleObject.center.y), circleObject.radius);
+};
+
+/**
+ * This initiates the actual algorithm but return a shallow circle representation.
+ *
+ * @param points
+ * @returns
+ */
+const wetzlsAlgorithm = (points: XYCoords[]): ICircle | null => {
+  return minimumContainingCircle(points, points.length, [], 0);
+};
+
+/**
+ * Pre: points.length >= 2
+ * @param {Vertex[]} points
+ * @param n
+ * @param boundary
+ * @param boundaryLength
+ * @returns
+ */
+const minimumContainingCircle = (points: XYCoords[], n: number, boundary: XYCoords[], boundaryLength: number): ICircle => {
+  if (boundaryLength === 3) {
+    return Triangle.utils.calcCircumcircle(boundary[0], boundary[1], boundary[2]);
+  } else if (n === 1 && boundaryLength === 0) {
+    return { center: { x: points[0].x, y: points[0].y }, radius: 0 };
+  } else if (n === 0 && boundaryLength === 2) {
+    return VertTuple.vtutils.calcCircumcircle(boundary[0], boundary[1]);
+  } else if (n === 1 && boundaryLength === 1) {
+    return VertTuple.vtutils.calcCircumcircle(boundary[0], points[0]);
+  } else {
+    const localCircle: ICircle = minimumContainingCircle(points, n - 1, boundary, boundaryLength);
+    if (!Circle.circleUtils.containsPoint(localCircle.center, localCircle.radius, points[n - 1])) {
+      boundary[boundaryLength++] = points[n - 1];
+      return minimumContainingCircle(points, n - 1, boundary, boundaryLength);
+    }
+    return localCircle;
+  }
+};

package/src/ts/utils/algorithms/solveApollonius3.ts

@@ -0,0 +1,132 @@
+/**
+ * A solver for the Apollonian circle problem:
+ *   find the circle that touches three other circles in extactly one point (each).
+ * The solution is not necesarily unique.
+ * 
+ * For each of the three circles a boolean attribute can be passed that determines if the 
+ * resultint circle should touch the input circle should be touched on the inside or outside.
+ * 
+ * Not that there can be condition when the circle cannot be calculated (e.g. all circles 
+ * have the same size and are colinear).
+ * 
+ * Found at
+ *     https://stackoverflow.com/questions/79281573/algorithm-for-finding-enclosing-circles-for-3-other-circles
+ * 
+ * solveApollonius(Coord c1, Coord c2, Coord c3, int s1, int s2, int s3) {
+        // https://github.com/DIKU-Steiner/ProGAL/blob/master/src/ProGAL/geom2d/ApolloniusSolver.java
+
+        var x1 = c1.x;
+        var y1 = c1.y;
+        var r1 = c1.z;
+        var x2 = c2.x;
+        var y2 = c2.y;
+        var r2 = c2.z;
+        var x3 = c3.x;
+        var y3 = c3.y;
+        var r3 = c3.z;
+
+        // Currently optimized for fewest multiplications.
+        var v11 = 2 * x2 - 2 * x1;
+        var v12 = 2 * y2 - 2 * y1;
+        var v13 = x1 * x1 - x2 * x2 + y1 * y1 - y2 * y2 - r1 * r1 + r2 * r2;
+        var v14 = 2 * s2 * r2 - 2 * s1 * r1;
+
+        var v21 = 2 * x3 - 2 * x2;
+        var v22 = 2 * y3 - 2 * y2;
+        var v23 = x2 * x2 - x3 * x3 + y2 * y2 - y3 * y3 - r2 * r2 + r3 * r3;
+        var v24 = 2 * s3 * r3 - 2 * s2 * r2;
+
+        var w12 = v12 / v11;
+        var w13 = v13 / v11;
+        var w14 = v14 / v11;
+
+        var w22 = v22 / v21 - w12;
+        var w23 = v23 / v21 - w13;
+        var w24 = v24 / v21 - w14;
+
+        var P = -w23 / w22;
+        var Q = w24 / w22;
+        var M = -w12 * P - w13;
+        var N = w14 - w12 * Q;
+
+        var a = N * N + Q * Q - 1;
+        var b = 2 * M * N - 2 * N * x1 + 2 * P * Q - 2 * Q * y1 + 2 * s1 * r1;
+        var c = x1 * x1 + M * M - 2 * M * x1 + P * P + y1 * y1 - 2 * P * y1 - r1 * r1;
+
+        // Find a root of a quadratic equation. This requires the circle centers not
+        // to be e.g. colinear
+        var D = b * b - 4 * a * c;
+        var rs = (-b - Math.sqrt(D)) / (2 * a);
+        var xs = M + N * rs;
+        var ys = P + Q * rs;
+
+        return (xs, ys, rs);
+    }
+ * 
+ * @date 2026-07-03
+ */
+
+import { Circle, ICircle } from "../../Circle";
+import { Vertex } from "../../Vertex";
+
+export const solveApollonius3 = (
+  c1: ICircle,
+  c2: ICircle,
+  c3: ICircle,
+  circle1Inside?: boolean,
+  circle2Inside?: boolean,
+  circle3Inside?: boolean
+): Circle => {
+  // https://github.com/DIKU-Steiner/ProGAL/blob/master/src/ProGAL/geom2d/ApolloniusSolver.java
+
+  var x1 = c1.center.x;
+  var y1 = c1.center.y;
+  var r1 = c1.radius;
+  var x2 = c2.center.x;
+  var y2 = c2.center.y;
+  var r2 = c2.radius;
+  var x3 = c3.center.x;
+  var y3 = c3.center.y;
+  var r3 = c3.radius;
+
+  var s1 = Boolean(circle1Inside) ? 1 : -1;
+  var s2 = Boolean(circle2Inside) ? 1 : -1;
+  var s3 = Boolean(circle3Inside) ? 1 : -1;
+
+  // Currently optimized for fewest multiplications.
+  var v11 = 2 * x2 - 2 * x1;
+  var v12 = 2 * y2 - 2 * y1;
+  var v13 = x1 * x1 - x2 * x2 + y1 * y1 - y2 * y2 - r1 * r1 + r2 * r2;
+  var v14 = 2 * s2 * r2 - 2 * s1 * r1;
+
+  var v21 = 2 * x3 - 2 * x2;
+  var v22 = 2 * y3 - 2 * y2;
+  var v23 = x2 * x2 - x3 * x3 + y2 * y2 - y3 * y3 - r2 * r2 + r3 * r3;
+  var v24 = 2 * s3 * r3 - 2 * s2 * r2;
+
+  var w12 = v12 / v11;
+  var w13 = v13 / v11;
+  var w14 = v14 / v11;
+
+  var w22 = v22 / v21 - w12;
+  var w23 = v23 / v21 - w13;
+  var w24 = v24 / v21 - w14;
+
+  var P = -w23 / w22;
+  var Q = w24 / w22;
+  var M = -w12 * P - w13;
+  var N = w14 - w12 * Q;
+
+  var a = N * N + Q * Q - 1;
+  var b = 2 * M * N - 2 * N * x1 + 2 * P * Q - 2 * Q * y1 + 2 * s1 * r1;
+  var c = x1 * x1 + M * M - 2 * M * x1 + P * P + y1 * y1 - 2 * P * y1 - r1 * r1;
+
+  // Find a root of a quadratic equation. This requires the circle centers not
+  // to be e.g. colinear
+  var D = b * b - 4 * a * c;
+  var rs = (-b - Math.sqrt(D)) / (2 * a);
+  var xs = M + N * rs;
+  var ys = P + Q * rs;
+
+  return new Circle(new Vertex(xs, ys), Math.abs(rs));
+};