plotboilerplate 1.17.0 → 1.18.0

package/src/ts/Circle.ts

@@ -9,7 +9,10 @@
  * @modified 2021-01-20 Added UID.
  * @modified 2022-02-02 Added the `destroy` method.
  * @modified 2022-02-02 Cleared the `toSVGString` function (deprecated). Use `drawutilssvg` instead.
- * @version  1.3.0
+ * @modified 2022-08-15 Added the `containsPoint` function.
+ * @modified 2022-08-23 Added the `lineIntersection` function.
+ * @modified 2022-08-23 Added the `closestPoint` function.
+ * @version  1.4.0
  **/
 
 import { Line } from "./Line";
@@ -17,7 +20,7 @@ import { UIDGenerator } from "./UIDGenerator";
 import { Vector } from "./Vector";
 import { VertTuple } from "./VertTuple";
 import { Vertex } from "./Vertex";
-import { SVGSerializable, UID } from "./interfaces";
+import { SVGSerializable, UID, XYCoords } from "./interfaces";
 
 /**
  * @classdesc A simple circle: center point and radius.
@@ -82,6 +85,19 @@ export class Circle implements SVGSerializable {
     this.radius = radius;
   }
 
+  /**
+   * Check if the given circle is fully contained inside this circle.
+   *
+   * @method containsPoint
+   * @param {XYCoords} point - The point to check if it is contained in this circle.
+   * @instance
+   * @memberof Circle
+   * @return {boolean} `true` if the given point is inside this circle.
+   */
+  containsPoint(point: XYCoords): boolean {
+    return this.center.distance(point) < this.radius;
+  }
+
   /**
    * Check if the given circle is fully contained inside this circle.
    *
@@ -198,6 +214,80 @@ export class Circle implements SVGSerializable {
     return new Line(new Vertex(x3, y3), new Vertex(x4, y4));
   }
 
+  /**
+   * Calculate the intersection points (if exists) with the given infinite line (defined by two points).
+   *
+   * @method lineIntersection
+   * @instance
+   * @memberof Circle
+   * @param {Vertex} a- The first of the two points defining the line.
+   * @param {Vertex} b - The second of the two points defining the line.
+   * @return {Line|null} The intersection points (as a line) or null if this circle does not intersect the line given.
+   **/
+  lineIntersection(a: Vertex, b: XYCoords): Line | null {
+    // Based on the math from
+    //    https://mathworld.wolfram.com/Circle-LineIntersection.html
+    const interA = new Vertex();
+    const interB = new Vertex();
+
+    // First do a transformation, because the calculation is based on a cicle at (0,0)
+    const transA = new Vertex(a).sub(this.center);
+    const transB = new Vertex(b).sub(this.center);
+
+    const diff: XYCoords = transA.difference(transB);
+    // There is a special case if diff.y=0, where the intersection is not calcuatable.
+    // Use an non-zero epsilon here to approximate this case.
+    // TODO for the future: find a better solution
+    if (Math.abs(diff.y) === 0) {
+      diff.y = 0.000001;
+    }
+
+    const dist: number = transA.distance(transB);
+    const det: number = transA.x * transB.y - transA.y * transB.x;
+    const distSquared: number = dist * dist;
+    const radiusSquared: number = this.radius * this.radius;
+
+    // Check if circle and line have an intersection at all
+    if (radiusSquared * distSquared - det * det < 0) {
+      return null;
+    }
+
+    const belowSqrt: number = this.radius * this.radius * dist * dist - det * det;
+    const sqrt: number = Math.sqrt(belowSqrt);
+
+    interA.x = (det * diff.y + Math.sign(diff.y) * diff.x * sqrt) / distSquared;
+    interB.x = (det * diff.y - Math.sign(diff.y) * diff.x * sqrt) / distSquared;
+
+    interA.y = (-det * diff.x + Math.abs(diff.y) * sqrt) / distSquared;
+    interB.y = (-det * diff.x - Math.abs(diff.y) * sqrt) / distSquared;
+
+    return new Line(interA.add(this.center), interB.add(this.center));
+    // return new Line(interA, interB);
+  }
+
+  /**
+   * Calculate the closest point on the outline of this circle to the given point.
+   *
+   * @method closestPoint
+   * @instance
+   * @memberof Circle
+   * @param {XYCoords} vert - The point to find the closest circle point for.
+   * @return {Vertex} The closest point on this circle.
+   **/
+  closestPoint(vert: XYCoords): Vertex {
+    const lineIntersection = this.lineIntersection(this.center, vert);
+    if (!lineIntersection) {
+      // Note: this case should not happen as a radial from the center always intersect this circle.
+      return new Vertex();
+    }
+    // Return closed of both
+    if (lineIntersection.a.distance(vert) < lineIntersection.b.distance(vert)) {
+      return lineIntersection.a;
+    } else {
+      return lineIntersection.b;
+    }
+  }
+
   /**
    * 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

package/src/ts/MouseHandler.ts

@@ -17,7 +17,8 @@
  * @modified 2020-10-04 Added extended JSDoc comments.
  * @modified 2020-11-25 Added the `isTouchEvent` param.
  * @modified 2021-01-10 The mouse handler is now also working with SVGElements.
- * @version  1.2.0
+ * @modified 2022-08-16 Fixed a bug in the mouse button detection.
+ * @version  1.2.1
  *
  * @file MouseHandler
  * @public
@@ -58,7 +59,7 @@ export type XWheelCallback = (e: XWheelEvent) => void;
  * @requires XYCoords
  */
 export class MouseHandler {
-  private name: string;
+  private name: string | undefined;
   private element: HTMLElement | SVGElement;
   private mouseDownPos: { x: number; y: number } | undefined = undefined;
   private mouseDragPos: { x: number; y: number } | undefined = undefined;
@@ -135,8 +136,8 @@ export class MouseHandler {
     // +-------------------------------------------------
     this.name = name;
     this.element = element;
-    this.mouseDownPos = null;
-    this.mouseDragPos = null;
+    this.mouseDownPos = undefined;
+    this.mouseDragPos = undefined;
     // this.mousePos     = null;
     this.mouseButton = -1;
     this.listeners = {};
@@ -202,26 +203,26 @@ export class MouseHandler {
    * @memberof MouseHandler
    * @instance
    * @private
-   * @param {MouseEvent} e - The mouse event to get the relative position for.
+   * @param {MouseEvent} event - The mouse event to get the relative position for.
    * @param {string} eventName - The name of the firing event.
    * @return {XMouseEvent}
    */
-  private mkParams(e: MouseEvent, eventName: string): XMouseEvent {
-    const rel: { x: number; y: number } = this.relPos(e);
-    const xEvent: XMouseEvent = e as unknown as XMouseEvent;
+  private mkParams(event: MouseEvent, eventName: string): XMouseEvent {
+    const rel: { x: number; y: number } = this.relPos(event);
+    const xEvent: XMouseEvent = event as unknown as XMouseEvent;
     xEvent.params = {
       element: this.element,
       name: eventName,
       isTouchEvent: false,
       pos: rel,
-      button: this.mouseButton,
-      leftButton: this.mouseButton == 0,
-      middleButton: this.mouseButton == 1,
-      rightButton: this.mouseButton == 2,
-      mouseDownPos: this.mouseDownPos,
-      draggedFrom: this.mouseDragPos,
+      button: event.button, // this.mouseButton,
+      leftButton: event.button === 0, // this.mouseButton === 0,
+      middleButton: event.button === 1, // this.mouseButton === 1,
+      rightButton: event.button === 2, // this.mouseButton === 2,
+      mouseDownPos: this.mouseDownPos ?? { x: NaN, y: NaN },
+      draggedFrom: this.mouseDragPos ?? { x: NaN, y: NaN },
       wasDragged: this.mouseDownPos != null && (this.mouseDownPos.x != rel.x || this.mouseDownPos.y != rel.y),
-      dragAmount: this.mouseDownPos != null ? { x: rel.x - this.mouseDragPos.x, y: rel.y - this.mouseDragPos.y } : { x: 0, y: 0 }
+      dragAmount: this.mouseDragPos != null ? { x: rel.x - this.mouseDragPos.x, y: rel.y - this.mouseDragPos.y } : { x: 0, y: 0 }
     };
     return xEvent;
   }

package/src/ts/PlotBoilerplate.ts

@@ -74,7 +74,8 @@
  * @modified 2021-03-29 Clearing `currentClassName` and `currentId` after drawing each drawable.
  * @modified 2021-04-25 Extending `remove` to accept arrays of drawables.
  * @modified 2021-11-16 Adding the `PBText` drawable.
- * @version  1.15.0
+ * @modified 2022-08-01 Added `title` to the params.
+ * @version  1.15.1
  *
  * @file PlotBoilerplate
  * @fileoverview The main class.
@@ -376,6 +377,7 @@ export class PlotBoilerplate {
    * @param {boolean=} [config.enableGL=false] - Indicates if the application should use the experimental WebGL features (not recommended).
    * @param {boolean=} [config.enableSVGExport=true] - Indicates if the SVG export should be enabled (default is true).
    *                                                   Note that changes from the postDraw hook might not be visible in the export.
+   * @param {string=} [config.title=null] - Specify any hover tile here. It will be attached as a `title` attribute to the most elevated element.
    */
   constructor(config: PBParams) {
     // This should be in some static block ...
@@ -592,6 +594,11 @@ export class PlotBoilerplate {
     } else {
       throw "Element is neither a canvas nor an svg element.";
     }
+    // At this point the event cacher element is deinfed and located at highest elevation.
+    // Set `title` attribut?
+    if (config.title) {
+      this.eventCatcher.setAttribute("title", config.title);
+    }
     this.draw.scale.set(this.config.scaleX, this.config.scaleY);
     this.fill.scale.set(this.config.scaleX, this.config.scaleY);
     this.vertices = [];

package/src/ts/draw.ts

@@ -42,7 +42,12 @@
  * @modified 2022-02-03 Added the `lineWidth` param to the `crosshair` function.
  * @modified 2022-02-03 Added the `cross(...)` function.
  * @modified 2022-03-27 Added the `texturedPoly` function.
- * @version  1.12.0
+ * @modified 2022-06-01 Tweaked the `polyline` function; lineWidth now scales with scale.x.
+ * @modified 2022-07-26 Adding `alpha` to the `image(...)` function.
+ * @modified 2022-08-23 Fixed a type issue in the `polyline` function.
+ * @modified 2022-08-23 Fixed a type issue in the `setConfiguration` function.
+ * @modified 2022-08-23 Fixed a type issue in the `path` function.
+ * @version  1.12.3
  **/
 
 import { CubicBezierCurve } from "./CubicBezierCurve";
@@ -139,7 +144,7 @@ export class drawutils implements DrawLib<void> {
    * @param {DrawLibConfiguration} configuration - The new configuration settings to use for the next render methods.
    */
   setConfiguration(configuration: DrawLibConfiguration): void {
-    this.ctx.globalCompositeOperation = configuration.blendMode;
+    this.ctx.globalCompositeOperation = configuration.blendMode || "source-over";
   }
 
   /**
@@ -229,16 +234,18 @@ export class drawutils implements DrawLib<void> {
    * @param {Image} image - The image object to draw.
    * @param {Vertex} position - The position to draw the the upper left corner at.
    * @param {Vertex} size - The x/y-size to draw the image with.
+   * @param {number=0.0} alpha - (optional, default=0.0) The transparency (1.0=opaque, 0.0=transparent).
    * @return {void}
    * @instance
    * @memberof drawutils
    **/
-  image(image: HTMLImageElement, position: Vertex, size: Vertex): void {
+  image(image: HTMLImageElement, position: Vertex, size: Vertex, alpha: number = 1.0): void {
     if (!image.complete || !image.naturalWidth) {
       // Avoid drawing un-unloaded or broken images
       return;
     }
     this.ctx.save();
+    this.ctx.globalAlpha = alpha;
     // Note that there is a Safari bug with the 3 or 5 params variant.
     // Only the 9-param varaint works.
     this.ctx.drawImage(
@@ -1003,10 +1010,12 @@ export class drawutils implements DrawLib<void> {
    * @memberof drawutils
    */
   polyline(vertices: Array<Vertex>, isOpen: boolean, color: string, lineWidth?: number) {
-    if (vertices.length <= 1) return;
+    if (vertices.length <= 1) {
+      return;
+    }
     this.ctx.save();
     this.ctx.beginPath();
-    this.ctx.lineWidth = lineWidth || 1.0;
+    this.ctx.lineWidth = (lineWidth || 1.0) * this.scale.x;
     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);
@@ -1141,13 +1150,19 @@ export class drawutils implements DrawLib<void> {
   path(pathData: SVGPathParams, color?: string, lineWidth?: number, options?: { inplace?: boolean }) {
     const d: SVGPathParams = options && options.inplace ? pathData : drawutilssvg.copyPathData(pathData);
     drawutilssvg.transformPathData(d, this.offset, this.scale);
-    this.ctx.strokeStyle = color;
+    if (color) {
+      this.ctx.strokeStyle = color;
+    }
     this.ctx.lineWidth = lineWidth || 1;
     if (this.fillShapes) {
-      this.ctx.fillStyle = color;
+      if (color) {
+        this.ctx.fillStyle = color;
+      }
       this.ctx.fill(new Path2D(d.join(" ")));
     } else {
-      this.ctx.strokeStyle = color;
+      if (color) {
+        this.ctx.strokeStyle = color;
+      }
       this.ctx.stroke(new Path2D(d.join(" ")));
     }
   }

package/src/ts/drawgl.ts

@@ -9,7 +9,8 @@
  * @modified 2022-02-03 Added the `lineWidth` param to the `crosshair` function.
  * @modified 2022-02-03 Added the `cross(...)` function.
  * @modified 2022-03-27 Added the `texturedPoly` function.
- * @version  0.0.7
+ * @modified 2022-07-26 Adding `alpha` to the `image(...)` function.
+ * @version  0.0.8
  **/
 
 import { CubicBezierCurve } from "./CubicBezierCurve";
@@ -279,11 +280,12 @@ export class drawutilsgl implements DrawLib<void> {
    * @param {Image} image - The image object to draw.
    * @param {Vertex} position - The position to draw the the upper left corner at.
    * @param {Vertex} size - The x/y-size to draw the image with.
+   * @param {number=0.0} alpha - (optional, default=0.0) The transparency (0.0=opaque, 1.0=transparent).
    * @return {void}
    * @instance
    * @memberof drawutils
    **/
-  image(image: HTMLImageElement, position: Vertex, size: Vertex) {
+  image(image: HTMLImageElement, position: Vertex, size: Vertex, alpha: number = 0.0) {
     // NOT YET IMPLEMENTED
   }
 

package/src/ts/drawutilssvg.ts

@@ -33,7 +33,8 @@
  * @modified 2022-02-03 Added the `cross(...)` function.
  * @modified 2022-03-26 Added the private `nodeDefs` and `bufferedNodeDefs` attributes.
  * @modified 2022-03-26 Added the `texturedPoly` function to draw textures polygons.
- * @version  1.6.0
+ * @modified 2022-07-26 Adding `alpha` to the `image(...)` function.
+ * @version  1.6.1
  **/
 
 import { CircleSector } from "./CircleSector";
@@ -594,11 +595,12 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
    * @param {Image} image - The image object to draw.
    * @param {Vertex} position - The position to draw the the upper left corner at.
    * @param {Vertex} size - The x/y-size to draw the image with.
+   * @param {number=0.0} alpha - (optional, default=0.0) The transparency (1.0=opaque, 0.0=transparent).
    * @return {void}
    * @instance
    * @memberof drawutilssvg
    **/
-  image(image: HTMLImageElement, position: Vertex, size: Vertex) {
+  image(image: HTMLImageElement, position: Vertex, size: Vertex, alpha: number = 1.0) {
     const node: SVGElement = this.makeNode("image");
 
     // We need to re-adjust the image if it was not yet fully loaded before.
@@ -609,6 +611,9 @@ export class drawutilssvg implements DrawLib<void | SVGElement> {
         node.setAttribute("width", `${image.naturalWidth * this.scale.x}`);
         node.setAttribute("height", `${image.naturalHeight * this.scale.y}`);
         node.setAttribute("display", null); // Dislay when loaded
+        // if (alpha) {
+        node.setAttribute("opacity", `${alpha}`);
+        // }
         node.setAttribute("transform", `translate(${this._x(position.x)} ${this._y(position.y)}) scale(${ratioX} ${ratioY})`);
       }
     };

package/src/ts/interfaces/DrawLib.ts

@@ -17,6 +17,7 @@
  * @modified 2021-11-19 Added the `color` param to the `label(...)` function.
  * @modified 2022-02-03 Added the `lineWidth` param to the `crosshair` function.
  * @modified 2022-02-03 Added the `cross(...)` function.
+ * @modified 2022-07-26 Adding `alpha` to the `image(...)` function.
  **/
 
 import { Bounds } from "../Bounds";
@@ -151,11 +152,12 @@ export interface DrawLib<R> {
    * @param {Image} image - The image object to draw.
    * @param {Vertex} position - The position to draw the the upper left corner at.
    * @param {Vertex} size - The x/y-size to draw the image with.
+   * @param {number=1.0} alpha - (optional, default=0.0) The transparency (1.0=opaque, 0.0=transparent).
    * @return {void}
    * @instance
    * @memberof DrawLib
    **/
-  image: (image: HTMLImageElement, position: Vertex, size: Vertex) => R;
+  image: (image: HTMLImageElement, position: Vertex, size: Vertex, alpha?: number) => R;
 
   /**
    * Draw an image at the given position with the given size.<br>

package/src/ts/interfaces/core.ts

@@ -14,6 +14,7 @@
  * @modified 2021-05-31 Splitted the large interfaces.ts file into this one and others.
  * @modified 2021-06-21 Added `IBounds.getCenter()`.
  * @modified 2021-11-16 Added `text` options to the `DrawConfig`.
+ * @modified 2022-08-01 Added `title` param to the `PBParams` interface.
  **/
 
 import { Vertex } from "../Vertex";
@@ -156,8 +157,8 @@ export interface Config {
  * For initialization the constructor needs a mix of config and draw-settings.
  */
 export interface PBParams extends Config {
-  // , DrawConfig {
-  // No additional attributes, just merge two interfaces.
+  title?: string; // Specify any hover tile here. It will be attached as a `title` attribute to the most elevated element.
+  // No more additional attributes, just merge two interfaces.
 }
 
 export interface DrawSettings {

package/src/ts/utils/datastructures/Color.ts

@@ -14,7 +14,9 @@
  * @modified 2021-11-07 Did the same with `saturate` and `desaturate`.
  * @modified 2021-11-07 Did the same with the `fadein` and `fadeout` functions.
  * @modified 2021-11-07 Added setRed, setGreen, setBlue, setHue, setSaturation, setLiminance functions.
- * @version 0.0.10
+ * @modified 2022-05-11 Modified the `clone` function by just copying the numeric calues, not re-calculating the whole color.
+ * @modified 2022-05-11 Fixed the `interpolate` function.
+ * @version 0.0.11
  **/
 
 /**
@@ -698,7 +700,16 @@ export class Color {
    * @return {Color} A clone of this color (in RGB mode).
    */
   clone(): Color {
-    return Color.makeRGB(this.r, this.g, this.b, this.a);
+    // return Color.makeRGB(this.r, this.g, this.b, this.a);
+    const col = new Color();
+    col.r = this.r;
+    col.g = this.g;
+    col.b = this.b;
+    col.a = this.a;
+    col.h = this.h;
+    col.s = this.s;
+    col.l = this.l;
+    return col;
   }
 
   /**
@@ -712,10 +723,10 @@ export class Color {
    * @return {Color} A clone of this color (in RGB mode).
    */
   interpolate(c: Color, t: number): Color {
-    this.r += (c.r - c.r) * t;
-    this.g += (c.g - c.g) * t;
-    this.b += (c.b - c.b) * t;
-    this.a += (c.a - c.a) * t;
+    this.r += (c.r - this.r) * t;
+    this.g += (c.g - this.g) * t;
+    this.b += (c.b - this.b) * t;
+    this.a += (c.a - this.a) * t;
     return this;
   }
 } // END class