plotboilerplate 1.17.0 → 1.18.0

package/README.md

@@ -47,12 +47,18 @@ often use for the visualization of 2D geometries. Basic features are
   - text
     ([docs](https://plotboilerplate.io/docs_typedoc/classes/pbtext.html "PBText class"),
     [example](https://plotboilerplate.io/repo/demos/basic-PBText "PBText example"))
-- configuration of the canvas behavior (fullsize, interaction, raster)
-- mouse interaction (zoom, pan, drag elements)
-- keyboard interaction
-- touch interaction for dragging vertices (mobile devices: zoom, pan, drag elements)
-
-The compressed library has 128kb.
+- configuration of the canvas behavior
+  - fullsize and auto-resizing
+  - enable/disable mouse, touch or keyboard interaction
+  - draw rasters
+  - default colors and darkmode
+- mouse and touch interaction
+  - zoom
+  - pan
+  - drag and select elements
+- keyboard interaction customizable
+
+The compressed library has 133kb.
 
 ## Install the package via npm
 
@@ -143,6 +149,8 @@ globalThis.addEventListener("load", () => {
 });
 ```
 
+For a guide of how to [Getting Started click here](https://github.com/IkarosKappler/plotboilerplate/blob/master/Getting-Started.md "Getting Started click here.").
+
 A full working demo repository about the [Usage with Typescript is here](https://github.com/IkarosKappler/plotboilerplate-typescript-example "usage with Typescript is here").
 
 ### Screenshot
@@ -442,6 +450,55 @@ vert.listeners.addDragListener(function (e) {
 - Touch & move (2 fingers): Pan the area
 - Touch & pinch: Zoom in/out
 
+## Custom keyboard events
+
+```javascript
+new KeyHandler({ trackAll: true })
+  .down("enter", function () {
+    console.log("ENTER was hit.");
+  })
+  .press("enter", function () {
+    console.log("ENTER was pressed.");
+  })
+  .up("enter", function () {
+    console.log("ENTER was released.");
+  })
+  .down("e", function () {
+    console.log("e was hit. shift is pressed?", keyHandler.isDown("shift"));
+  })
+  .up("spacebar", function () {
+    console.log("spacebar was released.");
+  });
+```
+
+For a list of all supported key codes see [Full list of supported key codes](https://github.com/IkarosKappler/plotboilerplate/blob/master/keycodes.md "Full list of supported key codes").
+
+## Custom mouse event
+
+```javascript
+new MouseHandler(document.getElementById("mycanvas"))
+  .drag(function (e) {
+    console.log("Mouse dragged: " + JSON.stringify(e));
+    if (e.params.leftMouse);
+    else if (e.params.rightMouse);
+  })
+  .move(function (e) {
+    console.log("Mouse moved: " + JSON.stringify(e.params));
+  })
+  .up(function (e) {
+    console.log("Mouse up. Was dragged?", e.params.wasDragged);
+  })
+  .down(function (e) {
+    console.log("Mouse down.");
+  })
+  .click(function (e) {
+    console.log("Click.");
+  })
+  .wheel(function (e) {
+    console.log("Wheel. delta=" + e.deltaY);
+  });
+```
+
 ## Build the package
 
 [Compile and build howto](https://github.com/IkarosKappler/plotboilerplate/blob/master/build.md "Compile and build howto")

package/changelog.md

@@ -1,5 +1,30 @@
 # Changelog
 
+- 2022-09-11
+  - Added the extended circle-line-intersection demo (because I am stupid and need visual confirmation).
+- 2022-08-23
+  - Added the `Circle.lineIntersection(Vertex,Vertex)` function.
+  - Added the `Circle.closestPoint(XYCoords)` function.
+  - Fixed a type issue in the `draw.polyline` function.
+  - Fixed a type issue in the `draw.setConfiguration` function.
+  - Fixed a type issue in the `draw.path` function.
+- 2022-08-16
+  - MouseHandler: Fixed a bug in the mouse button detection.
+- 2022-08-15
+  - Added the `Circle.containsPoint(XYCoords)` function.
+- 2022-08-01
+  - Added `title` param to the `PBParams` interface.
+- 2022-07-26
+  - Adding `alpha` to the `draw.image(...)` function.
+- 2022-06-02
+  - Adding the demo 42 (Hick's Hexagons).
+- 2022-06-01
+  - Tweaked the `draw.polyline` function; lineWidth now scales with scale.x.
+- 2022-05-11
+- Adding new demo: raindrops.
+- 2022-05-11
+  - Modified the `Color.clone` function by just copying the numeric calues, not re-calculating the whole color.
+  - Fixed the `Color.interpolate` function.
 - 2022-03-27
   - Added the `texturedPoly` function to the `DrawLib` interface.
   - Added the `texturedPoly` function to the `drawutils` and `drawutilssvg` class.

package/dist/index.esm.js

@@ -1472,6 +1472,20 @@ class Bounds {
     toString() {
         return `{ min: ${this.min.toString()}, max : ${this.max.toString()}, width: ${this.width}, height : ${this.height} }`;
     }
+    /**
+     * Clone this bounds object (create a deep clone).
+     *
+     * Note: the returned format might change in the future, so please do not
+     * rely on the returned string format.
+     *
+     * @method clone
+     * @instance
+     * @memberof Bounds
+     * @returns {string} Creates a deep clone of this bounds object. The returned object's `min` and `max` instances are `Vertex` instances.
+     */
+    // clone() {
+    //   return new Bounds(new Vertex(this.min.x, this.min.y), new Vertex(this.max.x, this.max.y));
+    // }
     /**
      * Compute the minimal bounding box for a given set of vertices.
      *
@@ -3931,7 +3945,10 @@ class Line extends VertTuple {
  * @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
  **/
 /**
  * @classdesc A simple circle: center point and radius.
@@ -3962,6 +3979,18 @@ class Circle {
         this.center = center;
         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) {
+        return this.center.distance(point) < this.radius;
+    }
     /**
      * Check if the given circle is fully contained inside this circle.
      *
@@ -4073,6 +4102,71 @@ class Circle {
         var y4 = p2.y + (h * (p1.x - p0.x)) / d;
         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, b) {
+        // 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 = 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 = transA.distance(transB);
+        const det = transA.x * transB.y - transA.y * transB.x;
+        const distSquared = dist * dist;
+        const radiusSquared = this.radius * this.radius;
+        // Check if circle and line have an intersection at all
+        if (radiusSquared * distSquared - det * det < 0) {
+            return null;
+        }
+        const belowSqrt = this.radius * this.radius * dist * dist - det * det;
+        const sqrt = 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) {
+        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
@@ -4228,7 +4322,8 @@ CircleSector.circleSectorUtils = {
  * @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
  **/
 const RAD_TO_DEG = 180 / Math.PI;
 /**
@@ -4610,11 +4705,12 @@ class drawutilssvg {
      * @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, position, size) {
+    image(image, position, size, alpha = 1.0) {
         const node = this.makeNode("image");
         // We need to re-adjust the image if it was not yet fully loaded before.
         const setImageSize = (image) => {
@@ -4624,6 +4720,9 @@ class drawutilssvg {
                 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})`);
             }
         };
@@ -5587,7 +5686,12 @@ drawutilssvg.HEAD_XML = [
  * @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
  **/
 // Todo: rename this class to Drawutils?
 /**
@@ -5641,7 +5745,7 @@ class drawutils {
      * @param {DrawLibConfiguration} configuration - The new configuration settings to use for the next render methods.
      */
     setConfiguration(configuration) {
-        this.ctx.globalCompositeOperation = configuration.blendMode;
+        this.ctx.globalCompositeOperation = configuration.blendMode || "source-over";
     }
     /**
      * This method shouled be called each time the currently drawn `Drawable` changes.
@@ -5724,16 +5828,18 @@ class drawutils {
      * @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, position, size) {
+    image(image, position, size, alpha = 1.0) {
         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(image, 0, 0, image.naturalWidth - 1, // There is this horrible Safari bug (fixed in newer versions)
@@ -6343,11 +6449,12 @@ class drawutils {
      * @memberof drawutils
      */
     polyline(vertices, isOpen, color, lineWidth) {
-        if (vertices.length <= 1)
+        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);
@@ -6464,14 +6571,20 @@ class drawutils {
     path(pathData, color, lineWidth, options) {
         const d = 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(" ")));
         }
     }
@@ -6516,7 +6629,8 @@ drawutils.helpers = {
  * @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
  **/
 /**
  * @classdesc A wrapper class for basic drawing operations. This is the WebGL
@@ -6706,11 +6820,12 @@ class drawutilsgl {
      * @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, position, size) {
+    image(image, position, size, alpha = 0.0) {
         // NOT YET IMPLEMENTED
     }
     /**
@@ -8254,7 +8369,8 @@ KeyHandler.KEY_CODES = {
  * @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
@@ -8344,8 +8460,8 @@ 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 = {};
@@ -8414,26 +8530,27 @@ 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}
      */
-    mkParams(e, eventName) {
-        const rel = this.relPos(e);
-        const xEvent = e;
+    mkParams(event, eventName) {
+        var _a, _b;
+        const rel = this.relPos(event);
+        const xEvent = event;
         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,
+            leftButton: event.button === 0,
+            middleButton: event.button === 1,
+            rightButton: event.button === 2,
+            mouseDownPos: (_a = this.mouseDownPos) !== null && _a !== void 0 ? _a : { x: NaN, y: NaN },
+            draggedFrom: (_b = this.mouseDragPos) !== null && _b !== void 0 ? _b : { 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;
     }
@@ -9866,7 +9983,8 @@ VEllipseSector.ellipseSectorUtils = {
  * @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.
@@ -9959,6 +10077,7 @@ 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) {
         /**
@@ -10174,6 +10293,11 @@ 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 = [];