@metamesh/modeling 0.13.0 → 0.15.0

package/dist/geometry/math/vector-value.js

@@ -0,0 +1,168 @@
+import { GeometryError } from "../errors.js";
+import { immutableMathClass } from "./immutable-value.js";
+import { add2, cross2, distance2, dot2, length2, lerp2, normalize2, scale2, subtract2, } from "./vector2.js";
+import { add3, cross3, distance3, dot3, length3, lerp3, normalize3, scale3, subtract3, } from "./vector3.js";
+const finite = (value, operation) => {
+    if (!Number.isFinite(value)) {
+        throw new GeometryError("NON_FINITE_VALUE", "Vector coordinates and results must be finite.", {
+            operation,
+        });
+    }
+    return value;
+};
+const validateCoordinates = (values, operation) => {
+    for (const coordinate of values)
+        finite(coordinate, operation);
+};
+const operand2 = (input, operation) => {
+    const values = vector2Data(input);
+    validateCoordinates(values, operation);
+    return values;
+};
+const operand3 = (input, operation) => {
+    const values = vector3Data(input);
+    validateCoordinates(values, operation);
+    return values;
+};
+function invalidVector(dimensions) {
+    throw new GeometryError("INVALID_ARGUMENT", `Expected a ${dimensions}D vector or coordinate tuple.`, {
+        operation: `vector${dimensions}`,
+    });
+}
+const tupleData = (input, dimensions) => {
+    if (typeof input !== "object" || input === null)
+        return invalidVector(dimensions);
+    let values = input;
+    if (!Array.isArray(input)) {
+        const method = Reflect.get(input, "toArray");
+        if (typeof method !== "function")
+            return invalidVector(dimensions);
+        values = Reflect.apply(method, input, []);
+    }
+    if (!Array.isArray(values) || values.length !== dimensions)
+        return invalidVector(dimensions);
+    return values;
+};
+/** Internal tuple view; validates dimension and shape without allocating or checking finiteness. */
+export const vector2Data = (input) => tupleData(input, 2);
+/** Internal tuple view; validates dimension and shape without allocating or checking finiteness. */
+export const vector3Data = (input) => tupleData(input, 3);
+const PlanarVector = /* @__PURE__ */ immutableMathClass(class PlanarVector {
+    values;
+    constructor(values, operation = "vector2") {
+        this.values = values;
+        validateCoordinates(values, operation);
+        Object.freeze(values);
+        Object.freeze(this);
+    }
+    get x() {
+        return this.values[0];
+    }
+    get y() {
+        return this.values[1];
+    }
+    add(other) {
+        return new PlanarVector(add2(this.values, operand2(other, "vector2.add")), "vector2.add");
+    }
+    subtract(other) {
+        return new PlanarVector(subtract2(this.values, operand2(other, "vector2.subtract")), "vector2.subtract");
+    }
+    scale(factor) {
+        return new PlanarVector(scale2(this.values, finite(factor, "vector2.scale")), "vector2.scale");
+    }
+    normalize(epsilon) {
+        return new PlanarVector(normalize2(this.values, epsilon), "vector2.normalize");
+    }
+    lerp(other, t) {
+        return new PlanarVector(lerp2(this.values, operand2(other, "vector2.lerp"), finite(t, "vector2.lerp")), "vector2.lerp");
+    }
+    dot(other) {
+        return finite(dot2(this.values, operand2(other, "vector2.dot")), "vector2.dot");
+    }
+    cross(other) {
+        return finite(cross2(this.values, operand2(other, "vector2.cross")), "vector2.cross");
+    }
+    length() {
+        return finite(length2(this.values), "vector2.length");
+    }
+    distance(other) {
+        return finite(distance2(this.values, operand2(other, "vector2.distance")), "vector2.distance");
+    }
+    toArray() {
+        return this.values;
+    }
+});
+const SpatialVector = /* @__PURE__ */ immutableMathClass(class SpatialVector {
+    values;
+    constructor(values, operation = "vector3") {
+        this.values = values;
+        validateCoordinates(values, operation);
+        Object.freeze(values);
+        Object.freeze(this);
+    }
+    get x() {
+        return this.values[0];
+    }
+    get y() {
+        return this.values[1];
+    }
+    get z() {
+        return this.values[2];
+    }
+    add(other) {
+        return new SpatialVector(add3(this.values, operand3(other, "vector3.add")), "vector3.add");
+    }
+    subtract(other) {
+        return new SpatialVector(subtract3(this.values, operand3(other, "vector3.subtract")), "vector3.subtract");
+    }
+    scale(factor) {
+        return new SpatialVector(scale3(this.values, finite(factor, "vector3.scale")), "vector3.scale");
+    }
+    normalize(epsilon) {
+        return new SpatialVector(normalize3(this.values, epsilon), "vector3.normalize");
+    }
+    lerp(other, t) {
+        return new SpatialVector(lerp3(this.values, operand3(other, "vector3.lerp"), finite(t, "vector3.lerp")), "vector3.lerp");
+    }
+    dot(other) {
+        return finite(dot3(this.values, operand3(other, "vector3.dot")), "vector3.dot");
+    }
+    cross(other) {
+        return new SpatialVector(cross3(this.values, operand3(other, "vector3.cross")), "vector3.cross");
+    }
+    length() {
+        return finite(length3(this.values), "vector3.length");
+    }
+    distance(other) {
+        return finite(distance3(this.values, operand3(other, "vector3.distance")), "vector3.distance");
+    }
+    toArray() {
+        return this.values;
+    }
+});
+/**
+ * Creates immutable XY arithmetic from a finite tuple or vector, snapshotting the coordinates.
+ * Values and results are finite. Invalid dimensions throw `INVALID_ARGUMENT`; nonfinite coordinates
+ * and overflow throw `NON_FINITE_VALUE` GeometryError.
+ * Use transform2().applyDirection(value) for rotations and nonuniform scaling.
+ */
+export function vector2(input) {
+    const values = operand2(input, "vector2");
+    return new PlanarVector([values[0], values[1]]);
+}
+/**
+ * Creates immutable XYZ arithmetic from a finite tuple or vector, snapshotting the coordinates.
+ * Values and results are finite. Invalid dimensions throw `INVALID_ARGUMENT`; nonfinite coordinates
+ * and overflow throw `NON_FINITE_VALUE` GeometryError.
+ * Use transform3().applyDirection(value) for rotations and nonuniform scaling.
+ *
+ * @example
+ * ```ts
+ * const direction = vector3([1, 2, 3]).add([4, 0, 0]).normalize().scale(10);
+ * const alignment = direction.dot([0, 0, 1]);
+ * ```
+ */
+export function vector3(input) {
+    const values = operand3(input, "vector3");
+    return new SpatialVector([values[0], values[1], values[2]]);
+}

package/dist/geometry/math/vector2.js

@@ -0,0 +1,80 @@
+import { GeometryError } from "../errors.js";
+/** Adds two finite XY vectors component-wise. */
+export const add2 = (a, b) => [a[0] + b[0], a[1] + b[1]];
+/** Subtracts `b` from `a` component-wise. */
+export const subtract2 = (a, b) => [
+    a[0] - b[0],
+    a[1] - b[1],
+];
+/** Multiplies a vector by a dimensionless scalar. */
+export const scale2 = (vector, scale) => [
+    vector[0] * scale,
+    vector[1] * scale,
+];
+/** Returns the scalar dot product. */
+export const dot2 = (a, b) => a[0] * b[0] + a[1] * b[1];
+/** Returns the signed scalar cross product; positive means `b` is counter-clockwise from `a`. */
+export const cross2 = (a, b) => a[0] * b[1] - a[1] * b[0];
+/** Returns Euclidean vector length in the vector's coordinate units. */
+export const length2 = (vector) => Math.hypot(vector[0], vector[1]);
+/** Returns Euclidean point distance without allocating an intermediate difference vector. */
+export const distance2 = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1]);
+/**
+ * Returns a unit vector; `epsilon` is a finite, non-negative length threshold (default `1e-12`).
+ * Rejects invalid thresholds, nonfinite lengths, and lengths at or below the threshold with
+ * `INVALID_TOLERANCE`, `NON_FINITE_VALUE`, and `DEGENERATE_GEOMETRY` respectively.
+ */
+export const normalize2 = (vector, epsilon = 1e-12) => {
+    const operation = "normalize2";
+    if (!Number.isFinite(epsilon) || epsilon < 0) {
+        throw new GeometryError("INVALID_TOLERANCE", "epsilon must be finite and non-negative.", {
+            operation,
+        });
+    }
+    const length = length2(vector);
+    if (!Number.isFinite(length)) {
+        throw new GeometryError("NON_FINITE_VALUE", "Cannot normalize a vector without finite length.", {
+            operation,
+        });
+    }
+    if (length <= epsilon) {
+        throw new GeometryError("DEGENERATE_GEOMETRY", "Cannot normalize a zero-length vector.", {
+            operation,
+        });
+    }
+    // Subnormal lengths lose relative precision; rescale only this rare case before division.
+    if (length < 2 ** -1022) {
+        const maximum = Math.max(Math.abs(vector[0]), Math.abs(vector[1]));
+        const x = vector[0] / maximum;
+        const y = vector[1] / maximum;
+        const scaledLength = Math.hypot(x, y);
+        return [x / scaledLength, y / scaledLength];
+    }
+    return [vector[0] / length, vector[1] / length];
+};
+/** Linearly interpolates two vectors; `t` is dimensionless and may extrapolate. */
+export const lerp2 = (a, b, t) => add2(a, scale2(subtract2(b, a), t));
+/**
+ * Rotates a finite vector counter-clockwise in XY by `degrees` about the origin.
+ * Throws `NON_FINITE_VALUE` for nonfinite coordinates, angles, or derived coordinates.
+ */
+export const rotate2 = (vector, degrees) => {
+    if (!Number.isFinite(vector[0]) || !Number.isFinite(vector[1]) || !Number.isFinite(degrees)) {
+        throw new GeometryError("NON_FINITE_VALUE", "Rotation coordinates and angle must be finite.", {
+            operation: "rotate2",
+        });
+    }
+    const radians = degrees * (Math.PI / 180);
+    const cosine = Math.cos(radians);
+    const sine = Math.sin(radians);
+    const rotated = [
+        vector[0] * cosine - vector[1] * sine,
+        vector[0] * sine + vector[1] * cosine,
+    ];
+    if (!Number.isFinite(rotated[0]) || !Number.isFinite(rotated[1])) {
+        throw new GeometryError("NON_FINITE_VALUE", "Rotated coordinates must remain finite.", {
+            operation: "rotate2",
+        });
+    }
+    return rotated;
+};

package/dist/geometry/math/vector3.js

@@ -1,3 +1,4 @@
+import { GeometryError } from "../errors.js";
 /**
  * Adds two finite XYZ vectors component-wise.
  * @example
@@ -5,7 +6,11 @@
  * add3([1, 2, 3], [4, 5, 6]); // [5, 7, 9]
  * ```
  */
-export const add3 = (a, b) => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+export const add3 = (a, b) => [
+    a[0] + b[0],
+    a[1] + b[1],
+    a[2] + b[2],
+];
 /**
  * Subtracts `b` from `a`.
  * @example
@@ -52,23 +57,48 @@ export const cross3 = (a, b) => [
 ];
 /** Returns Euclidean vector length in the vector's coordinate units. */
 export const length3 = (vector) => Math.hypot(vector[0], vector[1], vector[2]);
-/** Normalizes a finite vector and rejects nonfinite lengths or lengths at or below `epsilon`. */
+/** Returns Euclidean point distance without allocating an intermediate difference vector. */
+export const distance3 = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+/**
+ * Returns a unit vector; `epsilon` is a finite, non-negative length threshold (default `1e-12`).
+ * Rejects invalid thresholds, nonfinite lengths, and lengths at or below the threshold with
+ * `INVALID_TOLERANCE`, `NON_FINITE_VALUE`, and `DEGENERATE_GEOMETRY` respectively.
+ */
 export const normalize3 = (vector, epsilon = 1e-12) => {
+    const operation = "normalize3";
+    if (!Number.isFinite(epsilon) || epsilon < 0) {
+        throw new GeometryError("INVALID_TOLERANCE", "epsilon must be finite and non-negative.", {
+            operation,
+        });
+    }
     const length = length3(vector);
     if (!Number.isFinite(length)) {
-        throw new Error("Cannot normalize a vector without finite length.");
+        throw new GeometryError("NON_FINITE_VALUE", "Cannot normalize a vector without finite length.", {
+            operation,
+        });
     }
     if (length <= epsilon) {
-        throw new Error("Cannot normalize a zero-length vector.");
+        throw new GeometryError("DEGENERATE_GEOMETRY", "Cannot normalize a zero-length vector.", {
+            operation,
+        });
+    }
+    // Subnormal lengths lose relative precision; rescale only this rare case before division.
+    if (length < 2 ** -1022) {
+        const maximum = Math.max(Math.abs(vector[0]), Math.abs(vector[1]), Math.abs(vector[2]));
+        const x = vector[0] / maximum;
+        const y = vector[1] / maximum;
+        const z = vector[2] / maximum;
+        const scaledLength = Math.hypot(x, y, z);
+        return [x / scaledLength, y / scaledLength, z / scaledLength];
     }
-    return scale3(vector, 1 / length);
+    return [vector[0] / length, vector[1] / length, vector[2] / length];
 };
 /** Linearly interpolates two vectors; `t` is dimensionless and may extrapolate. */
 export const lerp3 = (a, b, t) => add3(a, scale3(subtract3(b, a), t));
 /** Removes the component parallel to a normalized plane normal. */
 export const projectOntoPlane3 = (vector, normal) => subtract3(vector, scale3(normal, dot3(vector, normal)));
-/** Rotates a vector right-handed around an axis by `angle` radians. */
-export const rotateAroundAxis3 = (vector, axis, angle) => {
+/** Rotates a vector right-handed around a unit axis by `angle` radians. */
+export const rotateAroundAxis3Radians = (vector, axis, angle) => {
     const cosine = Math.cos(angle);
     const sine = Math.sin(angle);
     return add3(add3(scale3(vector, cosine), scale3(cross3(axis, vector), sine)), scale3(axis, dot3(axis, vector) * (1 - cosine)));

package/dist/geometry/mechanical/gear-motion.js

@@ -50,7 +50,8 @@ const multiPolygonArea = (multiPolygon) => multiPolygon.reduce((total, polygon)
 /**
  * Measures sampled kinematic interference over one tooth cycle of an internal gear pair.
  *
- * The driver and ring rotate in the same direction at their resolved tooth-count ratio. Each
+ * The driver and ring start with half-tooth offsets for odd tooth counts, then rotate in the
+ * same direction at their resolved tooth-count ratio. Each
  * sampled pinion outline is subtracted from the ring's center-and-space opening; remaining area is
  * solid overlap. This catches involute, tip, and trimming interference that a single assembled pose
  * misses. It is a deterministic model check, not a certified gear-rating calculation.
@@ -70,12 +71,14 @@ export function measureInternalCylindricalGearPairMotion(spec, options = {}) {
     const ringSpace = sampleInternalCylindricalGearSpaceOutline(spec.driven, options.outline);
     const ringTipRadius = pair.driven.pitchRadius - pair.driven.addendum;
     const contactWindow = contactWindowPolygon(pair.centerDistance, pair.driver.outsideRadius, ringTipRadius);
-    const initialRingPhase = pair.driven.toothCount % 2 === 0 ? 0 : pair.driven.angularPitch / 2;
+    const initialRingPhase = pair.driven.toothCount % 2 === 0 ? 0 : pair.driven.angularPitchRadians / 2;
+    const initialDriverPhase = pair.driver.toothCount % 2 === 0 ? 0 : pair.driver.angularPitchRadians / 2;
     let maximumOverlapArea = 0;
-    let maximumPhase = 0;
+    let maximumPhase = initialDriverPhase;
     for (let sample = 0; sample < samples; sample += 1) {
-        const driverPhase = (pair.driver.angularPitch * sample) / samples;
-        const drivenPhase = initialRingPhase + driverPhase / pair.ratio;
+        const phase = (pair.driver.angularPitchRadians * sample) / samples;
+        const driverPhase = initialDriverPhase + phase;
+        const drivenPhase = initialRingPhase + phase / pair.ratio;
         const posedDriver = clippingPolygon(transformedLoop(driver, driverPhase));
         const posedSpace = clippingPolygon(transformedLoop(ringSpace, drivenPhase, pair.centerDistance));
         const contactDriver = polygonClipping.intersection(posedDriver, contactWindow);

package/dist/geometry/mechanical/gears.js

@@ -33,22 +33,22 @@ const freezePoints = (points) => {
  * count `z_v = z / cos³(beta)`, so increasing helix angle can reduce the physical tooth count.
  */
 export function minimumCylindricalGearToothCountWithoutUndercut(spec = {}) {
-    const pressureAngleDegrees = finite(spec.pressureAngleDegrees ?? DEFAULT_PRESSURE_ANGLE_DEGREES, "Pressure angle", "minimumCylindricalGearToothCountWithoutUndercut");
-    const helixAngleDegrees = finite(spec.helixAngleDegrees ?? 0, "Helix angle", "minimumCylindricalGearToothCountWithoutUndercut");
-    if (!(pressureAngleDegrees > 0 && pressureAngleDegrees < 45)) {
+    const pressureAngle = finite(spec.pressureAngle ?? DEFAULT_PRESSURE_ANGLE_DEGREES, "Pressure angle", "minimumCylindricalGearToothCountWithoutUndercut");
+    const helixAngle = finite(spec.helixAngle ?? 0, "Helix angle", "minimumCylindricalGearToothCountWithoutUndercut");
+    if (!(pressureAngle > 0 && pressureAngle < 45)) {
         throw new GeometryError("INVALID_ARGUMENT", "Pressure angle must be greater than 0 and less than 45 degrees.", {
             operation: "minimumCylindricalGearToothCountWithoutUndercut",
-            details: { pressureAngleDegrees },
+            details: { pressureAngle },
         });
     }
-    if (!(Math.abs(helixAngleDegrees) < 45)) {
+    if (!(Math.abs(helixAngle) < 45)) {
         throw new GeometryError("INVALID_ARGUMENT", "The absolute helix angle must be less than 45 degrees.", {
             operation: "minimumCylindricalGearToothCountWithoutUndercut",
-            details: { helixAngleDegrees },
+            details: { helixAngle },
         });
     }
-    const pressureAngleRadians = degreesToRadians(pressureAngleDegrees);
-    const helixAngleRadians = degreesToRadians(helixAngleDegrees);
+    const pressureAngleRadians = degreesToRadians(pressureAngle);
+    const helixAngleRadians = degreesToRadians(helixAngle);
     const exact = (2 * Math.cos(helixAngleRadians) ** 3) / Math.sin(pressureAngleRadians) ** 2;
     // Exact boundary cases such as alpha=30° should not round up because of floating-point noise.
     return Math.ceil(exact - Math.max(1, Math.abs(exact)) * 1e-12);
@@ -64,7 +64,7 @@ const resolveSimpleInvoluteProfileFacts = (dimensions, operation) => {
     const halfAngleAtTip = halfAngleAt(dimensions.outsideRadius);
     if (!(startRadius <= dimensions.outsideRadius) ||
         !(halfAngleAtTip > 0) ||
-        !(halfAngleAtStart < dimensions.angularPitch / 2)) {
+        !(halfAngleAtStart < dimensions.angularPitchRadians / 2)) {
         throw new GeometryError("DEGENERATE_GEOMETRY", "The selected tooth proportions cannot form a simple involute outline.", {
             operation,
             details: { halfAngleAtStart, halfAngleAtTip, startRadius },
@@ -73,7 +73,7 @@ const resolveSimpleInvoluteProfileFacts = (dimensions, operation) => {
     return Object.freeze({ halfAngleAt, halfAngleAtStart, halfAngleAtTip, startRadius });
 };
 const internalCylindricalGearSpaceDimensions = (dimensions) => {
-    const circularPitch = dimensions.angularPitch * dimensions.pitchRadius;
+    const circularPitch = dimensions.angularPitchRadians * dimensions.pitchRadius;
     return Object.freeze({
         ...dimensions,
         outsideRadius: dimensions.pitchRadius + dimensions.dedendum,
@@ -90,8 +90,8 @@ const internalCylindricalGearSpaceDimensions = (dimensions) => {
 const resolveCylindricalGearDimensions = (spec, profile) => {
     const toothCount = finite(spec.toothCount, "Tooth count");
     const module = finite(spec.module, "Module");
-    const pressureAngleDegrees = finite(spec.pressureAngleDegrees ?? DEFAULT_PRESSURE_ANGLE_DEGREES, "Pressure angle");
-    const helixAngleDegrees = finite(spec.helixAngleDegrees ?? 0, "Helix angle");
+    const pressureAngle = finite(spec.pressureAngle ?? DEFAULT_PRESSURE_ANGLE_DEGREES, "Pressure angle");
+    const helixAngle = finite(spec.helixAngle ?? 0, "Helix angle");
     const backlash = finite(spec.backlash ?? 0, "Backlash");
     const clearanceFactor = finite(spec.clearanceFactor ?? DEFAULT_CLEARANCE_FACTOR, "Clearance factor");
     if (!Number.isInteger(toothCount) || toothCount < 6 || toothCount > MAXIMUM_TOOTH_COUNT) {
@@ -103,29 +103,29 @@ const resolveCylindricalGearDimensions = (spec, profile) => {
             details: { module },
         });
     }
-    if (!(pressureAngleDegrees > 0 && pressureAngleDegrees < 45)) {
-        throw new GeometryError("INVALID_ARGUMENT", "Pressure angle must be greater than 0 and less than 45 degrees.", { operation: "resolveCylindricalGear", details: { pressureAngleDegrees } });
+    if (!(pressureAngle > 0 && pressureAngle < 45)) {
+        throw new GeometryError("INVALID_ARGUMENT", "Pressure angle must be greater than 0 and less than 45 degrees.", { operation: "resolveCylindricalGear", details: { pressureAngle } });
     }
-    if (!(Math.abs(helixAngleDegrees) < 45)) {
-        throw new GeometryError("INVALID_ARGUMENT", "The absolute helix angle must be less than 45 degrees.", { operation: "resolveCylindricalGear", details: { helixAngleDegrees } });
+    if (!(Math.abs(helixAngle) < 45)) {
+        throw new GeometryError("INVALID_ARGUMENT", "The absolute helix angle must be less than 45 degrees.", { operation: "resolveCylindricalGear", details: { helixAngle } });
     }
     if (backlash < 0 || clearanceFactor < 0) {
         throw new GeometryError("INVALID_ARGUMENT", "Backlash and clearance factor must be non-negative.", { operation: "resolveCylindricalGear" });
     }
-    const pressureAngleRadians = degreesToRadians(pressureAngleDegrees);
-    const helixAngleRadians = degreesToRadians(helixAngleDegrees);
+    const pressureAngleRadians = degreesToRadians(pressureAngle);
+    const helixAngleRadians = degreesToRadians(helixAngle);
     const minimumToothCountWithoutUndercut = minimumCylindricalGearToothCountWithoutUndercut({
-        helixAngleDegrees,
-        pressureAngleDegrees,
+        helixAngle,
+        pressureAngle,
     });
     const virtualToothCount = toothCount / Math.cos(helixAngleRadians) ** 3;
     if (profile === "external" && toothCount < minimumToothCountWithoutUndercut) {
-        throw new GeometryError("INVALID_ARGUMENT", `An unshifted full-depth external involute at ${pressureAngleDegrees}° pressure angle and ${Math.abs(helixAngleDegrees)}° helix angle requires at least ${minimumToothCountWithoutUndercut} teeth to avoid undercut; profile shift is not supported.`, {
+        throw new GeometryError("INVALID_ARGUMENT", `An unshifted full-depth external involute at ${pressureAngle}° pressure angle and ${Math.abs(helixAngle)}° helix angle requires at least ${minimumToothCountWithoutUndercut} teeth to avoid undercut; profile shift is not supported.`, {
             operation: "resolveCylindricalGear",
             details: {
-                helixAngleDegrees,
+                helixAngle,
                 minimumToothCountWithoutUndercut,
-                pressureAngleDegrees,
+                pressureAngle,
                 toothCount,
                 virtualToothCount,
             },
@@ -151,7 +151,7 @@ const resolveCylindricalGearDimensions = (spec, profile) => {
     }
     const dimensions = Object.freeze({
         addendum,
-        angularPitch: (Math.PI * 2) / toothCount,
+        angularPitchRadians: (Math.PI * 2) / toothCount,
         backlash,
         baseRadius: pitchRadius * Math.cos(transversePressureAngleRadians),
         dedendum,
@@ -199,12 +199,12 @@ export function resolveCylindricalGearPair(spec) {
     // separate tip/interference constraints are checked by the pair and coupled-motion validators.
     const driven = resolveCylindricalGearDimensions(spec.driven, spec.mesh);
     const epsilon = 1e-10;
-    const driverHelixDegrees = spec.driver.helixAngleDegrees ?? 0;
-    const drivenHelixDegrees = spec.driven.helixAngleDegrees ?? 0;
-    const requiredDrivenHelixAngleDegrees = spec.mesh === "external" ? -driverHelixDegrees : driverHelixDegrees;
+    const driverHelixDegrees = spec.driver.helixAngle ?? 0;
+    const drivenHelixDegrees = spec.driven.helixAngle ?? 0;
+    const requiredDrivenHelixAngle = spec.mesh === "external" ? -driverHelixDegrees : driverHelixDegrees;
     if (Math.abs(driver.module - driven.module) > epsilon ||
         Math.abs(driver.pressureAngleRadians - driven.pressureAngleRadians) > epsilon ||
-        Math.abs(drivenHelixDegrees - requiredDrivenHelixAngleDegrees) > epsilon) {
+        Math.abs(drivenHelixDegrees - requiredDrivenHelixAngle) > epsilon) {
         throw new GeometryError("INVALID_ARGUMENT", "Mating gears must share normal module and pressure angle with conjugate helix hands.", { operation: "resolveCylindricalGearPair" });
     }
     if (spec.mesh === "internal" && driven.pitchRadius <= driver.outsideRadius) {
@@ -218,7 +218,7 @@ export function resolveCylindricalGearPair(spec) {
         driven,
         drivenDirection: spec.mesh === "external" ? -1 : 1,
         ratio: driven.toothCount / driver.toothCount,
-        requiredDrivenHelixAngleDegrees,
+        requiredDrivenHelixAngle,
     });
 }
 const exactSampleCount = (value, label, minimum, maximum, operation) => {
@@ -345,7 +345,7 @@ const sampleResolvedCylindricalGearOutline = (dimensions, options, operation) =>
     const { halfAngleAt, halfAngleAtStart, halfAngleAtTip, startRadius } = resolveSimpleInvoluteProfileFacts(dimensions, operation);
     const limits = resolveGeometrySamplingLimits(options.limits);
     const resolution = resolveGeometryResolution(options.resolution, limits);
-    const rootArcAngle = dimensions.angularPitch / 2 - halfAngleAtStart;
+    const rootArcAngle = dimensions.angularPitchRadians / 2 - halfAngleAtStart;
     const rootArcSamples = options.rootArcSamples === undefined
         ? resolveAdaptiveArcSamples(dimensions.rootRadius, rootArcAngle, resolution, limits)
         : exactSampleCount(options.rootArcSamples, "Root arc samples", 1, limits.maxCircularSegments, operation);
@@ -361,10 +361,12 @@ const sampleResolvedCylindricalGearOutline = (dimensions, options, operation) =>
         : exactSampleCount(options.flankSamples, "Flank samples", 2, maximumFlankSamples, operation);
     const estimatedPoints = dimensions.toothCount * (flankSamples * 2 + fixedPerTooth);
     assertSamplingCount(estimatedPoints, operation, limits.maxProfilePoints);
-    const points = [polarPoint(dimensions.rootRadius, -dimensions.angularPitch / 2)];
+    const points = [
+        polarPoint(dimensions.rootRadius, -dimensions.angularPitchRadians / 2),
+    ];
     for (let tooth = 0; tooth < dimensions.toothCount; tooth += 1) {
-        const centerAngle = tooth * dimensions.angularPitch;
-        const valleyBefore = centerAngle - dimensions.angularPitch / 2;
+        const centerAngle = tooth * dimensions.angularPitchRadians;
+        const valleyBefore = centerAngle - dimensions.angularPitchRadians / 2;
         const leftRootAngle = centerAngle - halfAngleAtStart;
         for (let sample = 1; sample <= rootArcSamples; sample += 1) {
             const amount = sample / rootArcSamples;
@@ -391,7 +393,7 @@ const sampleResolvedCylindricalGearOutline = (dimensions, options, operation) =>
         if (startRadius > dimensions.rootRadius) {
             points.push(polarPoint(dimensions.rootRadius, rightRootAngle));
         }
-        const valleyAfter = centerAngle + dimensions.angularPitch / 2;
+        const valleyAfter = centerAngle + dimensions.angularPitchRadians / 2;
         for (let sample = 1; sample <= rootArcSamples; sample += 1) {
             const amount = sample / rootArcSamples;
             points.push(polarPoint(dimensions.rootRadius, rightRootAngle + (valleyAfter - rightRootAngle) * amount));
@@ -431,11 +433,9 @@ export function resolveRackPitch(spec) {
     const reference = resolveCylindricalGear({
         ...(spec.backlash === undefined ? {} : { backlash: spec.backlash }),
         ...(spec.clearanceFactor === undefined ? {} : { clearanceFactor: spec.clearanceFactor }),
-        ...(spec.helixAngleDegrees === undefined ? {} : { helixAngleDegrees: spec.helixAngleDegrees }),
+        ...(spec.helixAngle === undefined ? {} : { helixAngle: spec.helixAngle }),
         module: spec.module,
-        ...(spec.pressureAngleDegrees === undefined
-            ? {}
-            : { pressureAngleDegrees: spec.pressureAngleDegrees }),
+        ...(spec.pressureAngle === undefined ? {} : { pressureAngle: spec.pressureAngle }),
         // Rack pitch facts do not depend on this cylindrical reference count. Use the maximum so the
         // reference remains undercut-free for every supported normal pressure and helix angle.
         toothCount: MAXIMUM_TOOTH_COUNT,

package/dist/geometry/mechanical/index.js

@@ -5,9 +5,9 @@
  */
 export { minimumCylindricalGearToothCountWithoutUndercut, resolveCylindricalGear, resolveCylindricalGearPair, resolveRackPitch, sampleCylindricalGearOutline, sampleInternalCylindricalGearSpaceOutline, sampleRackToothPath, } from "./gears.js";
 export { measureInternalCylindricalGearPairMotion } from "./gear-motion.js";
-export { buildHelicalThreadRidgeMesh, buildHelicalThreadSolidMesh } from "./thread-mesh.js";
-export { compensateThreadProfileAxially, compensateThreadProfileForFaceting, createThreadProfile, } from "./thread-profiles.js";
+export { helicalThreadRidgeMesh, helicalThreadSolidMesh } from "./thread-mesh.js";
+export { compensateThreadProfileAxially, compensateThreadProfileForFaceting, threadProfile, } from "./thread-profiles.js";
 export { preflightHelicalThreadSolidMesh } from "./thread-mesh-plan.js";
 export { sampleConventionalThreadHelices as sampleThreadHelices } from "./thread-helices.js";
 export { compensateThreadDiameters, PRINTABLE_THREAD_FIT_POLICIES, resolvePrintableThreadFitPolicy, resolveThreadCircularSegments, } from "./threads.js";
-export { getMetricClearanceHole, getMetricFastenerStandard, METRIC_FASTENER_STANDARDS, } from "./standards.js";
+export { getMetricClearanceHoleDiameter, getMetricFastenerStandard, METRIC_FASTENER_STANDARDS, } from "./standards.js";

package/dist/geometry/mechanical/standards.js

@@ -50,7 +50,7 @@ export function getMetricFastenerStandard(size) {
     return METRIC_FASTENER_STANDARDS[size];
 }
 /** Returns one recommended metric clearance-hole diameter in millimetres. */
-export function getMetricClearanceHole(size, fit = "normal") {
+export function getMetricClearanceHoleDiameter(size, fit = "normal") {
     const holes = getMetricFastenerStandard(size).clearanceHoles;
     const diameter = fit === "close"
         ? holes.close

package/dist/geometry/mechanical/thread-helices.js

@@ -29,10 +29,9 @@ export function sampleConventionalThreadHelices(options) {
     const count = Math.max(1, Math.ceil(turns * density));
     assertSamplingCount(starts * (count + 1), operation, resolveGeometrySamplingLimits(options.limits).maxPathPoints);
     const direction = handedness === "right" ? 1 : -1;
-    const phase = assertFiniteThreadNumber((assertFiniteThreadNumber(options.phaseDegrees ?? 0, "phaseDegrees", operation) * Math.PI) /
-        180, "phase", operation);
+    const phaseRadians = assertFiniteThreadNumber((assertFiniteThreadNumber(options.phase ?? 0, "phase", operation) * Math.PI) / 180, "phase", operation);
     const paths = Object.freeze(Array.from({ length: starts }, (_, start) => {
-        const initial = phase + (direction * 2 * Math.PI * start) / starts;
+        const initial = phaseRadians + (direction * 2 * Math.PI * start) / starts;
         return Object.freeze(Array.from({ length: count + 1 }, (_, index) => {
             const t = index / count;
             const z = length * t;

package/dist/geometry/mechanical/thread-mesh-plan.js

@@ -133,9 +133,9 @@ export const resolveHelicalThreadMeshOptions = (options, operation, circularSamp
         throw new GeometryError("INVALID_ARGUMENT", "Exact circularSegments must be divisible by the requested thread starts.", { operation, details: { circularSegments: base, starts } });
     }
     const segments = Math.ceil(base / starts) * starts;
-    const maximumSegments = resolution.maximumSegments;
-    if (segments > maximumSegments) {
-        throw new GeometryError("COMPLEXITY_LIMIT", "Start-aligned thread tessellation exceeds the configured segment safety limit.", { operation, details: { maximumSegments, segments } });
+    const maxSegments = resolution.maxSegments;
+    if (segments > maxSegments) {
+        throw new GeometryError("COMPLEXITY_LIMIT", "Start-aligned thread tessellation exceeds the configured segment safety limit.", { operation, details: { maxSegments, segments } });
     }
     const handedness = options.handedness ?? "right";
     if (handedness !== "left" && handedness !== "right")
@@ -199,8 +199,7 @@ export const resolveHelicalThreadMeshOptions = (options, operation, circularSamp
         leadInLength,
         leadInShape,
         length,
-        phase: (assertFiniteThreadNumber(options.phaseDegrees ?? 0, "phaseDegrees", operation) * Math.PI) /
-            180,
+        phase: (assertFiniteThreadNumber(options.phase ?? 0, "phase", operation) * Math.PI) / 180,
         section,
         segments,
         starts,

package/dist/geometry/mechanical/thread-mesh.js

@@ -1,6 +1,6 @@
 /** Closed ridge and complete-solid mesh construction from resolved thread plans. */
 import { triangulateContour } from "../loft/loft.js";
-import { joinTriangleMeshes, measureTriangleMesh, reverseTriangleMesh, validateTriangleMesh, } from "../mesh/mesh.js";
+import { analyzeTriangleMesh, joinTriangleMeshes, reverseTriangleMesh, validateTriangleMesh, } from "../mesh/mesh.js";
 import { assertMeshAllocationWithinLimits, resolveModelingLimits } from "../model-limits.js";
 import { resolveHelicalThreadMeshOptions, resolveHelicalThreadSolidMeshPreflight, } from "./thread-mesh-plan.js";
 import { buildThreadSurfaceColumn, stitchThreadSurfaceColumns } from "./thread-surface.js";
@@ -61,7 +61,7 @@ const buildThreadRidgeComponent = (options) => {
         indices: new Uint32Array(indices),
     };
     validateTriangleMesh(mesh, { requireClosed: true });
-    if (measureTriangleMesh(mesh, { requireClosed: true }).signedVolume < 0)
+    if (analyzeTriangleMesh(mesh, { requireClosed: true }).signedVolume < 0)
         mesh = reverseTriangleMesh(mesh);
     return mesh;
 };
@@ -74,8 +74,8 @@ const buildThreadRidgeComponent = (options) => {
  * conservative pre-allocation estimate rejects excessive meshes before constructing position
  * arrays.
  */
-export function buildHelicalThreadSolidMesh(options) {
-    const operation = "buildHelicalThreadSolidMesh";
+export function helicalThreadSolidMesh(options) {
+    const operation = "helicalThreadSolidMesh";
     const { maximumAxialSegmentLength, resolved } = resolveHelicalThreadSolidMeshPreflight(options, operation);
     const positions = [];
     const columns = Array.from({ length: resolved.segments }, (_, column) => buildThreadSurfaceColumn(options.profile, resolved, options, resolved.phase + (column * 2 * Math.PI) / resolved.segments, maximumAxialSegmentLength, positions));
@@ -103,7 +103,7 @@ export function buildHelicalThreadSolidMesh(options) {
         indices: new Uint32Array(indices),
     };
     validateTriangleMesh(mesh, { requireClosed: true });
-    if (measureTriangleMesh(mesh, { requireClosed: true }).signedVolume < 0) {
+    if (analyzeTriangleMesh(mesh, { requireClosed: true }).signedVolume < 0) {
         mesh = reverseTriangleMesh(mesh);
     }
     return mesh;
@@ -113,8 +113,8 @@ export function buildHelicalThreadSolidMesh(options) {
  * shaft's radial/axial frame. The mesh is intended for union with its
  * minor-envelope cylinder and never owns WASM objects.
  */
-export function buildHelicalThreadRidgeMesh(options) {
-    const operation = "buildHelicalThreadRidgeMesh";
+export function helicalThreadRidgeMesh(options) {
+    const operation = "helicalThreadRidgeMesh";
     const resolved = resolveHelicalThreadMeshOptions(options, operation);
     const z0 = resolved.bottomBoundary - resolved.section[0][0];
     const z1 = resolved.topBoundary - resolved.section.at(-1)[0];