@bitbybit-dev/base 0.20.2 → 0.20.3

package/lib/api/services/point.js

@@ -4,10 +4,11 @@
  * When creating 2D points, z coordinate is simply set to 0 - [x, y, 0].
  */
 export class Point {
-    constructor(geometryHelper, transforms, vector) {
+    constructor(geometryHelper, transforms, vector, lists) {
         this.geometryHelper = geometryHelper;
         this.transforms = transforms;
         this.vector = vector;
+        this.lists = lists;
     }
     /**
      * Transforms the single point
@@ -103,6 +104,18 @@ export class Point {
         const scaleTransforms = this.transforms.scaleCenterXYZ({ center: inputs.center, scaleXyz: inputs.scaleXyz });
         return this.geometryHelper.transformControlPoints(scaleTransforms, inputs.points);
     }
+    /**
+     * Stretch multiple points by providing center point, direction and uniform scale factor
+     * @param inputs Contains points, center point, direction and scale factor
+     * @returns Stretched points
+     * @group transforms
+     * @shortname stretch points dir from center
+     * @drawable true
+     */
+    stretchPointsDirFromCenter(inputs) {
+        const stretchTransforms = this.transforms.stretchDirFromCenter({ center: inputs.center, scale: inputs.scale, direction: inputs.direction });
+        return this.geometryHelper.transformControlPoints(stretchTransforms, inputs.points);
+    }
     /**
      * Rotate multiple points by providing center point, axis and degrees of rotation
      * @param inputs Contains points, axis, center point and angle of rotation
@@ -359,6 +372,479 @@ export class Point {
         }
         return points;
     }
+    /**
+     * Creates a pointy-top or flat-top hexagon grid, scaling hexagons to fit specified dimensions exactly.
+     * Returns both center points and the vertices of each (potentially scaled) hexagon.
+     * Hexagons are ordered column-first, then row-first.
+     * @param inputs Information about the desired grid dimensions and hexagon counts.
+     * @returns An object containing the array of center points and an array of hexagon vertex arrays.
+     * @group create
+     * @shortname scaled hex grid to fit
+     * @drawable false
+     */
+    hexGridScaledToFit(inputs) {
+        var _a, _b, _c, _d;
+        let width = inputs.width;
+        let height = inputs.height;
+        let nrHexagonsInHeight = inputs.nrHexagonsInHeight;
+        let nrHexagonsInWidth = inputs.nrHexagonsInWidth;
+        let extendTop = (_a = inputs.extendTop) !== null && _a !== void 0 ? _a : false;
+        let extendBottom = (_b = inputs.extendBottom) !== null && _b !== void 0 ? _b : false;
+        let extendLeft = (_c = inputs.extendLeft) !== null && _c !== void 0 ? _c : false;
+        let extendRight = (_d = inputs.extendRight) !== null && _d !== void 0 ? _d : false;
+        const { flatTop = false, centerGrid = false, pointsOnGround = false } = inputs;
+        // we flip the width and height if the hexagons are flat-topped and will then rotate resuls afterwards as default
+        // computes pointy-top hexagons
+        if (flatTop) {
+            const oldWidth = width;
+            width = inputs.height;
+            height = oldWidth;
+            const oldNrHexagonsInWidth = nrHexagonsInWidth;
+            nrHexagonsInWidth = nrHexagonsInHeight;
+            nrHexagonsInHeight = oldNrHexagonsInWidth;
+            const extendTopOld = extendTop;
+            const extendBottomOld = extendBottom;
+            const extendLeftOld = extendLeft;
+            const extendRightOld = extendRight;
+            extendTop = extendLeftOld;
+            extendBottom = extendRightOld;
+            extendLeft = extendBottomOld;
+            extendRight = extendTopOld;
+        }
+        // --- Input Validation ---
+        if (width <= 0 || height <= 0 || nrHexagonsInWidth < 1 || nrHexagonsInHeight < 1) {
+            console.warn("Hex grid dimensions and counts must be positive.");
+            return { centers: [], hexagons: [], shortestDistEdge: undefined, longestDistEdge: undefined, maxFilletRadius: undefined };
+        }
+        // --- Generate Unscaled Regular Grid Centers (Radius = 1) ---
+        // Use the *existing* hexGrid function, ensuring it doesn't center or project yet.
+        const BASE_RADIUS = 1.0;
+        const unscaledCenters = this.hexGrid({
+            radiusHexagon: BASE_RADIUS,
+            nrHexagonsX: nrHexagonsInWidth,
+            nrHexagonsY: nrHexagonsInHeight,
+            orientOnCenter: false,
+            pointsOnGround: false // Keep on XY plane for now
+        });
+        if (unscaledCenters.length === 0) {
+            return { centers: [], hexagons: [], shortestDistEdge: undefined, longestDistEdge: undefined, maxFilletRadius: undefined }; // Return empty if base grid failed
+        }
+        // --- Generate Unscaled Regular Hexagon Vertices (Radius = 1) ---
+        const unscaledHexagons = unscaledCenters.map(center => this.getRegularHexagonVertices(center, BASE_RADIUS));
+        // --- Determine Dimensions of the Unscaled Grid Bounding Box ---
+        let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
+        for (const hex of unscaledHexagons) {
+            for (const vertex of hex) {
+                if (vertex[0] < minX)
+                    minX = vertex[0];
+                if (vertex[0] > maxX)
+                    maxX = vertex[0];
+                if (vertex[1] < minY)
+                    minY = vertex[1];
+                if (vertex[1] > maxY)
+                    maxY = vertex[1];
+            }
+        }
+        const unscaledWidth = maxX - minX;
+        const unscaledHeight = maxY - minY;
+        // --- Step 4: Calculate Scaling Factors ---
+        // Handle potential zero dimensions if only 1 hex (W/H would be based on hex size)
+        const scaleX = (unscaledWidth > 1e-9) ? width / unscaledWidth : 1;
+        const scaleY = (unscaledHeight > 1e-9) ? height / unscaledHeight : 1;
+        // If unscaled W/H is 0 (e.g., 1x1 grid), scale=1 means the final hex will have
+        // width/height derived from its regular R=1 shape, not fitting totalW/H.
+        // This might need adjustment if a single hex *must* fill the total W/H.
+        // For now, assume nrU/nrV > 1 or accept R=1 size for single hex.
+        // --- Scale Centers and Vertices ---
+        // Scale relative to the min corner of the unscaled grid (minX, minY)
+        let scaledCenters = unscaledCenters.map(p => [
+            (p[0] - minX) * scaleX,
+            (p[1] - minY) * scaleY,
+            0 // Keep Z=0 for now
+        ]);
+        let scaledHexagons = unscaledHexagons.map(hex => hex.map(v => [
+            (v[0] - minX) * scaleX,
+            (v[1] - minY) * scaleY,
+            0 // Keep Z=0 for now
+        ]));
+        let shortestDistEdge = Infinity;
+        let longestDistEdge = -Infinity;
+        let maxFilletRadius = 0;
+        // --- Calculate Shortes/Longest & Extensions ---
+        if (scaledHexagons.length !== 0) {
+            const firstHex = scaledHexagons[0];
+            maxFilletRadius = this.safestPointsMaxFilletHalfLine({
+                points: firstHex,
+                checkLastWithFirst: true,
+                tolerance: 1e-7
+            });
+            // Calculate the shortest and longest edge distances
+            firstHex.forEach((pt, index) => {
+                const nextPt = firstHex[(index + 1) % firstHex.length];
+                const dist = this.distance({ startPoint: pt, endPoint: nextPt });
+                if (dist < shortestDistEdge) {
+                    shortestDistEdge = dist;
+                }
+                if (dist > longestDistEdge) {
+                    longestDistEdge = dist;
+                }
+            });
+            if (extendTop || extendBottom || extendLeft || extendRight) {
+                const pt1Pointy = firstHex[0];
+                const pt2Pointy = firstHex[1];
+                const cellHeight = pt1Pointy[1] - pt2Pointy[1];
+                const cellWidth = pt2Pointy[0] - pt1Pointy[0];
+                if (extendTop && !extendBottom) {
+                    const transform = {
+                        center: [0, 0, 0],
+                        direction: [0, 1, 0],
+                        scale: height / (height - cellHeight),
+                    };
+                    scaledHexagons = scaledHexagons.map(hex => {
+                        transform.points = hex;
+                        return this.stretchPointsDirFromCenter(transform);
+                    });
+                    transform.points = scaledCenters;
+                    scaledCenters = this.stretchPointsDirFromCenter(transform);
+                }
+                if (extendBottom && !extendTop) {
+                    const transform = {
+                        center: [0, height, 0],
+                        direction: [0, -1, 0],
+                        scale: height / (height - cellHeight),
+                    };
+                    scaledHexagons = scaledHexagons.map(hex => {
+                        transform.points = hex;
+                        return this.stretchPointsDirFromCenter(transform);
+                    });
+                    transform.points = scaledCenters;
+                    scaledCenters = this.stretchPointsDirFromCenter(transform);
+                }
+                if (extendTop && extendBottom) {
+                    const transform = {
+                        center: [0, height / 2, 0],
+                        direction: [0, 1, 0],
+                        scale: height / (height - cellHeight * 2),
+                    };
+                    scaledHexagons = scaledHexagons.map(hex => {
+                        transform.points = hex;
+                        return this.stretchPointsDirFromCenter(transform);
+                    });
+                    transform.points = scaledCenters;
+                    scaledCenters = this.stretchPointsDirFromCenter(transform);
+                }
+                if (extendLeft && !extendRight) {
+                    const transform = {
+                        center: [width, 0, 0],
+                        direction: [1, 0, 0],
+                        scale: width / (width - cellWidth),
+                    };
+                    scaledHexagons = scaledHexagons.map(hex => {
+                        transform.points = hex;
+                        return this.stretchPointsDirFromCenter(transform);
+                    });
+                    transform.points = scaledCenters;
+                    scaledCenters = this.stretchPointsDirFromCenter(transform);
+                }
+                if (extendRight && !extendLeft) {
+                    const transform = {
+                        center: [0, 0, 0],
+                        direction: [1, 0, 0],
+                        scale: width / (width - cellWidth),
+                    };
+                    scaledHexagons = scaledHexagons.map(hex => {
+                        transform.points = hex;
+                        return this.stretchPointsDirFromCenter(transform);
+                    });
+                    transform.points = scaledCenters;
+                    scaledCenters = this.stretchPointsDirFromCenter(transform);
+                }
+                if (extendLeft && extendRight) {
+                    const transform = {
+                        center: [width / 2, 0, 0],
+                        direction: [1, 0, 0],
+                        scale: width / (width - cellWidth * 2),
+                    };
+                    scaledHexagons = scaledHexagons.map(hex => {
+                        transform.points = hex;
+                        return this.stretchPointsDirFromCenter(transform);
+                    });
+                    transform.points = scaledCenters;
+                    scaledCenters = this.stretchPointsDirFromCenter(transform);
+                }
+            }
+        }
+        if (flatTop) {
+            // width and height are swapped
+            scaledCenters = this.rotatePointsCenterAxis({
+                points: scaledCenters,
+                center: [width / 2, height / 2, 0],
+                axis: [0, 0, 1],
+                angle: 90
+            });
+            scaledHexagons = scaledHexagons.map(hex => {
+                return this.rotatePointsCenterAxis({
+                    points: hex,
+                    center: [width / 2, height / 2, 0],
+                    axis: [0, 0, 1],
+                    angle: 90
+                });
+            });
+            // translate to new center
+            const vecTranslation = this.vector.sub({
+                first: [height / 2, width / 2, 0],
+                second: [width / 2, height / 2, 0]
+            });
+            scaledCenters = this.translatePoints({
+                points: scaledCenters,
+                translation: vecTranslation
+            });
+            scaledHexagons = scaledHexagons.map(hex => {
+                return this.translatePoints({
+                    points: hex,
+                    translation: vecTranslation
+                });
+            });
+        }
+        // --- Apply Optional Centering ---
+        // Center the scaled grid (currently starting at [0,0]) around [0,0]
+        if (centerGrid) {
+            let shiftX = width / 2;
+            let shiftY = height / 2;
+            if (flatTop) {
+                shiftX = height / 2;
+                shiftY = width / 2;
+            }
+            for (let i = 0; i < scaledCenters.length; i++) {
+                scaledCenters[i][0] -= shiftX;
+                scaledCenters[i][1] -= shiftY;
+            }
+            for (let i = 0; i < scaledHexagons.length; i++) {
+                for (let j = 0; j < scaledHexagons[i].length; j++) {
+                    scaledHexagons[i][j][0] -= shiftX;
+                    scaledHexagons[i][j][1] -= shiftY;
+                }
+            }
+        }
+        // --- Apply Optional Ground Projection ---
+        if (pointsOnGround) {
+            for (let i = 0; i < scaledCenters.length; i++) {
+                scaledCenters[i] = [scaledCenters[i][0], 0, scaledCenters[i][1]];
+            }
+            for (let i = 0; i < scaledHexagons.length; i++) {
+                for (let j = 0; j < scaledHexagons[i].length; j++) {
+                    scaledHexagons[i][j] = [scaledHexagons[i][j][0], 0, scaledHexagons[i][j][1]];
+                }
+            }
+        }
+        // We need to adjust orders to be column first and then row first if we choose flat top
+        if (flatTop) {
+            const grouped = this.lists.groupNth({
+                list: scaledHexagons.reverse(),
+                nrElements: inputs.nrHexagonsInWidth,
+                keepRemainder: true,
+            });
+            const res = this.lists.flipLists({
+                list: grouped
+            });
+            res.forEach(s => s.reverse());
+            scaledHexagons = res.flat();
+            const groupedCenters = this.lists.groupNth({
+                list: scaledCenters.reverse(),
+                nrElements: inputs.nrHexagonsInWidth,
+                keepRemainder: true,
+            });
+            const resCenters = this.lists.flipLists({
+                list: groupedCenters
+            });
+            resCenters.forEach(s => s.reverse());
+            scaledCenters = resCenters.flat();
+        }
+        // --- Return Result ---
+        return {
+            centers: scaledCenters,
+            hexagons: scaledHexagons,
+            shortestDistEdge,
+            longestDistEdge,
+            maxFilletRadius
+        };
+    }
+    /**
+     * Calculates the maximum possible fillet radius at a corner formed by two line segments
+     * sharing an endpoint (C), such that the fillet arc is tangent to both segments
+     * and lies entirely within them.
+     * @param inputs three points and the tolerance
+     * @returns the maximum fillet radius
+     * @group fillet
+     * @shortname max fillet radius
+     * @drawable false
+     */
+    maxFilletRadius(inputs) {
+        const { start: p1, center: p2, end: c, tolerance = 1e-7 } = inputs;
+        const v1 = this.vector.sub({ first: p1, second: c });
+        const v2 = this.vector.sub({ first: p2, second: c });
+        const len1 = this.vector.length({ vector: v1 });
+        const len2 = this.vector.length({ vector: v2 });
+        if (len1 < tolerance || len2 < tolerance) {
+            return 0;
+        }
+        const normV1 = this.vector.normalized({ vector: v1 });
+        const normV2 = this.vector.normalized({ vector: v2 });
+        if (!normV1 || !normV2) {
+            return 0;
+        }
+        // Calculate the cosine of the angle between the vectors
+        // Clamp to [-1, 1] to avoid potential domain errors with acos due to floating point inaccuracies
+        const cosAlpha = Math.max(-1.0, Math.min(1.0, this.vector.dot({ first: normV1, second: normV2 })));
+        // Check for collinearity
+        // If vectors point in the same direction (angle ~ 0), no fillet
+        if (cosAlpha > 1.0 - tolerance) {
+            return 0;
+        }
+        // If vectors point in opposite directions (angle ~ 180 deg), no corner for a fillet
+        if (cosAlpha < -1.0 + tolerance) {
+            return 0;
+        }
+        // Calculate the angle alpha (0 < alpha < PI)
+        const alpha = Math.acos(cosAlpha);
+        // Calculate tan(alpha / 2)
+        // alpha/2 is between 0 and PI/2, so tan is positive and non-zero
+        const tanHalfAlpha = Math.tan(alpha / 2.0);
+        // If tanHalfAlpha is extremely small (alpha near 0, shouldn't happen due to collinearity check), return 0
+        if (tanHalfAlpha < tolerance) {
+            return 0;
+        }
+        // The distance 'd' from corner C to the tangent point must be less than or equal to the segment lengths.
+        // d = r / tan(alpha/2) <= min(len1, len2)
+        // r <= min(len1, len2) * tan(alpha/2)
+        const maxRadius = Math.min(len1, len2) * tanHalfAlpha;
+        return maxRadius;
+    }
+    /**
+     * Calculates the maximum possible fillet radius at a corner C, such that the fillet arc
+     * is tangent to both segments (P1-C, P2-C) and the tangent points lie within
+     * the first half of each segment (measured from C).
+     * @param inputs three points and the tolerance
+     * @returns the maximum fillet radius
+     * @group fillet
+     * @shortname max fillet radius half line
+     * @drawable false
+     */
+    maxFilletRadiusHalfLine(inputs) {
+        const { start: p1, center: p2, end: c, tolerance = 1e-7 } = inputs;
+        const v1 = this.vector.sub({ first: p1, second: c });
+        const v2 = this.vector.sub({ first: p2, second: c });
+        const len1 = this.vector.length({ vector: v1 });
+        const len2 = this.vector.length({ vector: v2 });
+        if (len1 < tolerance || len2 < tolerance) {
+            return 0;
+        }
+        const normV1 = this.vector.normalized({ vector: v1 });
+        const normV2 = this.vector.normalized({ vector: v2 });
+        if (!normV1 || !normV2) {
+            return 0;
+        }
+        const cosAlpha = Math.max(-1.0, Math.min(1.0, this.vector.dot({ first: normV1, second: normV2 })));
+        if (cosAlpha > 1.0 - tolerance || cosAlpha < -1.0 + tolerance) {
+            return 0; // Collinear
+        }
+        const alpha = Math.acos(cosAlpha);
+        const tanHalfAlpha = Math.tan(alpha / 2.0);
+        if (tanHalfAlpha < tolerance) {
+            return 0;
+        }
+        // The distance 'd' from corner C to the tangent point must be less than or equal
+        // to HALF the length of each segment.
+        // d = r / tan(alpha/2) <= min(len1 / 2, len2 / 2)
+        // r <= min(len1 / 2, len2 / 2) * tan(alpha/2)
+        const maxRadius = Math.min(len1 / 2.0, len2 / 2.0) * tanHalfAlpha;
+        return maxRadius;
+    }
+    /**
+     * Calculates the maximum possible fillet radius at each corner of a polyline formed by
+     * formed by a series of points. The fillet radius is calculated for each internal
+     * corner and optionally for the closing corners if the polyline is closed.
+     * @param inputs Points, checkLastWithFirst flag, and tolerance
+     * @returns Array of maximum fillet radii for each corner
+     * @group fillet
+     * @shortname max fillets half line
+     * @drawable false
+     */
+    maxFilletsHalfLine(inputs) {
+        const { points, checkLastWithFirst = false, tolerance = 1e-7 } = inputs;
+        const n = points.length;
+        const results = [];
+        // Need at least 3 points to form a corner
+        if (n < 3) {
+            return results;
+        }
+        // 1. Calculate fillets for internal corners (P[1] to P[n-2])
+        for (let i = 1; i < n - 1; i++) {
+            const p_prev = points[i - 1];
+            const p_corner = points[i];
+            const p_next = points[i + 1];
+            // Map geometric points to the DTO structure used by calculateMaxFilletRadiusHalfLine
+            // DTO: { start: P_prev, center: P_next, end: P_corner, tolerance }
+            const cornerInput = {
+                start: p_prev,
+                center: p_next,
+                end: p_corner,
+                tolerance: tolerance
+            };
+            results.push(this.maxFilletRadiusHalfLine(cornerInput));
+        }
+        // 2. Calculate fillets for closing corners if it's a closed polyline
+        if (checkLastWithFirst && n >= 3) {
+            // Corner at P[0] (formed by P[n-1]-P[0] and P[1]-P[0])
+            const p_prev_start = points[n - 1]; // Previous point is the last point
+            const p_corner_start = points[0];
+            const p_next_start = points[1];
+            const startCornerInput = {
+                start: p_prev_start,
+                center: p_next_start,
+                end: p_corner_start,
+                tolerance: tolerance
+            };
+            results.push(this.maxFilletRadiusHalfLine(startCornerInput));
+            // Corner at P[n-1] (formed by P[n-2]-P[n-1] and P[0]-P[n-1])
+            const p_prev_end = points[n - 2];
+            const p_corner_end = points[n - 1];
+            const p_next_end = points[0]; // Next point wraps around to the first point
+            const endCornerInput = {
+                start: p_prev_end,
+                center: p_next_end,
+                end: p_corner_end,
+                tolerance: tolerance
+            };
+            results.push(this.maxFilletRadiusHalfLine(endCornerInput));
+        }
+        return results;
+    }
+    /**
+     * Calculates the single safest maximum fillet radius that can be applied
+     * uniformly to all corners of collection of points, based on the 'half-line' constraint.
+     * This is determined by finding the minimum of the maximum possible fillet
+     * radii calculated for each individual corner.
+     * @param inputs Defines the points, whether it's closed, and an optional tolerance.
+     * @returns The smallest value from the results of pointsMaxFilletsHalfLine.
+     *          Returns 0 if the polyline has fewer than 3 points or if any
+     *          calculated maximum radius is 0.
+     * @group fillet
+     * @shortname safest fillet radii points
+     * @drawable false
+     */
+    safestPointsMaxFilletHalfLine(inputs) {
+        const allMaxRadii = this.maxFilletsHalfLine(inputs);
+        if (allMaxRadii.length === 0) {
+            // No corners, or fewer than 3 points. No fillet possible.
+            return 0;
+        }
+        // Find the minimum radius among all calculated maximums.
+        // If any corner calculation resulted in 0, the safest radius is 0.
+        const safestRadius = Math.min(...allMaxRadii);
+        // Ensure we don't return a negative radius if Math.min had weird input (shouldn't happen here)
+        return Math.max(0, safestRadius);
+    }
     /**
      * Removes consecutive duplicates from the point array with tolerance
      * @param inputs points, tolerance and check first and last
@@ -426,4 +912,57 @@ export class Point {
         }
         return { index: closestPointIndex + 1, distance, point };
     }
+    /**
+     * Checks if two points are almost equal
+     * @param inputs Two points and the tolerance
+     * @returns true if the points are almost equal
+     * @group measure
+     * @shortname two points almost equal
+     * @drawable false
+     */
+    twoPointsAlmostEqual(inputs) {
+        const p1 = inputs.point1;
+        const p2 = inputs.point2;
+        const dist = this.distance({ startPoint: p1, endPoint: p2 });
+        return dist < inputs.tolerance;
+    }
+    /**
+     * Sorts points lexicographically (X, then Y, then Z)
+     * @param inputs points
+     * @returns sorted points
+     * @group sort
+     * @shortname sort points
+     * @drawable true
+     */
+    sortPoints(inputs) {
+        return [...inputs.points].sort((a, b) => {
+            if (a[0] !== b[0])
+                return a[0] - b[0];
+            if (a[1] !== b[1])
+                return a[1] - b[1];
+            return a[2] - b[2];
+        });
+    }
+    /**
+     * Calculates the 6 vertices of a regular flat-top hexagon.
+     * @param center The center point [x, y, z].
+     * @param radius The radius (distance from center to vertex).
+     * @returns An array of 6 Point3 vertices in counter-clockwise order.
+     */
+    getRegularHexagonVertices(center, radius) {
+        const vertices = [];
+        const cx = center[0];
+        const cy = center[1];
+        const cz = center[2];
+        const angleStep = Math.PI / 3;
+        for (let i = 0; i < 6; i++) {
+            const angle = angleStep * i;
+            vertices.push([
+                cx + radius * Math.sin(angle),
+                cy + radius * Math.cos(angle),
+                cz // Maintain original Z
+            ]);
+        }
+        return vertices;
+    }
 }