@bitbybit-dev/base 0.20.2 → 0.20.3

package/lib/api/services/transforms.js

@@ -109,6 +109,23 @@ export class Transforms {
     scaleXYZ(inputs) {
         return [this.scaling(inputs.scaleXyz[0], inputs.scaleXyz[1], inputs.scaleXyz[2])];
     }
+    /**
+     * Creates a stretch transformation along a specific direction, relative to a center point.
+     * This scales points along the given direction vector while leaving points in the
+     * plane perpendicular to the direction (passing through the center) unchanged.
+     * @param inputs Defines the center, direction, and scale factor for the stretch.
+     * @returns Array of transformations: [Translate To Origin, Stretch, Translate Back].
+     * @group scale
+     * @shortname stretch dir center
+     * @drawable false
+     */
+    stretchDirFromCenter(inputs) {
+        return [
+            this.translation(-inputs.center[0], -inputs.center[1], -inputs.center[2]),
+            this.stretchDirection(inputs.direction, inputs.scale),
+            this.translation(inputs.center[0], inputs.center[1], inputs.center[2]),
+        ];
+    }
     /**
      * Creates uniform scale transformation
      * @param inputs Scale Dto
@@ -157,15 +174,22 @@ export class Transforms {
     translationsXYZ(inputs) {
         return inputs.translations.map(translation => [this.translation(translation[0], translation[1], translation[2])]);
     }
+    /**
+     * Creates the identity transformation
+     * @returns transformation
+     * @group identity
+     * @shortname identity
+     * @drawable false
+     */
+    identity() {
+        return [1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0];
+    }
     translation(x, y, z) {
         return [1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, x, y, z, 1.0];
     }
     scaling(x, y, z) {
         return [x, 0.0, 0.0, 0.0, 0.0, y, 0.0, 0.0, 0.0, 0.0, z, 0.0, 0.0, 0.0, 0.0, 1.0];
     }
-    identity() {
-        return [1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0];
-    }
     rotationAxis(axis, angle) {
         const s = Math.sin(-angle);
         const c = Math.cos(-angle);
@@ -253,4 +277,43 @@ export class Transforms {
         m[15] = 1.0;
         return m;
     }
+    /**
+     * Creates a 4x4 matrix that scales along a given direction vector.
+     * @param direction The direction vector (will be normalized).
+     * @param scale The scale factor along the direction.
+     * @returns A 4x4 column-major transformation matrix.
+     */
+    stretchDirection(direction, scale) {
+        const d = this.vector.normalized({ vector: direction });
+        const [dx, dy, dz] = d;
+        // Handle potential zero vector after normalization (if input was zero)
+        if (isNaN(dx) || (dx === 0 && dy === 0 && dz === 0)) {
+            console.warn("Stretch direction vector is zero or invalid. Returning identity matrix.");
+            return this.identity();
+        }
+        const s = scale;
+        const sMinus1 = s - 1.0;
+        // Calculate elements of the 3x3 directional scaling part
+        const m11 = 1.0 + sMinus1 * dx * dx;
+        const m12 = sMinus1 * dx * dy;
+        const m13 = sMinus1 * dx * dz;
+        // m14 = 0
+        const m21 = sMinus1 * dy * dx;
+        const m22 = 1.0 + sMinus1 * dy * dy;
+        const m23 = sMinus1 * dy * dz;
+        // m24 = 0
+        const m31 = sMinus1 * dz * dx;
+        const m32 = sMinus1 * dz * dy;
+        const m33 = 1.0 + sMinus1 * dz * dz;
+        // m34 = 0
+        // m41, m42, m43 = 0, m44 = 1
+        // Assemble the 4x4 matrix in COLUMN-MAJOR order
+        const m = [
+            m11, m21, m31, 0.0,
+            m12, m22, m32, 0.0,
+            m13, m23, m33, 0.0,
+            0.0, 0.0, 0.0, 1.0 // Column 4
+        ];
+        return m;
+    }
 }

package/lib/api/services/vector.d.ts

@@ -326,4 +326,22 @@ export declare class Vector {
      * @drawable false
      */
     sum(inputs: Inputs.Vector.VectorDto): number;
+    /**
+     * Computes the squared length of the vector
+     * @param inputs Vector to compute the length
+     * @returns Number that is squared length of the vector
+     * @group base
+     * @shortname length squared
+     * @drawable false
+     */
+    lengthSq(inputs: Inputs.Vector.Vector3Dto): number;
+    /**
+     * Computes the length of the vector
+     * @param inputs Vector to compute the length
+     * @returns Number that is length of the vector
+     * @group base
+     * @shortname length
+     * @drawable false
+     */
+    length(inputs: Inputs.Vector.Vector3Dto): number;
 }

package/lib/api/services/vector.js

@@ -328,6 +328,10 @@ export class Vector {
      * @drawable false
      */
     normalized(inputs) {
+        const len = this.length({ vector: inputs.vector });
+        if (len <= 1e-8) {
+            return undefined;
+        }
         return this.div({ scalar: this.norm(inputs), vector: inputs.vector });
     }
     /**
@@ -476,4 +480,27 @@ export class Vector {
     sum(inputs) {
         return inputs.vector.reduce((a, b) => a + b, 0);
     }
+    /**
+     * Computes the squared length of the vector
+     * @param inputs Vector to compute the length
+     * @returns Number that is squared length of the vector
+     * @group base
+     * @shortname length squared
+     * @drawable false
+     */
+    lengthSq(inputs) {
+        const v = inputs.vector;
+        return v[0] * v[0] + v[1] * v[1] + v[2] * v[2];
+    }
+    /**
+     * Computes the length of the vector
+     * @param inputs Vector to compute the length
+     * @returns Number that is length of the vector
+     * @group base
+     * @shortname length
+     * @drawable false
+     */
+    length(inputs) {
+        return Math.sqrt(this.lengthSq(inputs));
+    }
 }

package/lib/api/unit-test-helper.d.ts

@@ -0,0 +1,20 @@
+import * as Inputs from "./inputs";
+import { Vector } from "./services";
+export declare const TOLERANCE = 1e-7;
+export declare class UnitTestHelper {
+    vector: Vector;
+    constructor();
+    expectPointCloseTo(received: Inputs.Base.Point3 | Inputs.Base.Vector3 | undefined, expected: Inputs.Base.Point3 | Inputs.Base.Vector3): void;
+    expectPointsCloseTo(received: Inputs.Base.Point3[] | Inputs.Base.Vector3[], expected: Inputs.Base.Point3[] | Inputs.Base.Vector3[]): void;
+    expectLineCloseTo(received: Inputs.Base.Line3 | undefined, expected: Inputs.Base.Line3): void;
+    expectLinesCloseTo(received: Inputs.Base.Line3[], expected: Inputs.Base.Line3[]): void;
+    expectSegmentCloseTo(received: Inputs.Base.Segment3 | undefined, expected: Inputs.Base.Segment3, precision?: number): void;
+    expectPlaneCloseTo(received: Inputs.Base.TrianglePlane3 | undefined, expected: Inputs.Base.TrianglePlane3, precision?: number): void;
+    expectMatrixCloseTo(received: Inputs.Base.TransformMatrix | undefined, expected: Inputs.Base.TransformMatrix): void;
+    expectMatrixesCloseTo(received: Inputs.Base.TransformMatrixes | undefined, expected: Inputs.Base.TransformMatrixes): void;
+    /** Helper to compare two arrays of points for near-equality, ignoring order */
+    expectPointArraysCloseTo(actual: Inputs.Base.Point3[] | undefined, expected: Inputs.Base.Point3[], tolerance?: number): void;
+    sortPoints(points: Inputs.Base.Point3[]): Inputs.Base.Point3[];
+    sortPolylinesForComparison(polylines: Inputs.Base.Polyline3[]): Inputs.Base.Polyline3[];
+    expectFloatArraysClose(actual: number[], expected: number[], precision: number): void;
+}

package/lib/api/unit-test-helper.js

@@ -0,0 +1,130 @@
+import { GeometryHelper, MathBitByBit, Vector } from "./services";
+export const TOLERANCE = 1e-7;
+export class UnitTestHelper {
+    constructor() {
+        const math = new MathBitByBit();
+        const geometryHelper = new GeometryHelper();
+        this.vector = new Vector(math, geometryHelper);
+    }
+    expectPointCloseTo(received, expected) {
+        expect(received).toBeDefined();
+        if (!received)
+            return;
+        expect(received.length).toEqual(expected.length);
+        expect(received[0]).toBeCloseTo(expected[0], TOLERANCE);
+        expect(received[1]).toBeCloseTo(expected[1], TOLERANCE);
+        if (expected.length > 2 && received.length > 2) {
+            expect(received[2]).toBeCloseTo(expected[2], TOLERANCE);
+        }
+    }
+    expectPointsCloseTo(received, expected) {
+        expect(received.length).toEqual(expected.length);
+        received.forEach((p, i) => this.expectPointCloseTo(p, expected[i]));
+    }
+    expectLineCloseTo(received, expected) {
+        expect(received).toBeDefined();
+        if (!received)
+            return;
+        this.expectPointCloseTo(received.start, expected.start);
+        this.expectPointCloseTo(received.end, expected.end);
+    }
+    expectLinesCloseTo(received, expected) {
+        expect(received.length).toEqual(expected.length);
+        received.forEach((l, i) => this.expectLineCloseTo(l, expected[i]));
+    }
+    expectSegmentCloseTo(received, expected, precision = TOLERANCE) {
+        expect(received).toBeDefined();
+        if (!received)
+            return;
+        expect(received).toHaveLength(2);
+        const order1Matches = Math.abs(this.vector.dist({ first: received[0], second: expected[0] })) < precision &&
+            Math.abs(this.vector.dist({ first: received[1], second: expected[1] })) < precision;
+        const order2Matches = Math.abs(this.vector.dist({ first: received[0], second: expected[1] })) < precision &&
+            Math.abs(this.vector.dist({ first: received[1], second: expected[0] })) < precision;
+        expect(order1Matches || order2Matches).toBe(true);
+    }
+    expectPlaneCloseTo(received, expected, precision = TOLERANCE) {
+        expect(received).toBeDefined();
+        if (!received)
+            return;
+        const normalDir1 = this.vector.sub({ first: received.normal, second: expected.normal });
+        const normalDir2 = this.vector.add({ first: received.normal, second: expected.normal });
+        const dir1Match = this.vector.lengthSq({ vector: normalDir1 }) < precision * precision;
+        const dir2Match = this.vector.lengthSq({ vector: normalDir2 }) < precision * precision;
+        expect(dir1Match || dir2Match).toBe(true);
+        expect(received.d).toBeCloseTo(dir1Match ? expected.d : -expected.d, precision);
+    }
+    expectMatrixCloseTo(received, expected) {
+        expect(received).toBeDefined();
+        if (!received)
+            return;
+        expect(received).toHaveLength(16);
+        expect(expected).toHaveLength(16);
+        for (let i = 0; i < 16; i++) {
+            expect(received[i]).toBeCloseTo(expected[i], TOLERANCE);
+        }
+    }
+    expectMatrixesCloseTo(received, expected) {
+        expect(received).toBeDefined();
+        if (!received)
+            return;
+        expect(received.length).toEqual(expected.length);
+        received.forEach((matrix, i) => this.expectMatrixCloseTo(matrix, expected[i]));
+    }
+    /** Helper to compare two arrays of points for near-equality, ignoring order */
+    expectPointArraysCloseTo(actual, expected, tolerance = 1e-6) {
+        // Use expectPointsClose helper for individual point comparison if needed
+        const expectPointsClose = (act, exp, tol = 1e-6) => {
+            const precision = Math.max(0, Math.ceil(-Math.log10(tol)) - 1);
+            if (exp === undefined) {
+                expect(act).toBeUndefined();
+            }
+            else {
+                expect(act).toBeDefined();
+                if (act) {
+                    expect(act[0]).toBeCloseTo(exp[0], precision);
+                    expect(act[1]).toBeCloseTo(exp[1], precision);
+                    expect(act[2]).toBeCloseTo(exp[2], precision);
+                }
+            }
+        };
+        expect(actual).toBeDefined();
+        // Proceed only if actual is defined
+        if (actual) {
+            expect(actual.length).toEqual(expected.length);
+            // Sort both arrays to compare independent of order
+            const sortedActual = this.sortPoints(actual);
+            const sortedExpected = this.sortPoints(expected);
+            for (let i = 0; i < sortedExpected.length; i++) {
+                expectPointsClose(sortedActual[i], sortedExpected[i], tolerance);
+            }
+        }
+    }
+    sortPoints(points) {
+        return [...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];
+        });
+    }
+    sortPolylinesForComparison(polylines) {
+        return polylines.sort((a, b) => {
+            const pA = a.points[0];
+            const pB = b.points[0];
+            if (pA[0] !== pB[0])
+                return pA[0] - pB[0];
+            if (pA[1] !== pB[1])
+                return pA[1] - pB[1];
+            return pA[2] - pB[2];
+        });
+    }
+    expectFloatArraysClose(actual, expected, precision) {
+        expect(actual.length).toBe(expected.length);
+        actual.forEach((val, index) => {
+            expect(val).toBeCloseTo(expected[index], precision);
+        });
+    }
+    ;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@bitbybit-dev/base",
-    "version": "0.20.2",
+    "version": "0.20.3",
     "description": "Bit By Bit Developers Base CAD Library to Program Geometry",
     "main": "index.js",
     "repository": {
@@ -86,7 +86,7 @@
             "node_modules/(?!@bitbybit-dev)/"
         ],
         "collectCoverageFrom": [
-            "lib/api/**/*"
+            "lib/api/services/**/*"
         ]
     }
 }