plotboilerplate 1.23.2 → 1.23.3

package/src/cjs/geomutils.d.ts

@@ -2,16 +2,47 @@
  * @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 { Vertex } from "./Vertex";
+import { XYCoords } from "./interfaces";
 /**
  * A collection of usefull geometry utilities.
  *
  * @global
  **/
 export declare 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;
+    /**
+     * 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;
+    /**
+     * 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;
     /**
      * Compute the n-section of the angle – described as a triangle (A,B,C) – in point A.
      *

package/src/cjs/geomutils.js

@@ -3,7 +3,10 @@
  * @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
  **/
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.geomutils = void 0;
@@ -15,6 +18,49 @@ var Triangle_1 = require("./Triangle");
  * @global
  **/
 exports.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: function (angle) {
+        // Source: https://forums.codeguru.com/showthread.php?384172-get-angle-into-range-0-2*pi
+        var new_angle = 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: function (x1, y1, x2, y2) {
+        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: function (vertA, vertB) {
+        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/cjs/geomutils.js.map

@@ -1 +1 @@
-{"version":3,"file":"geomutils.js","sourceRoot":"","sources":["../ts/geomutils.ts"],"names":[],"mappings":";AAAA;;;;;IAKI;;;AAEJ,+BAA8B;AAC9B,uCAAsC;AAGtC;;;;IAII;AACS,QAAA,SAAS,GAAG;IACvB;;;;;;;;;;OAUG;IACH,UAAU,YAAC,EAAU,EAAE,EAAU,EAAE,EAAU,EAAE,CAAS;QACtD,IAAM,QAAQ,GAAa,IAAI,mBAAQ,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;QACpD,IAAM,MAAM,GAAS,IAAI,WAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QACtC,IAAM,MAAM,GAAS,IAAI,WAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QACtC,8DAA8D;QAC9D,IAAI,WAAW,GAAW,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC/C,iEAAiE;QACjE,2DAA2D;QAC3D,IAAM,SAAS,GAAY,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;QAEtD,yDAAyD;QACzD,IAAI,WAAW,GAAG,CAAC;YAAE,WAAW,GAAG,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,WAAW,CAAC;QAC7D,IAAI,CAAC,SAAS;YAAE,WAAW,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;QAE/D,+DAA+D;QAC/D,IAAM,UAAU,GAAW,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QACtE,IAAM,WAAW,GAAW,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;QAEzD,IAAI,MAAM,GAAgB,EAAE,CAAC;QAC7B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3B,qCAAqC;YACrC,MAAM,CAAC,IAAI,CAAC,IAAI,WAAI,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAS,CAAC,CAAC;QACtG,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;;;OAOG;IACH,OAAO,YAAC,CAAS,EAAE,GAAW;QAC5B,WAAW;QACX,6FAA6F;QAC7F,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;IACjC,CAAC;IAED;;;;;;;;OAQG;IACH,oBAAoB;IACpB,UAAU,YAAC,CAAS,EAAE,GAAW,EAAE,GAAW;QAC5C,OAAO,GAAG,GAAG,iBAAS,CAAC,OAAO,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,GAAG,GAAG,CAAC,CAAC;IACrD,CAAC;CACF,CAAC"}
+{"version":3,"file":"geomutils.js","sourceRoot":"","sources":["../ts/geomutils.ts"],"names":[],"mappings":"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"}

package/src/cjs/utils/algorithms/PolygonInset.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Calculate the inset of any non-self-overlapping polygon.
+ *
+ * The polygon may be
+ *  - convex or non-convex
+ *  - self-intersecting
+ *
+ * The algorithms will
+ *  - first construct a general offset polygon which may be corrupt due to ouf-of-bounds or in illegal-area problems.
+ *  - then dissect the possibly self-intersecting inset polygon into separate simple polygons.
+ *  - then detect for each if it's out of bounds or in some illegal area.
+ *  - keeping only the valid ones.
+ *
+ * @required sutherlandHodgman
+ * @required splitPolygonToNonIntersecting
+ *
+ * @author   Ikaros Kappler
+ * @date     2024-11-04 Ported the script to a class.
+ * @modified 2024-12-02 Ported to Typescript.
+ */
+import { Line } from "../../Line";
+import { Polygon } from "../../Polygon";
+import { Vertex } from "../../Vertex";
+export interface IPolygonInsetOptions {
+    innerPolygonOffset: number;
+    maxPolygonSplitDepth?: number;
+    intersectionEpsilon?: number;
+    removeEars?: boolean;
+}
+export declare class PolygonInset {
+    /**
+     * The polygon to work with.
+     */
+    readonly polygon: Polygon;
+    /**
+     * The input polygon, but without ear edges.
+     */
+    optimizedPolygon: Polygon;
+    /**
+     * The original polygon as a sequence of line objects. This is easier to use than a list of points.
+     */
+    originalPolygonLines: Array<Line>;
+    /**
+     * The simple inset lines, directly generated by offsetting the original polygon lines by the given amount.
+     */
+    insetLines: Array<Line>;
+    /**
+     * The cropped inset lines that makes up the first direct iteration of the inset polygon.
+     * This one will probably be self-intersecting.
+     */
+    insetPolygonLines: Array<Line>;
+    /**
+     * The inset polygon lines resembling an actual polygon instance (not just a sequence of lines).
+     */
+    insetPolygon: Polygon;
+    /**
+     * Each polygon line and it's offsetted inset-line resemble a rectangular polygon.
+     * Array<Polygon> with 4 vertices each
+     **/
+    insetRectanglePolygons: Array<Polygon>;
+    /**
+     * The inset polygon split up into simple non-self-intersecting polygons.
+     * Represented as a list of vertex-lists. Each sub-list represents a single polygon.
+     */
+    splitPolygons: Array<Array<Vertex>>;
+    /**
+     * The final result: all valid split-polygons. These are making up the actual polygon inset.
+     * Note: list may be empty. Depending on the offset amount there is not a guaranteed offset polygon existing.
+     */
+    filteredSplitPolygons: Array<Array<Vertex>>;
+    /**
+     * Constructs a new PolygonInset instance with the underlying given polygon to work with.
+     *
+     * Please note that the algorithm will reverse the vertex order if the given polygon
+     * is not clockwise.
+     *
+     * @param {Polygon} polygon - The polygon to calculate the offset for.
+     */
+    constructor(polygon: Polygon);
+    /**
+     * This is the main method.
+     *
+     * Call this with the required option params to compute your desired offset polygon(s).
+     *
+     * @param {number} options.innerPolygonOffset - The offset to use. Should be a positive number. Correct result for negative numbers are not guaranteed.
+     * @param {number?} options.maxPolygonSplitDepth - (default is the number of polygon.vertices) The maximum amount of recursive stepts to simplify the complex first iteration of the offset polygon.
+     * @param {number?} options.intersectionEpsilon - (default is 1.0) The epsilon to use for detecting overlapping polygons. This indicates a tolerance value, because directly adjecent polygons may have a little arithmetic intersection area.
+     * @returns {Array<Array<Vertex>>} A list of vertex-lists, each one representing a simple polygon from the offset-polygons.
+     */
+    computeOutputPolygons(options: IPolygonInsetOptions): Array<Array<Vertex>>;
+    /**
+     * This method transforms each polygon line into a new line
+     * by moving it to the inside direction of the polygon (by the given `insetAmount`).
+     *
+     * @param {Array<Line>} polygonLines
+     * @param {number} insetAmount
+     * @return {Array<Line>} The transformed lines. The result array has the same length and order as the input array.
+     */
+    private _collectInsetLines;
+    /**
+     * For a sequence of inset polygon lines get the inset polygon by detecting
+     * useful intersections (by cropping or extending them).
+     *
+     * The returned lines resemble a new polygon.
+     *
+     * Please note that the returned polygon can be self-intersecting!
+     *
+     * @param {Array<Line>} insetLines
+     * @returns {Array<Line>} The cropped or exented inset polygon lines.
+     */
+    private _collectInsetPolygonLines;
+    /**
+     * Converts two lists (same length) of original polygon lines and inset lines (interpreted as
+     * pairs) to a list of rectangular polyons.
+     *
+     * @static
+     * @param {Array<Line>} originalPolygonLines
+     * @param {Array<Line>} insetLines
+     * @returns {Array<Polygon>} A list of rectangular polygons; each returned polyon has exactly four vertices.
+     */
+    private _collectRectangularPolygonInsets;
+    /**
+     * Converts a sequence of (hopefully adjacent) lines to a polygon by using all second line vertices `b`.
+     *
+     * @static
+     * @param insetPolygonLines
+     * @returns
+     */
+    private static convertToBasicInsetPolygon;
+    /**
+     * Optimize the inset polygon by removing critical `ear` edges.
+     * Such an is identified by: the edge itself is completely located inside its neighbours inset rectangle.
+     *
+     * In this process multiple edges from the ear might be dropped and two adjacent edges get a new
+     * common intersection point.
+     *
+     * Note: this method is not working as expected in all cases and quite experimental.
+     *
+     * @param insetPolygon
+     * @param insetRectangles
+     */
+    private static _optimizeInsetPolygon;
+    private static _locateExcessiveEarEdge;
+    private static _rectangleFullyContainsLine;
+    /**
+     * Filter split polygons: only keep those whose vertices are all contained inside the original polygon.
+     * Reason: scaling too much will result in excessive translation beyond the opposite bounds of the polygon (like more than 200% of possible insetting).
+     *
+     * @param {Array<Array<Vertex>>} splitPolygonsVertices
+     * @param {Polygon} originalPolygon
+     * @return {Array<Array<Vertex>>} The filtered polygon list.
+     */
+    private static _filterInnerSplitPolygonsByOriginalBounds;
+    /**
+     * Filter split polygons: only keep those that do not (signifiantly) interset with any rectangles.
+     *
+     * @static
+     * @param {Array<Array<Vertex>>} splitPolygonsVertices
+     * @param {Array<Polygon>} insetRectanglePolygons
+     * @param {number?=1.0} intersectionEpsilon - (optional, default is 1.0) A epsislon to define a tolerance for checking if two polygons intersect.
+     */
+    private static _filterInnerSplitPolygonsByCoverage;
+    /**
+     * This private method will reverse each polygon's vertex order that's not clockwise.
+     *
+     * @param {Array<Vertex[]>} polygons
+     */
+    private static _assertAllPolygonsAreClockwise;
+    /**
+     * This private method will revert the vertex order if the polygon is not clockwise.
+     *
+     * @param {Vertex[]} polygonVerts
+     */
+    private static _assertPolygonIsClockwise;
+    /**
+     * For simplification I'm using a callback generator function here.
+     *
+     * @param splitPolyVerts
+     * @param eps
+     * @param _splitPolyIndex
+     * @returns {Function} The callback for an `Array.some` parameter.
+     */
+    private static _hasIntersectionCallback;
+}