@metamesh/modeling 0.0.0-stage → 0.7.0

package/dist/geometry/mechanical/gears.js

@@ -0,0 +1,484 @@
+import { GeometryError } from "../errors.js";
+import { signedAreaLoop2 } from "../regions.js";
+import { resolveCircularSegments, resolveGeometryResolution, } from "../resolution.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling-limits.js";
+const DEFAULT_PRESSURE_ANGLE_DEGREES = 20;
+const DEFAULT_CLEARANCE_FACTOR = 0.25;
+const MAXIMUM_TOOTH_COUNT = 1_000;
+const finite = (value, label, operation = "resolveCylindricalGear") => {
+    if (!Number.isFinite(value)) {
+        throw new GeometryError("NON_FINITE_VALUE", `${label} must be finite.`, {
+            operation,
+        });
+    }
+    return value;
+};
+const degreesToRadians = (degrees) => (degrees * Math.PI) / 180;
+const involuteAngle = (baseRadius, radius) => {
+    if (radius <= baseRadius)
+        return 0;
+    const pressure = Math.acos(baseRadius / radius);
+    return Math.tan(pressure) - pressure;
+};
+const polarPoint = (radius, angle) => Object.freeze([radius * Math.cos(angle), radius * Math.sin(angle)]);
+const freezePoints = (points) => {
+    for (const point of points)
+        Object.freeze(point);
+    return Object.freeze(points);
+};
+/**
+ * Returns the smallest unshifted full-depth external tooth count that avoids rack-cutter undercut.
+ *
+ * The normal-plane limit is `2 / sin²(alpha_n)`. Helical gears use the standard virtual tooth
+ * 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)) {
+        throw new GeometryError("INVALID_ARGUMENT", "Pressure angle must be greater than 0 and less than 45 degrees.", {
+            operation: "minimumCylindricalGearToothCountWithoutUndercut",
+            details: { pressureAngleDegrees },
+        });
+    }
+    if (!(Math.abs(helixAngleDegrees) < 45)) {
+        throw new GeometryError("INVALID_ARGUMENT", "The absolute helix angle must be less than 45 degrees.", {
+            operation: "minimumCylindricalGearToothCountWithoutUndercut",
+            details: { helixAngleDegrees },
+        });
+    }
+    const pressureAngleRadians = degreesToRadians(pressureAngleDegrees);
+    const helixAngleRadians = degreesToRadians(helixAngleDegrees);
+    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);
+}
+const resolveSimpleInvoluteProfileFacts = (dimensions, operation) => {
+    const startRadius = Math.max(dimensions.rootRadius, dimensions.baseRadius);
+    const pitchInvolute = involuteAngle(dimensions.baseRadius, dimensions.pitchRadius);
+    const halfPitchThicknessAngle = dimensions.toothThicknessAtPitch / (dimensions.pitchRadius * 2);
+    const halfAngleAt = (radius) => halfPitchThicknessAngle +
+        pitchInvolute -
+        involuteAngle(dimensions.baseRadius, Math.max(radius, dimensions.baseRadius));
+    const halfAngleAtStart = halfAngleAt(startRadius);
+    const halfAngleAtTip = halfAngleAt(dimensions.outsideRadius);
+    if (!(startRadius <= dimensions.outsideRadius) ||
+        !(halfAngleAtTip > 0) ||
+        !(halfAngleAtStart < dimensions.angularPitch / 2)) {
+        throw new GeometryError("DEGENERATE_GEOMETRY", "The selected tooth proportions cannot form a simple involute outline.", {
+            operation,
+            details: { halfAngleAtStart, halfAngleAtTip, startRadius },
+        });
+    }
+    return Object.freeze({ halfAngleAt, halfAngleAtStart, halfAngleAtTip, startRadius });
+};
+const internalCylindricalGearSpaceDimensions = (dimensions) => {
+    const circularPitch = dimensions.angularPitch * dimensions.pitchRadius;
+    return Object.freeze({
+        ...dimensions,
+        outsideRadius: dimensions.pitchRadius + dimensions.dedendum,
+        rootRadius: dimensions.pitchRadius - dimensions.addendum,
+        toothThicknessAtPitch: circularPitch - dimensions.toothThicknessAtPitch,
+    });
+};
+/**
+ * Validates and resolves a cylindrical involute gear into transverse dimensions.
+ *
+ * The gear axis is +Z and the returned radii describe its XY pitch plane.
+ * These are nominal printable-model dimensions, not a certified gear standard.
+ */
+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 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) {
+        throw new GeometryError("INVALID_ARGUMENT", `Tooth count must be an integer from 6 through ${MAXIMUM_TOOTH_COUNT}.`, { operation: "resolveCylindricalGear", details: { toothCount } });
+    }
+    if (!(module > 0)) {
+        throw new GeometryError("INVALID_ARGUMENT", "Module must be greater than zero.", {
+            operation: "resolveCylindricalGear",
+            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 (!(Math.abs(helixAngleDegrees) < 45)) {
+        throw new GeometryError("INVALID_ARGUMENT", "The absolute helix angle must be less than 45 degrees.", { operation: "resolveCylindricalGear", details: { helixAngleDegrees } });
+    }
+    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 minimumToothCountWithoutUndercut = minimumCylindricalGearToothCountWithoutUndercut({
+        helixAngleDegrees,
+        pressureAngleDegrees,
+    });
+    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.`, {
+            operation: "resolveCylindricalGear",
+            details: {
+                helixAngleDegrees,
+                minimumToothCountWithoutUndercut,
+                pressureAngleDegrees,
+                toothCount,
+                virtualToothCount,
+            },
+        });
+    }
+    const transverseModule = module / Math.cos(helixAngleRadians);
+    const transversePressureAngleRadians = Math.atan(Math.tan(pressureAngleRadians) / Math.cos(helixAngleRadians));
+    const pitchRadius = (transverseModule * toothCount) / 2;
+    const addendum = module;
+    const dedendum = module * (1 + clearanceFactor);
+    const outsideRadius = pitchRadius + addendum;
+    const rootRadius = pitchRadius - dedendum;
+    const circularPitch = Math.PI * transverseModule;
+    const toothThicknessAtPitch = circularPitch / 2 - backlash;
+    if (!(rootRadius > 0)) {
+        throw new GeometryError("DEGENERATE_GEOMETRY", "The dedendum consumes the gear root radius.", {
+            operation: "resolveCylindricalGear",
+            details: { rootRadius },
+        });
+    }
+    if (!(toothThicknessAtPitch > 0) || !(toothThicknessAtPitch < circularPitch)) {
+        throw new GeometryError("DEGENERATE_GEOMETRY", "Backlash leaves an invalid tooth thickness at the pitch circle.", { operation: "resolveCylindricalGear", details: { toothThicknessAtPitch } });
+    }
+    const dimensions = Object.freeze({
+        addendum,
+        angularPitch: (Math.PI * 2) / toothCount,
+        backlash,
+        baseRadius: pitchRadius * Math.cos(transversePressureAngleRadians),
+        dedendum,
+        helixAngleRadians,
+        minimumToothCountWithoutUndercut,
+        module,
+        outsideRadius,
+        pitchRadius,
+        pressureAngleRadians,
+        rootRadius,
+        toothCount,
+        toothThicknessAtPitch,
+        transverseModule,
+        transversePressureAngleRadians,
+        virtualToothCount,
+    });
+    resolveSimpleInvoluteProfileFacts(profile === "external" ? dimensions : internalCylindricalGearSpaceDimensions(dimensions), "resolveCylindricalGear");
+    return dimensions;
+};
+/**
+ * Resolves a validated unshifted full-depth external cylindrical gear.
+ *
+ * The gear axis is +Z and the returned radii describe its XY pitch plane. Inputs below the
+ * pressure- and helix-dependent no-undercut tooth count are rejected because profile shift is not
+ * currently supported.
+ */
+export function resolveCylindricalGear(spec) {
+    return resolveCylindricalGearDimensions(spec, "external");
+}
+/**
+ * Resolves ratio, center distance, and helix relationship for a gear pair.
+ *
+ * Both gears must use the same normal module, pressure angle, and helix-angle
+ * magnitude. An external pair uses opposite helix hands; an internal pair uses
+ * the same hand. The function validates those conjugate pitch invariants.
+ */
+export function resolveCylindricalGearPair(spec) {
+    if (spec.mesh !== "external" && spec.mesh !== "internal") {
+        throw new GeometryError("INVALID_ARGUMENT", "Unsupported cylindrical gear mesh kind.", {
+            operation: "resolveCylindricalGearPair",
+        });
+    }
+    const driver = resolveCylindricalGearDimensions(spec.driver, "external");
+    // Internal tooth spaces are not subject to the external rack-cutter undercut limit. Their
+    // 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;
+    if (Math.abs(driver.module - driven.module) > epsilon ||
+        Math.abs(driver.pressureAngleRadians - driven.pressureAngleRadians) > epsilon ||
+        Math.abs(drivenHelixDegrees - requiredDrivenHelixAngleDegrees) > 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) {
+        throw new GeometryError("DEGENERATE_GEOMETRY", "An internal driven gear must leave radial room for the driver tooth tips.", { operation: "resolveCylindricalGearPair" });
+    }
+    return Object.freeze({
+        centerDistance: spec.mesh === "external"
+            ? driver.pitchRadius + driven.pitchRadius
+            : driven.pitchRadius - driver.pitchRadius,
+        driver,
+        driven,
+        drivenDirection: spec.mesh === "external" ? -1 : 1,
+        ratio: driven.toothCount / driver.toothCount,
+        requiredDrivenHelixAngleDegrees,
+    });
+}
+const exactSampleCount = (value, label, minimum, maximum, operation) => {
+    const resolved = finite(value, label, operation);
+    if (!Number.isSafeInteger(resolved) || resolved < minimum) {
+        throw new GeometryError("INVALID_ARGUMENT", `${label} must be a safe integer of at least ${minimum}.`, { operation });
+    }
+    assertSamplingCount(resolved, operation, maximum);
+    return resolved;
+};
+const involutePoint = (baseRadius, radius) => {
+    const angle = involuteAngle(baseRadius, radius);
+    return [radius * Math.cos(angle), radius * Math.sin(angle)];
+};
+const involuteDerivative = (baseRadius, radius) => {
+    const angle = involuteAngle(baseRadius, radius);
+    const tangentParameter = Math.sqrt(Math.max(0, (radius / baseRadius) ** 2 - 1));
+    return [
+        Math.cos(angle) - tangentParameter * Math.sin(angle),
+        Math.sin(angle) + tangentParameter * Math.cos(angle),
+    ];
+};
+/** Maximum normal distance between one involute interval and its straight chord. */
+const involuteChordDeviation = (baseRadius, startRadius, endRadius) => {
+    const start = involutePoint(baseRadius, startRadius);
+    const end = involutePoint(baseRadius, endRadius);
+    const chordX = end[0] - start[0];
+    const chordY = end[1] - start[1];
+    const chordLength = Math.hypot(chordX, chordY);
+    if (chordLength === 0)
+        return 0;
+    const derivativeCross = (radius) => {
+        const derivative = involuteDerivative(baseRadius, radius);
+        return chordX * derivative[1] - chordY * derivative[0];
+    };
+    let lower = startRadius;
+    let upper = endRadius;
+    let lowerDerivative = derivativeCross(lower);
+    const upperDerivative = derivativeCross(upper);
+    if (lowerDerivative * upperDerivative <= 0) {
+        for (let iteration = 0; iteration < 48; iteration += 1) {
+            const middle = (lower + upper) / 2;
+            const middleDerivative = derivativeCross(middle);
+            if (lowerDerivative * middleDerivative <= 0) {
+                upper = middle;
+            }
+            else {
+                lower = middle;
+                lowerDerivative = middleDerivative;
+            }
+        }
+    }
+    else {
+        // Degenerate near-linear intervals can lose the derivative sign change to roundoff. A dense
+        // deterministic fallback still measures the physical curve rather than assuming zero error.
+        let maximum = 0;
+        for (let sample = 1; sample < 32; sample += 1) {
+            const point = involutePoint(baseRadius, startRadius + ((endRadius - startRadius) * sample) / 32);
+            maximum = Math.max(maximum, Math.abs(chordX * (point[1] - start[1]) - chordY * (point[0] - start[0])) / chordLength);
+        }
+        return maximum;
+    }
+    const point = involutePoint(baseRadius, (lower + upper) / 2);
+    return Math.abs(chordX * (point[1] - start[1]) - chordY * (point[0] - start[0])) / chordLength;
+};
+const resolveAdaptiveFlankSamples = (baseRadius, startRadius, endRadius, resolution, maximum, operation) => {
+    const satisfiesResolution = (samples) => {
+        for (let segment = 0; segment < samples; segment += 1) {
+            const segmentStart = startRadius + ((endRadius - startRadius) * segment) / samples;
+            const segmentEnd = startRadius + ((endRadius - startRadius) * (segment + 1)) / samples;
+            const chordStart = involutePoint(baseRadius, segmentStart);
+            const chordEnd = involutePoint(baseRadius, segmentEnd);
+            if (involuteChordDeviation(baseRadius, segmentStart, segmentEnd) > resolution.maxChordError ||
+                (resolution.maxSegmentLength !== undefined &&
+                    Math.hypot(chordEnd[0] - chordStart[0], chordEnd[1] - chordStart[1]) >
+                        resolution.maxSegmentLength)) {
+                return false;
+            }
+        }
+        return true;
+    };
+    // Preserve the smallest ordinary uniform count. For tighter requested tolerances, doubling
+    // and a bounded search avoid scanning every integer up to a host-raised profile ceiling.
+    for (let samples = 2; samples <= Math.min(32, maximum); samples += 1) {
+        if (satisfiesResolution(samples))
+            return samples;
+    }
+    let lower = 32;
+    while (lower < maximum) {
+        let upper = Math.min(maximum, lower * 2);
+        if (satisfiesResolution(upper)) {
+            while (upper - lower > 1) {
+                const middle = Math.floor((lower + upper) / 2);
+                if (satisfiesResolution(middle))
+                    upper = middle;
+                else
+                    lower = middle;
+            }
+            return upper;
+        }
+        lower = upper;
+    }
+    throw new GeometryError("COMPLEXITY_LIMIT", `The requested physical gear-flank tolerance requires more than ${maximum} samples per flank; the selected profile ceiling permits ${maximum}.`, {
+        operation,
+        details: {
+            baseRadius,
+            requiredCount: maximum + 1,
+            allowedCount: maximum,
+            endRadius,
+            maxChordError: resolution.maxChordError,
+            ...(resolution.maxSegmentLength === undefined
+                ? {}
+                : { maxSegmentLength: resolution.maxSegmentLength }),
+            startRadius,
+        },
+    });
+};
+const resolveAdaptiveArcSamples = (radius, angleRadians, resolution, limits) => {
+    const fullCircleSegments = resolveCircularSegments(radius, resolution, limits);
+    const samples = Math.max(1, Math.ceil((Math.abs(angleRadians) * fullCircleSegments) / (Math.PI * 2)));
+    return samples;
+};
+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 rootArcSamples = options.rootArcSamples === undefined
+        ? resolveAdaptiveArcSamples(dimensions.rootRadius, rootArcAngle, resolution, limits)
+        : exactSampleCount(options.rootArcSamples, "Root arc samples", 1, limits.maxCircularSegments, operation);
+    const tipArcSamples = options.tipArcSamples === undefined
+        ? resolveAdaptiveArcSamples(dimensions.outsideRadius, halfAngleAtTip * 2, resolution, limits)
+        : exactSampleCount(options.tipArcSamples, "Tip arc samples", 1, limits.maxCircularSegments, operation);
+    const radialTransitions = startRadius > dimensions.rootRadius ? 2 : 0;
+    const fixedPerTooth = rootArcSamples * 2 + tipArcSamples + radialTransitions;
+    assertSamplingCount(dimensions.toothCount * (4 + fixedPerTooth), operation, limits.maxProfilePoints);
+    const maximumFlankSamples = Math.floor((Math.floor(limits.maxProfilePoints / dimensions.toothCount) - fixedPerTooth) / 2);
+    const flankSamples = options.flankSamples === undefined
+        ? resolveAdaptiveFlankSamples(dimensions.baseRadius, startRadius, dimensions.outsideRadius, resolution, maximumFlankSamples, 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)];
+    for (let tooth = 0; tooth < dimensions.toothCount; tooth += 1) {
+        const centerAngle = tooth * dimensions.angularPitch;
+        const valleyBefore = centerAngle - dimensions.angularPitch / 2;
+        const leftRootAngle = centerAngle - halfAngleAtStart;
+        for (let sample = 1; sample <= rootArcSamples; sample += 1) {
+            const amount = sample / rootArcSamples;
+            points.push(polarPoint(dimensions.rootRadius, valleyBefore + (leftRootAngle - valleyBefore) * amount));
+        }
+        if (startRadius > dimensions.rootRadius) {
+            points.push(polarPoint(startRadius, leftRootAngle));
+        }
+        for (let sample = 1; sample <= flankSamples; sample += 1) {
+            const amount = sample / flankSamples;
+            const radius = startRadius + (dimensions.outsideRadius - startRadius) * amount;
+            points.push(polarPoint(radius, centerAngle - halfAngleAt(radius)));
+        }
+        for (let sample = 1; sample <= tipArcSamples; sample += 1) {
+            const amount = sample / tipArcSamples;
+            points.push(polarPoint(dimensions.outsideRadius, centerAngle - halfAngleAtTip + halfAngleAtTip * 2 * amount));
+        }
+        for (let sample = flankSamples - 1; sample >= 0; sample -= 1) {
+            const amount = sample / flankSamples;
+            const radius = startRadius + (dimensions.outsideRadius - startRadius) * amount;
+            points.push(polarPoint(radius, centerAngle + halfAngleAt(radius)));
+        }
+        const rightRootAngle = centerAngle + halfAngleAtStart;
+        if (startRadius > dimensions.rootRadius) {
+            points.push(polarPoint(dimensions.rootRadius, rightRootAngle));
+        }
+        const valleyAfter = centerAngle + dimensions.angularPitch / 2;
+        for (let sample = 1; sample <= rootArcSamples; sample += 1) {
+            const amount = sample / rootArcSamples;
+            points.push(polarPoint(dimensions.rootRadius, rightRootAngle + (valleyAfter - rightRootAngle) * amount));
+        }
+    }
+    points.pop();
+    if (!(signedAreaLoop2(points) > 0)) {
+        throw new GeometryError("INVALID_TOPOLOGY", "The sampled gear outline must be counter-clockwise.", {
+            operation,
+        });
+    }
+    return freezePoints(points);
+};
+/**
+ * Samples a complete external involute gear boundary in the XY plane.
+ *
+ * The returned loop is counter-clockwise, closed implicitly without a repeated
+ * seam point, and contains no holes. Its center is the origin and its axis is
+ * +Z. Bore, hub, keyway, twist, and face-width choices remain generator-owned.
+ */
+export function sampleCylindricalGearOutline(spec, options = {}) {
+    return sampleResolvedCylindricalGearOutline(resolveCylindricalGear(spec), options, "sampleCylindricalGearOutline");
+}
+/**
+ * Samples the center opening and tooth spaces used to subtract an internal ring gear.
+ *
+ * Internal tooth tips lie one addendum below the pitch radius and their roots lie one
+ * dedendum above it. At the pitch circle, positive backlash widens each sampled space
+ * tangentially. The returned CCW loop encloses the center and is intended to be reversed
+ * when used as a region hole.
+ */
+export function sampleInternalCylindricalGearSpaceOutline(spec, options = {}) {
+    return sampleResolvedCylindricalGearOutline(internalCylindricalGearSpaceDimensions(resolveCylindricalGearDimensions(spec, "internal")), options, "sampleInternalCylindricalGearSpaceOutline");
+}
+/** Resolves a rack segment that is conjugate with the same normal cylindrical pitch system. */
+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 }),
+        module: spec.module,
+        ...(spec.pressureAngleDegrees === undefined
+            ? {}
+            : { pressureAngleDegrees: spec.pressureAngleDegrees }),
+        // 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,
+    });
+    const toothCount = finite(spec.toothCount, "Rack tooth count");
+    if (!Number.isInteger(toothCount) || toothCount < 1 || toothCount > MAXIMUM_TOOTH_COUNT) {
+        throw new GeometryError("INVALID_ARGUMENT", `Rack tooth count must be an integer from 1 through ${MAXIMUM_TOOTH_COUNT}.`, { operation: "resolveRackPitch", details: { toothCount } });
+    }
+    const pitch = Math.PI * reference.transverseModule;
+    return Object.freeze({
+        addendum: reference.addendum,
+        dedendum: reference.dedendum,
+        helixAngleRadians: reference.helixAngleRadians,
+        length: pitch * toothCount,
+        module: reference.module,
+        pitch,
+        pressureAngleRadians: reference.transversePressureAngleRadians,
+        toothCount,
+        toothThicknessAtPitch: reference.toothThicknessAtPitch,
+    });
+}
+/**
+ * Samples the open top boundary of a finite rack in its XY pitch plane.
+ *
+ * X follows rack travel, Y is tooth height, and the pitch line is `Y = 0`.
+ * The path begins and ends on the root line, omits duplicate adjacent points,
+ * and leaves base thickness, mounting features, extrusion, and helical sweep to
+ * the owning generator.
+ */
+export function sampleRackToothPath(spec, limits = {}) {
+    const dimensions = resolveRackPitch(spec);
+    assertSamplingCount(dimensions.toothCount * 4 + 2, "sampleRackToothPath", resolveGeometrySamplingLimits(limits).maxPathPoints);
+    const slope = Math.tan(dimensions.pressureAngleRadians);
+    const rootHalfWidth = dimensions.toothThicknessAtPitch / 2 + dimensions.dedendum * slope;
+    const tipHalfWidth = dimensions.toothThicknessAtPitch / 2 - dimensions.addendum * slope;
+    if (!(tipHalfWidth > 0) || !(rootHalfWidth < dimensions.pitch / 2)) {
+        throw new GeometryError("DEGENERATE_GEOMETRY", "The selected rack proportions cannot form separated trapezoidal teeth.", { operation: "sampleRackToothPath" });
+    }
+    const points = [Object.freeze([0, -dimensions.dedendum])];
+    for (let tooth = 0; tooth < dimensions.toothCount; tooth += 1) {
+        const center = (tooth + 0.5) * dimensions.pitch;
+        points.push(Object.freeze([center - rootHalfWidth, -dimensions.dedendum]), Object.freeze([center - tipHalfWidth, dimensions.addendum]), Object.freeze([center + tipHalfWidth, dimensions.addendum]), Object.freeze([center + rootHalfWidth, -dimensions.dedendum]));
+    }
+    points.push(Object.freeze([dimensions.length, -dimensions.dedendum]));
+    return freezePoints(points);
+}

package/dist/geometry/mechanical/index.js

@@ -0,0 +1,13 @@
+/**
+ * Runtime-neutral, opt-in mechanical geometry helpers and standards data.
+ *
+ * @packageDocumentation
+ */
+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 { 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";

package/dist/geometry/mechanical/standards.js

@@ -0,0 +1,67 @@
+import { GeometryError } from "../errors.js";
+const standard = (nominalDiameter, coarsePitch, clearanceHoles, hexNut, socketCapHead) => Object.freeze({
+    coarsePitch,
+    clearanceHoles: Object.freeze({
+        close: clearanceHoles[0],
+        loose: clearanceHoles[2],
+        normal: clearanceHoles[1],
+    }),
+    hexNut: Object.freeze({ acrossFlats: hexNut[0], thickness: hexNut[1] }),
+    nominalDiameter,
+    socketCapHead: Object.freeze({
+        diameter: socketCapHead[0],
+        height: socketCapHead[1],
+        hexKey: socketCapHead[2],
+    }),
+});
+/**
+ * Curated metric modeling dimensions for clearance holes, regular hex nuts,
+ * and socket-head cap screws.
+ *
+ * Values are nominal reference dimensions intended for parametric envelopes.
+ * Manufacturing tolerances, coatings, and printer compensation remain caller
+ * responsibilities.
+ */
+export const METRIC_FASTENER_STANDARDS = Object.freeze({
+    /** Nominal M2 coarse-thread modeling dimensions. */
+    M2: standard(2, 0.4, [2.2, 2.4, 2.6], [4, 1.6], [3.8, 2, 1.5]),
+    /** Nominal M2.5 coarse-thread modeling dimensions. */
+    "M2.5": standard(2.5, 0.45, [2.7, 2.9, 3.1], [5, 2], [4.5, 2.5, 2]),
+    /** Nominal M3 coarse-thread modeling dimensions. */
+    M3: standard(3, 0.5, [3.2, 3.4, 3.6], [5.5, 2.4], [5.5, 3, 2.5]),
+    /** Nominal M4 coarse-thread modeling dimensions. */
+    M4: standard(4, 0.7, [4.3, 4.5, 4.8], [7, 3.2], [7, 4, 3]),
+    /** Nominal M5 coarse-thread modeling dimensions. */
+    M5: standard(5, 0.8, [5.3, 5.5, 5.8], [8, 4], [8.5, 5, 4]),
+    /** Nominal M6 coarse-thread modeling dimensions. */
+    M6: standard(6, 1, [6.4, 6.6, 7], [10, 5], [10, 6, 5]),
+    /** Nominal M8 coarse-thread modeling dimensions. */
+    M8: standard(8, 1.25, [8.4, 9, 10], [13, 6.5], [13, 8, 6]),
+    /** Nominal M10 coarse-thread modeling dimensions. */
+    M10: standard(10, 1.5, [10.5, 11, 12], [17, 8], [16, 10, 8]),
+    /** Nominal M12 coarse-thread modeling dimensions. */
+    M12: standard(12, 1.75, [13, 13.5, 14.5], [19, 10], [18, 12, 10]),
+});
+/** Returns the immutable standards record for one supported metric size. */
+export function getMetricFastenerStandard(size) {
+    const value = METRIC_FASTENER_STANDARDS[size];
+    if (value === undefined) {
+        throw new GeometryError("INVALID_ARGUMENT", `Unsupported metric fastener size: ${size}.`);
+    }
+    return value;
+}
+/** Returns one recommended metric clearance-hole diameter in millimetres. */
+export function getMetricClearanceHole(size, fit = "normal") {
+    const holes = getMetricFastenerStandard(size).clearanceHoles;
+    const diameter = fit === "close"
+        ? holes.close
+        : fit === "normal"
+            ? holes.normal
+            : fit === "loose"
+                ? holes.loose
+                : undefined;
+    if (diameter === undefined) {
+        throw new GeometryError("INVALID_ARGUMENT", `Unsupported clearance-hole fit: ${fit}.`);
+    }
+    return diameter;
+}

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

@@ -0,0 +1,44 @@
+/** Conventional thread helix sampling, independent of surface construction. */
+import { GeometryError } from "../errors.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling-limits.js";
+import { assertFiniteThreadNumber } from "./thread-profiles.js";
+/**
+ * Samples evenly phased thread helices with finite `lead = pitch * starts`.
+ * All starts together respect maxPathPoints (default 100000); excessive counts fail before allocation.
+ */
+export function sampleConventionalThreadHelices(options) {
+    const operation = "sampleThreadHelices";
+    const radius = assertFiniteThreadNumber(options.radius, "radius", operation);
+    const length = assertFiniteThreadNumber(options.length, "length", operation);
+    const pitch = assertFiniteThreadNumber(options.pitch, "pitch", operation);
+    const starts = assertFiniteThreadNumber(options.starts ?? 1, "starts", operation);
+    const density = assertFiniteThreadNumber(options.segmentsPerTurn ?? 32, "segmentsPerTurn", operation);
+    if (!(radius > 0 && length > 0 && pitch > 0) ||
+        !Number.isInteger(starts) ||
+        starts < 1 ||
+        starts > 32 ||
+        !Number.isInteger(density) ||
+        density < 3) {
+        throw new GeometryError("INVALID_ARGUMENT", "Helix dimensions, starts, or density are invalid.", { operation });
+    }
+    const handedness = options.handedness ?? "right";
+    if (handedness !== "left" && handedness !== "right")
+        throw new GeometryError("INVALID_ARGUMENT", "Unsupported handedness.", { operation });
+    const lead = assertFiniteThreadNumber(pitch * starts, "lead", operation);
+    const turns = length / lead;
+    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 paths = Object.freeze(Array.from({ length: starts }, (_, start) => {
+        const initial = phase + (direction * 2 * Math.PI * start) / starts;
+        return Object.freeze(Array.from({ length: count + 1 }, (_, index) => {
+            const t = index / count;
+            const z = length * t;
+            const angle = initial + direction * 2 * Math.PI * turns * t;
+            return Object.freeze([radius * Math.cos(angle), radius * Math.sin(angle), z]);
+        }));
+    }));
+    return Object.freeze({ lead, paths, pitch, turns });
+}