plotboilerplate 1.12.10 → 1.16.0

package/src/ts/Vertex.ts

@@ -22,7 +22,13 @@
  * @modified 2020-05-26 Added functions addX(number) and addY(number).
  * @modified 2020-10-30 Changed the warnings in `sub(...)` and `add(...)` into real errors.
  * @modified 2021-03-01 Changed the second param `center` in the `rotate` function from Vertex to XYCoords.
- * @version  2.4.2
+ * @modified 2021-12-01 Changed the type of param of `scale` to XYCoords.
+ * @modified 2021-12-01 Added function `scaleXY` for non uniform scaling.
+ * @modified 2021-12-17 Added the functions `lerp` and `lerpAbs` for linear interpolations.
+ * @modified 2022-01-31 Added `Vertex.utils.arrayToJSON`.
+ * @modified 2022-02-02 Added the `destroy` method.
+ * @modified 2022-02-02 Cleared the `Vertex.toSVGString` function (deprecated). Use `drawutilssvg` instead.
+ * @version  2.7.0
  *
  * @file Vertex
  * @public
@@ -101,6 +107,14 @@ export class Vertex implements XYCoords, SVGSerializable {
    **/
   listeners: VertexListeners;
 
+  /**
+   * @member isDestroyed
+   * @memberof Vertex
+   * @type {boolean}
+   * @instance
+   */
+  isDestroyed: boolean;
+
   /**
    * The constructor for the vertex class.
    *
@@ -406,19 +420,75 @@ export class Vertex implements XYCoords, SVGSerializable {
 
   /**
    * This is a vector-like behavior and 'scales' this vertex
-   * towards/from a given center.
+   * towards/from a given center by one uniform scale factor.
    *
    * @method scale
    * @param {number} factor - The factor to 'scale' this vertex; 1.0 means no change.
-   * @param {Vertex=} center - The origin of scaling; default is (0,0).
+   * @param {XYCoords=} center - The origin of scaling; default is (0,0).
    * @return {Vertex} this
    * @instance
    * @memberof Vertex
    **/
-  scale(factor: number, center?: Vertex): Vertex {
-    if (!center || typeof center === "undefined") center = new Vertex(0, 0);
-    this.x = center.x + (this.x - center.x) * factor;
-    this.y = center.y + (this.y - center.y) * factor;
+  scale(factor: number, center?: XYCoords): Vertex {
+    return this.scaleXY({ x: factor, y: factor }, center);
+  }
+
+  /**
+   * Perform a linear interpolation towards the given target vertex.
+   * The amount value `t` is relative, `t=0.0` means no change, `t=1.0`
+   * means this point will be moved to the exact target position.
+   *
+   * `t=0.5` will move this point to the middle of the connecting
+   * linear segment.
+   *
+   * @param {XYCoords} target - The target position to lerp this vertex to.
+   * @param {number} t - The relative amount, usually in [0..1], but other values will work, too.
+   * @returns
+   */
+  lerp(target: XYCoords, t: number): Vertex {
+    var diff = this.difference(target);
+    // return new Vertex(this.x + diff.x * t, this.y + diff.y * t);
+    this.x += diff.x * t;
+    this.y += diff.y * t;
+    return this;
+  }
+
+  /**
+   * Perform a linear interpolation towards the given target vertex (absolute variant).
+   * The amount value `t` is absolute, which means the lerp amount is a direct distance
+   * value. This point will have move the amount of the passed distance `u`.
+   *
+   * @param {XYCoords} target - The target position to lerp this vertex to.
+   * @param {number} t - The absolute move amount to use to lerping.
+   * @returns
+   */
+  lerpAbs(target: XYCoords, u: number): Vertex {
+    var dist = this.distance(target);
+    var diff = this.difference(target);
+    var step = { x: diff.x / dist, y: diff.y / dist };
+    // return new Vertex(this.x + step.x * u, this.y + step.y * u);
+    this.x += step.x * u;
+    this.y += step.y * u;
+    return this;
+  }
+
+  /**
+   * This is a vector-like behavior and 'scales' this vertex
+   * towards/from a given center by two independent x- and y- scale factors.
+   *
+   * @method scale
+   * @param {number} factor - The factor to 'scale' this vertex; 1.0 means no change.
+   * @param {XYCoords=} center - The origin of scaling; default is (0,0).
+   * @return {Vertex} this
+   * @instance
+   * @memberof Vertex
+   **/
+  scaleXY(factors: XYCoords, center?: XYCoords): Vertex {
+    if (!center || typeof center === "undefined") {
+      center = { x: 0, y: 0 };
+    }
+    this.x = center.x + (this.x - center.x) * factors.x;
+    this.y = center.y + (this.y - center.y) * factors.y;
     return this;
   }
 
@@ -513,20 +583,35 @@ export class Vertex implements XYCoords, SVGSerializable {
    * @return {string} A string representing the SVG code for this vertex.
    * @instance
    * @memberof Vertex
+   * @deprecated
    **/
   toSVGString(options: { className?: string }): string {
-    options = options || {};
-    var buffer = [];
-    buffer.push("<circle");
-    if (options.className) buffer.push(' class="' + options.className + '"');
-    buffer.push(' cx="' + this.x + '"');
-    buffer.push(' cy="' + this.y + '"');
-    buffer.push(' r="2"');
-    buffer.push(" />");
-    return buffer.join("");
+    // options = options || {};
+    // var buffer = [];
+    // buffer.push("<circle");
+    // if (options.className) buffer.push(' class="' + options.className + '"');
+    // buffer.push(' cx="' + this.x + '"');
+    // buffer.push(' cy="' + this.y + '"');
+    // buffer.push(' r="2"');
+    // buffer.push(" />");
+    // return buffer.join("");
+    console.warn(
+      "[Deprecation] Warning: the Vertex.toSVGString method is deprecated and does not return and valid SVG data any more. Please use `drawutilssvg` instead."
+    );
+    return "";
   }
   // END Vertex
 
+  /**
+   * 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
+   * should not be used.
+   */
+  destroy() {
+    this.listeners.removeAllListeners();
+    this.isDestroyed = true;
+  }
+
   /**
    * Create a new random vertex inside the given viewport.
    *
@@ -588,6 +673,22 @@ export class Vertex implements XYCoords, SVGSerializable {
       );
 
       return vertices;
+    },
+
+    /**
+     * Convert the given vertices (array) to a JSON string.
+     *
+     * @param {number?} precision - (optional) The numeric precision to be used (number of precision digits).
+     * @returns {string}
+     */
+    arrayToJSON(vertices: Array<XYCoords>, precision?: number) {
+      return JSON.stringify(
+        vertices.map(function (vert) {
+          return typeof precision === undefined
+            ? { x: vert.x, y: vert.y }
+            : { x: Number(vert.x.toFixed(precision)), y: Number(vert.y.toFixed(precision)) };
+        })
+      );
     }
   };
 }