@metamesh/modeling 0.0.0-bootstrap.0 → 0.6.0

package/dist/geometry/loft-geometry.js

@@ -0,0 +1,184 @@
+import { GeometryError } from "./errors.js";
+import { alignLoftRows, assertLoftGrid, loftSubdivisions, sliceLoftRows, subdivideLoftRow, } from "./loft-correspondence.js";
+import { loftFrame, resolveLoftControls } from "./loft-options.js";
+import { normalizeLoop2, normalizeRegion2, signedAreaLoop2 } from "./regions.js";
+import { resolveGeometryResolution } from "./resolution.js";
+import { assertSamplingCount } from "./sampling-limits.js";
+import { frameTransform3 } from "./transform3.js";
+const fail = (message) => {
+    throw new GeometryError("INVALID_ARGUMENT", message, { operation: "loft" });
+};
+const contours = (profile) => profile.components.flatMap((component) => [component.outer, ...component.holes]);
+/** @internal Counts and validates the explicit profile protocol before expanding its grids. */
+export function loftProfilePointCount(profile) {
+    const identity = (id) => typeof id === "string" && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(id) && id.length <= 64;
+    if (!Array.isArray(profile.components) ||
+        profile.components.length === 0 ||
+        profile.components.length > 1000)
+        fail("Loft profiles need one through 1000 identified components.");
+    const components = new Set();
+    let count = 0;
+    for (const component of profile.components) {
+        if (!identity(component.id) || components.has(component.id) || !Array.isArray(component.holes))
+            fail("Loft component identities must be canonical and unique.");
+        components.add(component.id);
+        const names = new Set();
+        for (const contour of [component.outer, ...component.holes]) {
+            if (!identity(contour.id) || names.has(contour.id))
+                fail("Loft contour identities must be canonical and unique within a component.");
+            names.add(contour.id);
+            if (!Array.isArray(contour.points) ||
+                !Array.isArray(contour.spans) ||
+                contour.points.length < 3 ||
+                contour.points.length !== contour.spans.length ||
+                contour.spans.some((span) => !identity(span)))
+                fail("Loft contours require at least three logical points and paired span identities.");
+            count += contour.points.length;
+        }
+    }
+    return count;
+}
+/** @internal Makes plain point data an indexed, single-component profile without inventing landmarks. */
+export function pointLoftProfile(points) {
+    return {
+        components: [
+            {
+                id: "component-0",
+                holes: [],
+                outer: { id: "outer", points, spans: points.map((_, index) => `point-${index}`) },
+            },
+        ],
+    };
+}
+/** @internal Validates winding while retaining repeated logical vertices and each input seam. */
+function checkedLoop(points, outer, authoritative, limits) {
+    if (!Array.isArray(points))
+        fail("Loft contours must be ordered point arrays.");
+    assertSamplingCount(points.length, "loft", limits.maxProfilePoints);
+    normalizeLoop2(points, outer);
+    const sameWinding = signedAreaLoop2(points) > 0 === outer;
+    if (!sameWinding && authoritative)
+        fail("Identified loft contours must retain outer CCW and hole CW winding.");
+    const copied = points.map((point) => [point[0], point[1]]);
+    if (!authoritative)
+        while (copied.length > 3 &&
+            copied[0][0] === copied.at(-1)[0] &&
+            copied[0][1] === copied.at(-1)[1])
+            copied.pop();
+    return sameWinding ? copied : [copied[0], ...copied.slice(1).reverse()];
+}
+/** @internal Resolves grids for native hole caps and pure simple-loop caps using the same controls. */
+export function prepareLoftGeometry(input, options, limits, authoritative, recipeSampled) {
+    if (!Array.isArray(input) || input.length < 2)
+        fail("Loft requires at least two stations.");
+    assertSamplingCount(input.length, "loft", limits.maxPathPoints);
+    const controls = resolveLoftControls(options, input.length);
+    assertSamplingCount(input.reduce((sum, station) => sum + loftProfilePointCount(station.profile), 0), "loft", 1_000_000);
+    if (authoritative && controls.methods.some((method) => method !== "direct"))
+        fail("Identified loft landmarks are authoritative and cannot be remapped by geometric correspondence methods.");
+    const finalRows = input.length + controls.slices.reduce((sum, count) => sum + count, 0);
+    assertSamplingCount(finalRows, "loft", limits.maxPathPoints);
+    const frames = input.map((station) => loftFrame(station));
+    const transforms = frames.map((frame) => frameTransform3(frame));
+    const first = input[0].profile;
+    if (!Array.isArray(first.components) ||
+        first.components.length === 0 ||
+        first.components.length > 1000)
+        fail("Loft profiles need one through 1000 components.");
+    const lists = input.map((station) => {
+        const profile = station.profile;
+        if (!Array.isArray(profile.components) || profile.components.length !== first.components.length)
+            fail("Loft component topology cannot change between stations.");
+        profile.components.forEach((component, index) => {
+            const expected = first.components[index];
+            if (component.id !== expected.id ||
+                !Array.isArray(component.holes) ||
+                component.holes.length !== expected.holes.length)
+                fail("Loft component identities and hole counts must retain their input order.");
+        });
+        return contours(profile);
+    });
+    const reference = lists[0];
+    const allRows = [];
+    const allSpans = [];
+    const budget = { comparisons: 0 };
+    const resolution = resolveGeometryResolution(options.resolution, limits);
+    const maxLengths = input.map((_, index) => recipeSampled?.[index] === true ? undefined : resolution.maxSegmentLength);
+    // Validate every original station's filled topology, including middle stations.
+    // Inserted world grids may have no useful local plane and are checked by mesh topology.
+    input.forEach((station) => normalizeRegion2(station.profile.components.map((component) => ({
+        outer: component.outer.points,
+        holes: component.holes.map((hole) => hole.points),
+    }))));
+    let otherContours = 0;
+    reference.forEach((expected, contourIndex) => {
+        const outer = first.components.some((component) => component.outer === expected);
+        const rows = lists.map((list, stationIndex) => {
+            const contour = list[contourIndex];
+            if (contour.id !== expected.id)
+                fail("Loft contour identities must retain their input order.");
+            if (authoritative &&
+                (contour.points.length !== expected.points.length ||
+                    contour.spans.length !== expected.spans.length ||
+                    contour.spans.some((span, index) => span !== expected.spans[index])))
+                fail("Identified loft contours must preserve every paired landmark and logical slot.");
+            const points = checkedLoop(contour.points, outer, authoritative, limits), matrix = transforms[stationIndex];
+            const world = points.map(([x, y]) => {
+                const point = [
+                    matrix[0] * x + matrix[1] * y + matrix[3],
+                    matrix[4] * x + matrix[5] * y + matrix[7],
+                    matrix[8] * x + matrix[9] * y + matrix[11],
+                ];
+                if (!point.every((coordinate) => Number.isFinite(Math.fround(coordinate))))
+                    throw new GeometryError("NON_FINITE_VALUE", "Loft world positions must fit finite Float32 storage.", { operation: "loft" });
+                return point;
+            });
+            return { points, world };
+        });
+        let aligned, spans;
+        if (authoritative) {
+            const demands = rows.map((row, index) => loftSubdivisions(row, row.points.length * controls.refine[index], controls.distribution, maxLengths[index]));
+            const counts = expected.points.map((_, index) => Math.max(...demands.map((demand) => demand[index])));
+            const count = counts.reduce((sum, count) => sum + count, 0);
+            assertLoftGrid(count, finalRows, otherContours, limits);
+            aligned = rows.map((row) => subdivideLoftRow(row, counts));
+            spans = counts.flatMap((count, index) => Array(count).fill(expected.spans[index]));
+        }
+        else {
+            aligned = alignLoftRows(rows, controls.methods, controls.distribution, controls.refine, finalRows, otherContours, limits, budget, maxLengths);
+            spans = aligned[0].points.map((_, index) => `point-${index}`);
+        }
+        otherContours += aligned[0].points.length;
+        allRows.push(sliceLoftRows(aligned, controls.slices));
+        allSpans.push(spans);
+    });
+    const templates = first.components;
+    const stationFrames = [frames[0]];
+    for (let gap = 0; gap < controls.slices.length; gap++) {
+        // Intermediate frames are placeholders only. Their vertices use the explicit world grids.
+        for (let index = 0; index < controls.slices[gap]; index++)
+            stationFrames.push(frames[gap]);
+        stationFrames.push(frames[gap + 1]);
+    }
+    const stations = stationFrames.map((frame, row) => {
+        let contourIndex = 0;
+        const convert = (contour) => {
+            const index = contourIndex++;
+            return { ...contour, points: allRows[index][row].points, spans: allSpans[index] };
+        };
+        return {
+            frame,
+            profile: {
+                components: templates.map((component) => ({
+                    ...component,
+                    outer: convert(component.outer),
+                    holes: component.holes.map(convert),
+                })),
+            },
+        };
+    });
+    return {
+        stations,
+        world: stationFrames.map((_, row) => allRows.map((contour) => contour[row].world)),
+    };
+}

package/dist/geometry/loft-options.js

@@ -0,0 +1,56 @@
+import { GeometryError } from "./errors.js";
+import { frameTransform3 } from "./transform3.js";
+/** @internal Resolves placement without sorting stations or interpolating their axes. */
+export function loftFrame(placement, operation = "loft") {
+    if (typeof placement !== "object" ||
+        placement === null ||
+        Array.isArray(placement) ||
+        "z" in placement === "frame" in placement)
+        throw new GeometryError("INVALID_ARGUMENT", "Each loft station must specify exactly one z or frame.", { operation });
+    if ("z" in placement) {
+        if (!Number.isFinite(placement.z))
+            throw new GeometryError("NON_FINITE_VALUE", "Loft station z must be finite millimetres.", {
+                operation,
+            });
+        return { origin: [0, 0, placement.z], xAxis: [1, 0, 0], yAxis: [0, 1, 0], zAxis: [0, 0, 1] };
+    }
+    frameTransform3(placement.frame);
+    return placement.frame;
+}
+/** @internal Validated controls shared by every loft construction route. */
+export function resolveLoftControls(options, stationCount) {
+    if (typeof options !== "object" || options === null || Array.isArray(options))
+        throw new GeometryError("INVALID_ARGUMENT", "Loft options must be an object.", {
+            operation: "loft",
+        });
+    const expand = (value, count, fallback, label) => {
+        if (Array.isArray(value)) {
+            if (value.length !== count)
+                fail(`${label} requires exactly ${count} entries in station order.`);
+            return value;
+        }
+        return Array(count).fill(value === undefined ? fallback : value);
+    };
+    const methods = expand(options.correspondence, stationCount - 1, "direct", "correspondence");
+    for (const method of methods)
+        if (!["direct", "reindex", "fast-distance", "distance"].includes(method))
+            fail("Unsupported loft correspondence method.");
+    const duplicate = methods.some((method) => method === "distance" || method === "fast-distance");
+    const distribution = options.distribution ?? (duplicate ? "segments" : "perimeter");
+    if (distribution !== "perimeter" && distribution !== "segments")
+        fail("Loft distribution must be perimeter or segments.");
+    if (duplicate && distribution !== "segments")
+        fail("Vertex-duplication correspondence requires segments distribution.");
+    const refine = expand(options.refine, stationCount, 1, "refine");
+    const slices = expand(options.slices, stationCount - 1, 0, "slices");
+    for (const count of refine)
+        if (!Number.isSafeInteger(count) || count < 1)
+            fail("Loft refine values must be positive safe integers.");
+    for (const count of slices)
+        if (!Number.isSafeInteger(count) || count < 0)
+            fail("Loft slices values must be nonnegative safe integers.");
+    return { methods, distribution, refine, slices };
+}
+const fail = (message) => {
+    throw new GeometryError("INVALID_ARGUMENT", message, { operation: "loft" });
+};

package/dist/geometry/loft-simple-mesh.js

@@ -0,0 +1,92 @@
+import { GeometryError } from "./errors.js";
+import { triangulateLoop2 } from "./loft-triangulation.js";
+import { measureTriangleMesh, validateTriangleMesh } from "./mesh.js";
+import { assertMeshAllocationWithinLimits, } from "./model-limits.js";
+import { writeMeshVertex } from "./numeric.js";
+/** @internal Pure closed simple-contour strips, retaining repeated correspondence slots as shared physical vertices. */
+export function simpleLoftMesh(geometry, limits, allocationGuard) {
+    const count = geometry.world[0][0].length, rowCount = geometry.world.length;
+    const maximumVertices = count * rowCount, maximumTriangles = 2 * count * (rowCount - 1) + 2 * (count - 2);
+    const bytes = 12 * (maximumVertices + maximumTriangles);
+    assertMeshAllocationWithinLimits(maximumVertices, maximumTriangles, bytes, "loftMesh", limits);
+    allocationGuard?.(maximumVertices, maximumTriangles, bytes, "loftMesh");
+    const positions = new Float32Array(maximumVertices * 3), indices = new Uint32Array(maximumTriangles * 3);
+    let vertexCount = 0, cursor = 0;
+    const rows = geometry.world.map((contours, row) => {
+        const points = [], vertices = [], slots = [];
+        contours[0].forEach((point, slot) => {
+            const coordinates = point.map(Math.fround), previous = vertices.at(-1);
+            if (previous !== undefined &&
+                coordinates.every((coordinate, axis) => coordinate === positions[previous * 3 + axis]))
+                slots.push(previous);
+            else {
+                writeMeshVertex(positions, vertexCount * 3, point, "loftMesh");
+                slots.push(vertexCount);
+                vertices.push(vertexCount++);
+                points.push(geometry.stations[row].profile.components[0].outer.points[slot]);
+            }
+        });
+        const start = vertices[0], end = vertices.at(-1);
+        if (start !== end &&
+            [0, 1, 2].every((axis) => positions[start * 3 + axis] === positions[end * 3 + axis])) {
+            slots.forEach((slot, index) => {
+                if (slot === end)
+                    slots[index] = start;
+            });
+            vertices.pop();
+            points.pop();
+            vertexCount--;
+        }
+        if (vertices.length < 3)
+            throw new GeometryError("INVALID_TOPOLOGY", "Loft contours cannot collapse their filled topology.", { operation: "loftMesh" });
+        return { points, vertices, slots };
+    });
+    const triangle = (a, b, c) => {
+        if (a === b || b === c || c === a)
+            return;
+        const ab = [
+            positions[b * 3] - positions[a * 3],
+            positions[b * 3 + 1] - positions[a * 3 + 1],
+            positions[b * 3 + 2] - positions[a * 3 + 2],
+        ];
+        const ac = [
+            positions[c * 3] - positions[a * 3],
+            positions[c * 3 + 1] - positions[a * 3 + 1],
+            positions[c * 3 + 2] - positions[a * 3 + 2],
+        ];
+        if (ab[1] * ac[2] - ab[2] * ac[1] === 0 &&
+            ab[2] * ac[0] - ab[0] * ac[2] === 0 &&
+            ab[0] * ac[1] - ab[1] * ac[0] === 0)
+            return;
+        indices[cursor++] = a;
+        indices[cursor++] = b;
+        indices[cursor++] = c;
+    };
+    for (let row = 0; row < rows.length - 1; row++)
+        for (let index = 0; index < count; index++) {
+            const next = (index + 1) % count, a = rows[row], b = rows[row + 1];
+            triangle(a.slots[index], a.slots[next], b.slots[next]);
+            triangle(a.slots[index], b.slots[next], b.slots[index]);
+        }
+    const cap = (row, top) => {
+        const contour = rows[row], triangles = triangulateLoop2(contour.points);
+        for (let index = 0; index < triangles.length; index += 3)
+            triangle(contour.vertices[triangles[index]], contour.vertices[triangles[index + (top ? 1 : 2)]], contour.vertices[triangles[index + (top ? 2 : 1)]]);
+    };
+    cap(0, false);
+    cap(rows.length - 1, true);
+    const mesh = {
+        positions: positions.slice(0, vertexCount * 3),
+        indices: indices.slice(0, cursor),
+    };
+    const volume = measureTriangleMesh(mesh).signedVolume;
+    if (volume === 0)
+        throw new GeometryError("DEGENERATE_GEOMETRY", "Loft stations collapse to zero enclosed volume.", { operation: "loftMesh" });
+    if (volume < 0)
+        for (let index = 0; index < mesh.indices.length; index += 3) {
+            const b = mesh.indices[index + 1];
+            mesh.indices[index + 1] = mesh.indices[index + 2];
+            mesh.indices[index + 2] = b;
+        }
+    return validateTriangleMesh(mesh, { requireClosed: true });
+}

package/dist/geometry/loft-triangulation.js

@@ -0,0 +1,64 @@
+import { GeometryError } from "./errors.js";
+import { normalizeLoop2 } from "./regions.js";
+const maximumComparisons = 8_000_000;
+const cross = (a, b, c) => (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0]);
+const pointInTriangle = (point, a, b, c, epsilon) => {
+    const ab = cross(a, b, point);
+    const bc = cross(b, c, point);
+    const ca = cross(c, a, point);
+    return ab >= -epsilon && bc >= -epsilon && ca >= -epsilon;
+};
+/** Ear-clips one normalized simple CCW loop into stable local vertex indices. */
+export function triangulateLoop2(loop) {
+    const normalized = normalizeLoop2(loop, true);
+    // Subdividing a straight edge introduces roundoff-sized turns. Treat them consistently
+    // in both ear convexity and containment so they cannot consume a false ear or block the cap.
+    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+    for (const [x, y] of normalized) {
+        minX = Math.min(minX, x);
+        minY = Math.min(minY, y);
+        maxX = Math.max(maxX, x);
+        maxY = Math.max(maxY, y);
+    }
+    const extent = Math.max(maxX - minX, maxY - minY);
+    const epsilon = extent * extent * Number.EPSILON * 32;
+    const remaining = normalized.map((_, index) => index);
+    const triangles = [];
+    let comparisons = 0;
+    const consume = () => {
+        if (++comparisons > maximumComparisons)
+            throw new GeometryError("COMPLEXITY_LIMIT", "Profile cap triangulation exceeds its eight-million-comparison work limit.", {
+                operation: "triangulateLoop2",
+                details: { requiredCount: comparisons, allowedCount: maximumComparisons },
+            });
+    };
+    while (remaining.length > 3) {
+        let clipped = false;
+        for (let offset = 0; offset < remaining.length; offset += 1) {
+            consume();
+            const previous = remaining[(offset - 1 + remaining.length) % remaining.length];
+            const current = remaining[offset];
+            const next = remaining[(offset + 1) % remaining.length];
+            if (cross(normalized[previous], normalized[current], normalized[next]) <= epsilon)
+                continue;
+            if (remaining.some((candidate) => {
+                consume();
+                return (candidate !== previous &&
+                    candidate !== current &&
+                    candidate !== next &&
+                    pointInTriangle(normalized[candidate], normalized[previous], normalized[current], normalized[next], epsilon));
+            })) {
+                continue;
+            }
+            triangles.push(previous, current, next);
+            remaining.splice(offset, 1);
+            clipped = true;
+            break;
+        }
+        if (!clipped) {
+            throw new GeometryError("INVALID_TOPOLOGY", "Profile cap triangulation could not find a valid ear.", { operation: "triangulateLoop2" });
+        }
+    }
+    triangles.push(remaining[0], remaining[1], remaining[2]);
+    return new Uint32Array(triangles);
+}

package/dist/geometry/loft.js

@@ -0,0 +1,80 @@
+import { GeometryError } from "./errors.js";
+import { resolveExtrusionControls, resolveExtrusionDivisions, } from "./extrusion.js";
+import { pointLoftProfile, prepareLoftGeometry } from "./loft-geometry.js";
+import {} from "./loft-options.js";
+import { simpleLoftMesh } from "./loft-simple-mesh.js";
+import { assertMeshAllocationWithinLimits, resolveModelingLimits, } from "./model-limits.js";
+import { assertSamplingCount } from "./sampling-limits.js";
+export { triangulateLoop2 } from "./loft-triangulation.js";
+/**
+ * Lofts simple point loops at z heights or explicit right-handed frames, in input order.
+ *
+ * An explicit correspondence method is required. CCW-normalized loops retain their
+ * seam and original vertices; unequal counts gain subdivisions or repeated fan slots.
+ * Both ends use ear-clipped caps, supporting concave profiles without center fans.
+ * Intermediate slices interpolate placed world vertices, never frame axes.
+ * Transformed coordinates must fit finite Float32 mesh storage.
+ */
+export function loftMesh(stations, options) {
+    return buildLoftMesh(stations, options);
+}
+/** @internal Shared pure loft with host allocation preflight. */
+export function buildLoftMesh(stations, options, allocationGuard) {
+    if (options?.correspondence === undefined)
+        throw new GeometryError("INVALID_ARGUMENT", "Point-loop lofts require an explicit correspondence method.", { operation: "loftMesh" });
+    const limits = resolveModelingLimits(options.limits);
+    if (!Array.isArray(stations) || stations.length < 2)
+        throw new GeometryError("INVALID_ARGUMENT", "Loft requires at least two stations.", {
+            operation: "loftMesh",
+        });
+    const input = stations;
+    assertSamplingCount(input.length, "loftMesh", limits.maxPathPoints);
+    assertSamplingCount(input.reduce((sum, station) => {
+        if (!Array.isArray(station.profile))
+            throw new GeometryError("INVALID_ARGUMENT", "Pure loft profiles must be ordered point arrays.", { operation: "loftMesh" });
+        return sum + station.profile.length;
+    }, 0), "loftMesh", 1_000_000);
+    const profiles = input.map((station) => ({
+        ...station,
+        profile: pointLoftProfile(station.profile),
+    }));
+    return simpleLoftMesh(prepareLoftGeometry(profiles, options, limits, false), limits, allocationGuard);
+}
+/** Linearly extrudes one simple profile along +Z with robust ear-clipped caps. */
+export function extrudeMesh(profile, options) {
+    const { height } = options;
+    const { center, scales, twistDegrees } = resolveExtrusionControls(height, options, "extrudeMesh");
+    if (!Number.isFinite(height) || height <= 0) {
+        throw new GeometryError("INVALID_ARGUMENT", "Extrusion height must be finite and positive.", {
+            operation: "extrudeMesh",
+            details: { height },
+        });
+    }
+    const bottom = center ? -height / 2 : 0;
+    const limits = resolveModelingLimits(options.limits);
+    assertSamplingCount(profile.length, "extrudeMesh", limits.maxProfilePoints);
+    const divisions = resolveExtrusionDivisions(profile, height, options);
+    const count = profile.length * (divisions + 2);
+    const triangles = (divisions + 1) * profile.length * 2 + (profile.length - 2) * 2;
+    assertMeshAllocationWithinLimits(count, triangles, (count + triangles) * 12, "extrudeMesh", limits);
+    const frame = (amount) => ({
+        origin: [0, 0, bottom + height * amount],
+        xAxis: [1, 0, 0],
+        yAxis: [0, 1, 0],
+        zAxis: [0, 0, 1],
+    });
+    const stations = Array.from({ length: divisions + 2 }, (_, index) => {
+        const amount = index / (divisions + 1);
+        const angle = ((twistDegrees * Math.PI) / 180) * amount;
+        const cosine = Math.cos(angle), sine = Math.sin(angle);
+        const sx = 1 + (scales[0] - 1) * amount, sy = 1 + (scales[1] - 1) * amount;
+        return {
+            frame: frame(amount),
+            profile: profile.map(([x, y]) => [
+                x * sx * cosine - y * sy * sine,
+                x * sx * sine + y * sy * cosine,
+            ]),
+        };
+    });
+    return loftMesh(stations, { correspondence: "direct", limits });
+}

package/dist/geometry/math/vector3.js

@@ -0,0 +1,41 @@
+/** Adds two finite XYZ vectors component-wise. @example `add3([1, 2, 3], [4, 5, 6])` */
+export const add3 = (a, b) => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+/** Subtracts `b` from `a`. @example `subtract3([4, 5, 6], [1, 2, 3])` */
+export const subtract3 = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+/** Multiplies a vector by a dimensionless scalar. @example `scale3([1, 2, 3], 2)` */
+export const scale3 = (vector, scale) => [
+    vector[0] * scale,
+    vector[1] * scale,
+    vector[2] * scale,
+];
+/** Returns the scalar dot product. @example `dot3([1, 0, 0], [0, 1, 0])` */
+export const dot3 = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+/** Returns the right-handed cross product. @example `cross3([1, 0, 0], [0, 1, 0])` */
+export const cross3 = (a, b) => [
+    a[1] * b[2] - a[2] * b[1],
+    a[2] * b[0] - a[0] * b[2],
+    a[0] * b[1] - a[1] * b[0],
+];
+/** 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`. */
+export const normalize3 = (vector, epsilon = 1e-12) => {
+    const length = length3(vector);
+    if (!Number.isFinite(length)) {
+        throw new Error("Cannot normalize a vector without finite length.");
+    }
+    if (length <= epsilon) {
+        throw new Error("Cannot normalize a zero-length vector.");
+    }
+    return scale3(vector, 1 / 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) => {
+    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

@@ -0,0 +1,94 @@
+import { GeometryError } from "../errors.js";
+import { polygonClipping } from "../polygon-clipping.js";
+import { resolveCylindricalGearPair, sampleCylindricalGearOutline, sampleInternalCylindricalGearSpaceOutline, } from "./gears.js";
+const DEFAULT_MOTION_SAMPLES = 24;
+const MAXIMUM_MOTION_SAMPLES = 360;
+const transformedLoop = (loop, angle, translationX = 0) => {
+    const cosine = Math.cos(angle);
+    const sine = Math.sin(angle);
+    return Object.freeze(loop.map(([x, y]) => Object.freeze([x * cosine - y * sine + translationX, x * sine + y * cosine])));
+};
+const clippingPolygon = (loop) => [
+    [...loop.map(([x, y]) => [x, y]), [...loop[0]]],
+];
+const contactWindowPolygon = (centerDistance, driverOutsideRadius, ringTipRadius) => {
+    // The internal-space loop contains the complete disk inside the ring tooth tips. A driver point
+    // can therefore overlap ring material only when its distance from the ring center is at least
+    // ringTipRadius. Since |y| cannot exceed the driver's outside radius, every possible overlap is
+    // conservatively confined to this left-hand X slab. Cropping both periodic outlines before the
+    // expensive difference keeps interactive validation proportional to the contact zone rather
+    // than to both complete high-tooth-count polygons.
+    const radialMargin = Math.max(1, driverOutsideRadius, ringTipRadius) * 1e-10;
+    const squaredHorizontalReach = ringTipRadius ** 2 - driverOutsideRadius ** 2;
+    const maximumX = Math.min(driverOutsideRadius, squaredHorizontalReach > 0
+        ? centerDistance - Math.sqrt(squaredHorizontalReach) + radialMargin
+        : driverOutsideRadius);
+    const minimumX = -driverOutsideRadius - radialMargin;
+    const minimumY = -driverOutsideRadius - radialMargin;
+    const maximumY = driverOutsideRadius + radialMargin;
+    return [
+        [
+            [minimumX, minimumY],
+            [maximumX, minimumY],
+            [maximumX, maximumY],
+            [minimumX, maximumY],
+            [minimumX, minimumY],
+        ],
+    ];
+};
+const ringArea = (ring) => {
+    let doubled = 0;
+    for (let index = 0; index + 1 < ring.length; index += 1) {
+        const current = ring[index];
+        const next = ring[index + 1];
+        doubled += current[0] * next[1] - next[0] * current[1];
+    }
+    return doubled / 2;
+};
+const multiPolygonArea = (multiPolygon) => multiPolygon.reduce((total, polygon) => total +
+    polygon.reduce((area, ring, index) => area + (index === 0 ? Math.abs(ringArea(ring)) : -Math.abs(ringArea(ring))), 0), 0);
+/**
+ * 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
+ * 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.
+ */
+export function measureInternalCylindricalGearPairMotion(spec, options = {}) {
+    if (spec.mesh !== "internal") {
+        throw new GeometryError("INVALID_ARGUMENT", "Motion analysis requires an internal gear pair.", {
+            operation: "measureInternalCylindricalGearPairMotion",
+        });
+    }
+    const samples = options.samples ?? DEFAULT_MOTION_SAMPLES;
+    if (!Number.isInteger(samples) || samples < 4 || samples > MAXIMUM_MOTION_SAMPLES) {
+        throw new GeometryError("INVALID_ARGUMENT", `Motion samples must be an integer from 4 through ${MAXIMUM_MOTION_SAMPLES}.`, { operation: "measureInternalCylindricalGearPairMotion", details: { samples } });
+    }
+    const pair = resolveCylindricalGearPair(spec);
+    const driver = sampleCylindricalGearOutline(spec.driver, options.outline);
+    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;
+    let maximumOverlapArea = 0;
+    let maximumPhase = 0;
+    for (let sample = 0; sample < samples; sample += 1) {
+        const driverPhase = (pair.driver.angularPitch * sample) / samples;
+        const drivenPhase = initialRingPhase + driverPhase / pair.ratio;
+        const posedDriver = clippingPolygon(transformedLoop(driver, driverPhase));
+        const posedSpace = clippingPolygon(transformedLoop(ringSpace, drivenPhase, pair.centerDistance));
+        const contactDriver = polygonClipping.intersection(posedDriver, contactWindow);
+        const contactSpace = polygonClipping.intersection(posedSpace, contactWindow);
+        const overlapArea = multiPolygonArea(polygonClipping.difference(contactDriver, contactSpace));
+        if (overlapArea > maximumOverlapArea) {
+            maximumOverlapArea = overlapArea;
+            maximumPhase = driverPhase;
+        }
+    }
+    return Object.freeze({
+        driverPhaseRadians: maximumPhase,
+        maximumOverlapArea,
+        samples,
+    });
+}