plotboilerplate 1.27.1 → 1.28.0

package/src/_esm/src/ts/utils/algorithms/CircleIntersections.js

@@ -0,0 +1,303 @@
+/**
+ * @author   Ikaros Kappler
+ * @date     2020-10-05
+ * @modified 2021-02-08 Fixed a lot of es2015 compatibility issues.
+ * @modified 2024-02-23 Fixed some null-type conflicts.
+ * @version  1.0.2
+ * @file CircleIntersections
+ * @public
+ **/
+import { arrayFill } from "./arrayFill";
+import { matrixFill } from "./matrixFill";
+import { CircleSector } from "../../CircleSector";
+import { Line } from "../../Line";
+import { CircularIntervalSet } from "../datastructures/CircularIntervalSet";
+/**
+ * @classdesc A script for finding the intersection points of two or
+ * multiple circles (the 'radical lines').
+ *
+ * Based on the C++ implementation by Robert King
+ *    https://stackoverflow.com/questions/3349125/circle-circle-intersection-points
+ * and the 'Circles and spheres' article by Paul Bourke.
+ *    http://paulbourke.net/geometry/circlesphere/
+ *
+ * @requires arrayFill
+ * @requires matrixFill
+ * @requires Circle
+ * @requires IndexPair
+ * @requires Matrix
+ * @requires Interval
+ * @requires Line
+ * @requires CirularIntervalSet
+ */
+export class CircleIntersections {
+    /**
+     * Find all connected outer path partitions.
+     *
+     * @method findOuterPartitions
+     * @static
+     * @memberof CircleIntersections
+     * @param {Array<Circle>} circles - The circles to find intersections for.
+     * @param {Array<CircularIntervalSet>} intervalSets - The determined interval sets (see `findOuterCircleIntervals`).
+     * @return {Array<Array<IndexPair>>} An array of paths, each defined by a sequence of IndexPairs adressing circle i and interval j.
+     **/
+    static findOuterPartitions(circles, intervalSets) {
+        // For tracking which interval we already used for detecting the partition
+        // we need a matrix; find the maximal interval length.
+        let maxSetLength = 0;
+        for (var i = 0; i < intervalSets.length; i++) {
+            maxSetLength = Math.max(maxSetLength, intervalSets[i].intervals.length);
+        }
+        const usedIntervals = matrixFill(intervalSets.length, maxSetLength, false);
+        var path = null;
+        var pathList = [];
+        while ((path = CircleIntersections.findOuterPartition(circles, intervalSets, usedIntervals)) != null) {
+            pathList.push(path);
+        }
+        return pathList;
+    }
+    /**
+     * Find all connected outer path partitions (as CircleSectors).
+     *
+     * @method findOuterPartitionsAsSectors
+     * @static
+     * @memberof CircleIntersections
+     * @param {Array<Circle>} circles - The circles to find intersections for.
+     * @param {Array<CircularIntervalSet>} intervalSets - The determined interval sets (see `findOuterCircleIntervals`).
+     * @return {Array<Array<CircleSector>>} An array of paths, each defined by a sequence of SircleSectors.
+     **/
+    static findOuterPartitionsAsSectors(circles, intervalSets) {
+        const partitions = CircleIntersections.findOuterPartitions(circles, intervalSets);
+        const partitionsAsArcs = [];
+        for (var p = 0; p < partitions.length; p++) {
+            const path = partitions[p];
+            const pathAsArcs = [];
+            for (var i = 0; i < path.length; i++) {
+                const circleIndex = path[i].i;
+                const circle = circles[circleIndex];
+                var interval = intervalSets[path[i].i].intervals[path[i].j];
+                // Params: circle, startAngle, endAngle
+                pathAsArcs.push(new CircleSector(circle, interval[0], interval[1]));
+            } // END for
+            partitionsAsArcs.push(pathAsArcs);
+        } // END for
+        return partitionsAsArcs;
+    }
+    /**
+     * Build the n*n intersection matrix: contains the radical line at (i,j) if circle i and circle j do intersect;
+     * conatins null at (i,j) otherwise.
+     *
+     * Note that this matrix is symmetrical: if circles (i,j) intersect with line (A,B), then also circles (j,i) intersect
+     * with line (B,A).
+     *
+     * The returned two-dimensional matrix (array) has exactly as many entries as the passed circle array.
+     *
+     * @method buildRadicalLineMatrix
+     * @static
+     * @memberof CircleIntersections
+     * @param {Array<Circle>} circles - The circles to find intersections for.
+     * @return {Array<Array<Line>>} A 2d-matrix containing the radical lines where circles intersect.
+     **/
+    static buildRadicalLineMatrix(circles) {
+        var radicalLines = [];
+        for (var i = 0; i < circles.length; i++) {
+            if (!radicalLines[i]) {
+                radicalLines[i] = arrayFill(circles.length, null);
+            }
+            for (var j = 0; j < circles.length; j++) {
+                if (i == j)
+                    continue;
+                if (radicalLines[i][j])
+                    continue;
+                radicalLines[i][j] = circles[i].circleIntersection(circles[j]);
+                // Build symmetrical matrix
+                var tmpRadLine = radicalLines[i][j];
+                if (tmpRadLine) {
+                    if (!radicalLines[j]) {
+                        radicalLines[j] = arrayFill(circles.length, null);
+                    }
+                    // Use reverse line
+                    radicalLines[j][i] = new Line(tmpRadLine.b, tmpRadLine.a);
+                }
+            }
+        }
+        return radicalLines;
+    }
+    /**
+     * Find all circles (indices) which are completely located inside another circle.
+     *
+     * The returned array conatins the array indices.
+     *
+     * @method findInnerCircles
+     * @static
+     * @memberof CircleIntersections
+     * @param {Array<Circle>} circles - The circles to find intersections for.
+     * @return {Array<number>}
+     **/
+    static findInnerCircles(circles) {
+        const innerCircleIndices = [];
+        for (var i = 0; i < circles.length; i++) {
+            for (var j = 0; j < circles.length; j++) {
+                if (i == j)
+                    continue;
+                if (circles[j].containsCircle(circles[i])) {
+                    innerCircleIndices.push(i);
+                }
+            }
+        }
+        return innerCircleIndices;
+    }
+    /**
+     * Calculate all outer circle intervals (sections that belong to the outermost line), dermined by the given
+     * circles and their radical lines.
+     *
+     * The returned array contains IntervalSets - one for each circle - indicating the remaining circle sections.
+     *
+     * @method findOuterCircleIntervals
+     * @static
+     * @memberof CircleIntersections
+     * @param {Array<Circle>} circles - The circles to find intersections for.
+     * @param {Array<Line>} intersectionMatrix
+     * @return {Array<number>}
+     **/
+    static findOuterCircleIntervals(circles, intersectionMatrix) {
+        const intervalSets = [];
+        for (var i = 0; i < circles.length; i++) {
+            intervalSets[i] = new CircularIntervalSet(0, 2 * Math.PI);
+            for (var j = 0; j < circles.length; j++) {
+                if (i == j)
+                    continue;
+                if (intersectionMatrix[i][j] !== null) {
+                    // const interval : Interval = CircleIntersections.radicalLineToInterval( circle, radicalLine );
+                    CircleIntersections.handleCircleInterval(circles[i], intersectionMatrix[i][j], intervalSets[i]);
+                }
+                else if (circles[j].containsCircle(circles[i])) {
+                    intervalSets[i].clear();
+                }
+            }
+        }
+        return intervalSets;
+    }
+    /**
+     * Calculate the next connected partition from the given set of circles and outer path intervals. The function
+     * will pick a random unused circle interval and detect all adjacent intervals until a closed partition
+     * was found.
+     *
+     * If an interval (circle section) was already visited will be stored in the `usedIntervalSetRecords` matrix (thus
+     * is must be large enough to map all sections).
+     *
+     * The returned array contains IndexPairs (i,j) - one for each circle i - indicating the used circle section j.
+     *
+     * @method findOuterPartition
+     * @static
+     * @memberof CircleIntersections
+     * @param {Array<Circle>} circles - The circles to find intersections for.
+     * @param {Array<CircularIntervalSet>} intervalSets - The circle intervals that form the intersection outline.
+     * @param {Matrix<boolean>} usedIntervals - A matrix for remembering which circle intervals were always used.
+     * @return {Array<Indexpair>|null} The next partition or `null` if no more can be found.
+     **/
+    static findOuterPartition(circles, intervalSets, usedIntervals) {
+        let intLocation = CircleIntersections.randomUnusedInterval(intervalSets, usedIntervals);
+        const path = [];
+        while (intLocation != null) {
+            path.push(intLocation);
+            usedIntervals[intLocation.i][intLocation.j] = true;
+            intLocation = CircleIntersections.findAdjacentInterval(circles, intLocation, intervalSets, usedIntervals, 0.001);
+        }
+        return path.length == 0 ? null : path;
+    }
+    /**
+     * Convert a radical line (belonging to a circle) into an interval: start angle and end angle.
+     *
+     * @method radicalLineToInterval
+     * @static
+     * @private
+     * @memberof CircleIntersections
+     * @param {Circle} circle - The circle itself.
+     * @param {Line} radicaLine - The radical line to convert (must have two intersection points on the circle).
+     * @return {Interval} The interval `[startAngle,endAngle]` determined by the radical line.
+     **/
+    static radicalLineToInterval(circle, radicalLine) {
+        // Get angle sections in the circles
+        const lineA = new Line(circle.center, radicalLine.a);
+        const lineB = new Line(circle.center, radicalLine.b);
+        let angleA = lineA.angle();
+        let angleB = lineB.angle();
+        // Map angles to [0 ... 2*PI]
+        // (the angle() function might return negative angles in [-PI .. 0 .. PI])
+        if (angleA < 0)
+            angleA = Math.PI * 2 + angleA;
+        if (angleB < 0)
+            angleB = Math.PI * 2 + angleB;
+        return [angleA, angleB];
+    }
+    /**
+     * This is a helper fuction used by `findOuterCircleIntervals`.
+     *
+     * It applies the passed radical line by intersecting the remaining circle sections with the new section.
+     *
+     * @method handleCircleInterval
+     * @static
+     * @private
+     * @memberof CircleIntersections
+     * @param {Circle} circle - The circles to find intersections for.
+     * @param {Line} radicalLine - The radical line to apply.
+     * @param {CircularIntervalSet} intervalSet - The CircularIntervalSet to use (must have left and right border: 0 and 2*PI).
+     * @return {void}
+     **/
+    static handleCircleInterval(circle, radicalLine, intervalSet) {
+        const interval = CircleIntersections.radicalLineToInterval(circle, radicalLine);
+        intervalSet.intersect(interval[1], interval[0]);
+    }
+    /**
+     * Pick a random unused circle interval. This function is used by the `findOuterPartition` function, which
+     * starts the detection with any random section.
+     *
+     * @method randomUnusedInterval
+     * @static
+     * @private
+     * @memberof CircleIntersections
+     * @param {Array<CircularIntervalSet>} intervalSets - An array of all available interval sets/intervals.
+     * @param {Matrix<boolean>} usedIntervals - A matrix indicating which intervals have already been used/visited by the algorithm
+     * @return {IndexPair|null}
+     **/
+    static randomUnusedInterval(intervalSets, usedIntervals) {
+        for (var i = 0; i < intervalSets.length; i++) {
+            for (var j = 0; j < intervalSets[i].intervals.length; j++) {
+                if (!usedIntervals[i][j]) {
+                    return { i: i, j: j };
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Find the next adjacent circle interval for the given interval.
+     * starts the detection with any random section.
+     *
+     * @method randomUnusedInterval
+     * @static
+     * @private
+     * @memberof CircleIntersections
+     * @param {Array<CircularIntervalSet>} intervalSets - An array of all available interval sets/intervals.
+     * @param {Matrix<boolean>} usedIntervals - A matrix indicating which intervals have already been used/visited by the algorithm
+     * @return {IndexPair|null}
+     **/
+    static findAdjacentInterval(circles, intLocation, intervalSets, usedIntervalSetRecords, epsilon) {
+        var curInterval = intervalSets[intLocation.i].intervals[intLocation.j];
+        var curEndPoint = circles[intLocation.i].vertAt(curInterval[1]);
+        for (var i = 0; i < intervalSets.length; i++) {
+            for (var j = 0; j < intervalSets[i].intervals.length; j++) {
+                if (usedIntervalSetRecords[i][j]) {
+                    continue;
+                }
+                var interval = intervalSets[i].intervals[j];
+                var startPoint = circles[i].vertAt(interval[0]);
+                if (curEndPoint.distance(startPoint) < epsilon)
+                    return { i: i, j: j };
+            }
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=CircleIntersections.js.map

package/src/_esm/src/ts/utils/algorithms/CircleIntersections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CircleIntersections.js","sourceRoot":"","sources":["../../../../../ts/utils/algorithms/CircleIntersections.ts"],"names":[],"mappings":"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"}

package/src/_esm/src/ts/utils/algorithms/ContourLineDetection.d.ts

@@ -0,0 +1,150 @@
+/**
+ * A function to detect contour lines from 3D terrain data.
+ *
+ * For usage see demo `./demos/48-contour-plot`.
+ *
+ * @requires detectPaths
+ * @requires GenericPath
+ * @author   Ikaros Kappler
+ * @date     2023-11-05
+ * @modified 2023-11-20 Addig path detection on a triangle based grid.
+ * @version  1.0.0
+ */
+import { Line } from "../../Line";
+import { IDataGrid2d } from "../datastructures/DataGrid2d";
+import { GenericPath } from "../datastructures/GenericPath";
+export declare class ContourLineDetection {
+    private dataGrid;
+    private rawLinearPathSegments;
+    static CLOSE_GAP_TYPE_NONE: number;
+    static CLOSE_GAP_TYPE_ABOVE: number;
+    static CLOSE_GAP_TYPE_BELOW: number;
+    debugMode: boolean;
+    /**
+     * Creates a new instance for calculating contour lines from the given data grid.
+     * @param {IDataGrid2d<number>} dataGrid - The data grid to use. Must not contain any NaN or null values.
+     * @param {boolean=?} debugMode - (optional) Pass `true` to log warnings on (rare) critical edge cases where the algorithm might fail.
+     */
+    constructor(dataGrid: IDataGrid2d<number>, debugMode?: boolean);
+    /**
+     * Detect contour paths from the underlying data source.
+     *
+     * @param {number} criticalHeightValue - The height value. If above data's maximum or below data's minimum then the result will be empty (no intersections).
+     * @param {number} options.closeGapType - `CLOSE_GAP_TYPE_NONE` or `CLOSE_GAP_TYPE_ABOVE` or `CLOSE_GAP_TYPE_BELOW`.
+     * @param {boolean=false} options.useTriangles - If set to true the detection will split each face3 quad into two triangle faces.
+     * @param {pathDetectEpsilon=0.000001} options.pathDetectEpsilon - (optional) The epsilon to tell if two points are located 'in the same place'. Used for connected path detection. If not specified the value `0.0000001` is used.
+     * @param {pointEliminationEpsilon=0.0000001} options.pointEliminationEpsilon - (optional) The epsilon for duplicate point elimination (default is 0.000001).
+     * @param {function?} onRawSegmentsDetected - (optional) Get the interim result of all detected single lines before path detection starts; DO NOT MODIFY the array.
+     * @returns {Array<GenericPath>} - A list of connected paths that resemble the contour lines of the data/terrain at the given height value.
+     */
+    detectContourPaths(criticalHeightValue: number, options?: {
+        closeGapType: number;
+        useTriangles?: boolean;
+        pointEliminationEpsilon?: number;
+        pathDetectEpsilon?: number;
+        onRawSegmentsDetected?: (rawSegmentsDoNotModifiy: Array<Line>) => void;
+    }): Array<GenericPath>;
+    /**
+     * This function will calculate a single intersecion line of the given face4 data
+     * segment. If the given face does not intersect with the plane at the given `heightValue`
+     * then no segments will be stored.
+     *
+     * @param {number} xIndex - The x position (index) of the data face.
+     * @param {number} yIndex - The y position (index) of the data face.
+     * @param {[[number,number],[number,number]]} heightFace - The data sample that composes the face4 as a two-dimensional number array.
+     * @param {number} heightValue - The height value of the intersection plane to check for.
+     * @returns {Line|null}
+     */
+    private findHeight4FaceIntersectionLine;
+    /**
+     * This function will calculate a single intersecion line of the given face4 data
+     * segment. If the given face does not intersect with the plane at the given `heightValue`
+     * then no segments will be stored.
+     *
+     * @param {number} xIndex - The x position (index) of the data face.
+     * @param {number} yIndex - The y position (index) of the data face.
+     * @param {[[number,number],[number,number]]} heightFace - The data sample that composes the face4 as a two-dimensional number array.
+     * @param {number} heightValue - The height value of the intersection plane to check for.
+     * @returns {Line|null}
+     */
+    private findHeightFaceIntersectionLines;
+    /**
+     * This function will calculate a single intersecion line of the given face3 data
+     * segment. If the given face does not intersect with the plane at the given `heightValue`
+     * then no segments will be stored.
+     *
+     * @param {number} xIndexA - The x position (index) of the first triangle data point.
+     * @param {number} yIndexA - The y position (index) of the first triangle data point.
+     * @param {[[number,number],[number,number]]} heightFace - The data sample that composes the face4 as a two-dimensional number array.
+     * @param {number} heightValue - The height value of the intersection plane to check for.
+     * @returns {Line|null}
+     */
+    private findHeighteFace3IntersectionLine;
+    /**
+     * This procedure will look at the face4 at the ((x,y),(nextX,nextY)) position – which are four values –
+     * and determines the local contour lines for these cases.
+     *
+     * This is used to detect and calculate edge cases on the borders of the underliying height data:
+     *  * left and right border (x=0, x=data.xSegmentCount)
+     *  * top and bottom border (x=y, x=data.ySegmentCount)
+     *
+     * Resulting path segments will be stored in the global `rawLinearPathSegments` array for further processing.
+     *
+     * @param {number} x
+     * @param {number} y
+     * @param {number} nextX
+     * @param {number} nextY
+     * @param {number} criticalHeightValue
+     * @param {number} closeGapType - CLOSE_GAP_TYPE_ABOVE or CLOSE_GAP_TYPE_BELOW.
+     * @return {void}
+     */
+    detectAboveBelowLerpSegment(x: number, y: number, nextX: number, nextY: number, criticalHeightValue: number, closeGapType: number): void;
+    /**
+     * Checks if both value are on the same side of the critical value (above or below). The `closeGapType`
+     * indictes if `CLOSE_GAP_TYPE_BELOW` or `CLOSE_GAP_TYPE_ABOVE` should be used as a rule.
+     *
+     * @param {number} valueA
+     * @param {number} valueB
+     * @param {number} criticalValue
+     * @param {number} closeGapType
+     * @returns {boolean}
+     */
+    private areBothValuesOnRequiredPlaneSide;
+    /**
+     * Test if a given numeric value (`curValue`) is between the given values `valA` and `valB`.
+     * Value A and B don't need to be in ascending order, so `valA <= curValue <= valB` and `valB <= curvalue <= valA`
+     * will do the job.
+     *
+     * @param {number} valA - The first of the two bounds.
+     * @param {number} valB - The second of the two bounds.
+     * @param {number} curValue - The value to check if it is between (or equal) to the given bounds.
+     * @returns {boolean}
+     */
+    private isBetween;
+    /**
+     * Get a 'lerp' value - which is some sort of percentage/ratio for the `curValue` inside the
+     * range of the given interval `[valA ... valB]`.
+     *
+     * Examples:
+     *  * getLerpRatio(0,100,50) === 0.5
+     *  * getLerpRatio(50,100,75) === 0.5
+     *  * getLerpRatio(0,100,0) === 0.0
+     *  * getLerpRatio(0,100,100) === 1.0
+     *  * getLerpRatio(0,100,-50) === -0.5
+     *
+     * @param {number} valA
+     * @param {number} valB
+     * @param {number} curValue
+     * @returns
+     */
+    private getLerpRatio;
+    /**
+     * Helper function to lerp a numeric value.
+     *
+     * @param {number} min - The min (start) value. Doesn't necesarily need to be the smaller one.
+     * @param {number} max - The max (end) value. Doesn't necesarily need to be the larger one.
+     * @param {number} ratio - The lerp ratio; usually a value between 0.0 and 1.0, but other values a valid for linear interpolation, too.
+     * @returns {number}
+     */
+    private lerp;
+}