@metamesh/modeling 0.0.0-bootstrap.0 → 0.6.0

package/dist/geometry/mesh-planar.js

@@ -0,0 +1,408 @@
+import { GeometryError } from "./errors.js";
+import { buildTriangleMeshQualityAnalysis, } from "./mesh-quality.js";
+const DEFAULT_MAXIMUM_FLIP_ATTEMPTS = 1_000_000;
+const DEFAULT_MAXIMUM_PATCH_TRIANGLE_COUNT = 50_000;
+const DEFAULT_MAXIMUM_PROCESSED_TRIANGLE_COUNT = 200_000;
+const DEFAULT_MAXIMUM_EDGE_REVISITS = 12;
+const DEFAULT_MINIMUM_PATCH_TRIANGLE_COUNT = 8;
+const DEFAULT_TRIGGER_MINIMUM_ANGLE_DEGREES = 8;
+const DEFAULT_TRIGGER_MAXIMUM_ASPECT_RATIO = 12;
+const DEFAULT_TRIGGER_MAXIMUM_VERTEX_TRIANGLE_INCIDENCE = 16;
+const DEFAULT_TRIGGER_MAXIMUM_FAN_RATIO = 0.2;
+const ATTEMPTS_PER_INITIAL_EDGE = 20;
+const edgeKey = (first, second) => first < second ? `${first}:${second}` : `${second}:${first}`;
+const pointAt = (positions, vertex) => [
+    positions[vertex * 3],
+    positions[vertex * 3 + 1],
+    positions[vertex * 3 + 2],
+];
+const subtract = (left, right) => [
+    left[0] - right[0],
+    left[1] - right[1],
+    left[2] - right[2],
+];
+const dot = (left, right) => left[0] * right[0] + left[1] * right[1] + left[2] * right[2];
+const cross = (left, right) => [
+    left[1] * right[2] - left[2] * right[1],
+    left[2] * right[0] - left[0] * right[2],
+    left[0] * right[1] - left[1] * right[0],
+];
+const squaredLength = (vector) => dot(vector, vector);
+const positiveInteger = (value, label) => {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new GeometryError("INVALID_ARGUMENT", `${label} must be a positive safe integer.`);
+    }
+    return value;
+};
+const positiveFinite = (value, label) => {
+    if (!Number.isFinite(value) || !(value > 0)) {
+        throw new GeometryError("INVALID_ARGUMENT", `${label} must be finite and greater than zero.`);
+    }
+    return value;
+};
+const resolveOptions = (options) => {
+    const triggerMaximumFanRatio = options.triggerMaximumFanRatio ?? DEFAULT_TRIGGER_MAXIMUM_FAN_RATIO;
+    if (!Number.isFinite(triggerMaximumFanRatio) ||
+        triggerMaximumFanRatio < 0 ||
+        triggerMaximumFanRatio > 1) {
+        throw new GeometryError("INVALID_ARGUMENT", "Maximum fan ratio trigger must be finite and between zero and one.");
+    }
+    const triggerMinimumAngleDegrees = positiveFinite(options.triggerMinimumAngleDegrees ?? DEFAULT_TRIGGER_MINIMUM_ANGLE_DEGREES, "Minimum angle trigger");
+    if (triggerMinimumAngleDegrees >= 180) {
+        throw new GeometryError("INVALID_ARGUMENT", "Minimum angle trigger must be below 180 degrees.");
+    }
+    return {
+        maximumEdgeRevisits: positiveInteger(options.maximumEdgeRevisits ?? DEFAULT_MAXIMUM_EDGE_REVISITS, "Maximum edge revisits"),
+        maximumFlipAttempts: options.maximumFlipAttempts === undefined
+            ? undefined
+            : positiveInteger(options.maximumFlipAttempts, "Maximum flip attempts"),
+        maximumPatchTriangleCount: positiveInteger(options.maximumPatchTriangleCount ?? DEFAULT_MAXIMUM_PATCH_TRIANGLE_COUNT, "Maximum patch triangle count"),
+        maximumProcessedTriangleCount: positiveInteger(options.maximumProcessedTriangleCount ?? DEFAULT_MAXIMUM_PROCESSED_TRIANGLE_COUNT, "Maximum processed triangle count"),
+        minimumPatchTriangleCount: positiveInteger(options.minimumPatchTriangleCount ?? DEFAULT_MINIMUM_PATCH_TRIANGLE_COUNT, "Minimum patch triangle count"),
+        triggerMaximumAspectRatio: positiveFinite(options.triggerMaximumAspectRatio ?? DEFAULT_TRIGGER_MAXIMUM_ASPECT_RATIO, "Maximum aspect-ratio trigger"),
+        triggerMaximumFanRatio,
+        triggerMaximumVertexTriangleIncidence: positiveInteger(options.triggerMaximumVertexTriangleIncidence ??
+            DEFAULT_TRIGGER_MAXIMUM_VERTEX_TRIANGLE_INCIDENCE, "Maximum vertex triangle-incidence trigger"),
+        triggerMinimumAngleDegrees,
+    };
+};
+const pairQuality = (positions, first, second) => {
+    const angles = [];
+    let maximumAspectRatio = 0;
+    for (const triangle of [first, second]) {
+        const points = triangle.map((vertex) => pointAt(positions, vertex));
+        const edgeVectors = [
+            subtract(points[1], points[0]),
+            subtract(points[2], points[1]),
+            subtract(points[0], points[2]),
+        ];
+        const edgeSquaredLengths = edgeVectors.map(squaredLength);
+        const doubleArea = Math.sqrt(squaredLength(cross(edgeVectors[0], subtract(points[2], points[0]))));
+        maximumAspectRatio = Math.max(maximumAspectRatio, doubleArea === 0
+            ? Number.POSITIVE_INFINITY
+            : (Math.sqrt(3) * Math.max(...edgeSquaredLengths)) / (2 * doubleArea));
+        for (let corner = 0; corner < 3; corner += 1) {
+            const origin = points[corner];
+            const incoming = subtract(points[(corner + 1) % 3], origin);
+            const outgoing = subtract(points[(corner + 2) % 3], origin);
+            angles.push(Math.atan2(Math.sqrt(squaredLength(cross(incoming, outgoing))), dot(incoming, outgoing)));
+        }
+    }
+    angles.sort((left, right) => left - right);
+    return { angles, maximumAspectRatio };
+};
+const comparePairQuality = (before, after, angularTolerance) => {
+    for (let index = 0; index < before.angles.length; index += 1) {
+        const difference = after.angles[index] - before.angles[index];
+        if (difference > angularTolerance)
+            return 1;
+        if (difference < -angularTolerance)
+            return -1;
+    }
+    const aspectTolerance = Math.max(1, before.maximumAspectRatio) * 1e-12;
+    if (after.maximumAspectRatio < before.maximumAspectRatio - aspectTolerance)
+        return 1;
+    if (after.maximumAspectRatio > before.maximumAspectRatio + aspectTolerance)
+        return -1;
+    return 0;
+};
+const localConcentrationPotential = (vertices, incidence, valence, changes = new Map()) => {
+    let potential = 0;
+    for (const vertex of new Set(vertices)) {
+        const change = changes.get(vertex) ?? 0;
+        const nextIncidence = incidence[vertex] + change;
+        const nextValence = valence[vertex] + change;
+        potential += nextIncidence ** 2 + nextValence ** 2;
+    }
+    return potential;
+};
+const isTriggeredPatch = (patch, options) => {
+    const report = patch.report;
+    return (report.triangleCount >= options.minimumPatchTriangleCount &&
+        (report.minimumTriangleAngleDegrees < options.triggerMinimumAngleDegrees ||
+            report.maximumTriangleAspectRatio > options.triggerMaximumAspectRatio ||
+            report.maximumVertexTriangleIncidence > options.triggerMaximumVertexTriangleIncidence ||
+            report.fanRatio > options.triggerMaximumFanRatio));
+};
+const unchangedResult = (mesh, report, skippedPatchCount, budgetExhausted, fallbackReason) => ({
+    after: report,
+    before: report,
+    budgetExhausted,
+    changed: false,
+    ...(fallbackReason === undefined ? {} : { fallbackReason }),
+    flipCount: 0,
+    mesh,
+    optimizedPatchCount: 0,
+    skippedPatchCount,
+});
+const boundsEqual = (first, second) => first.min.every((value, axis) => value === second.min[axis]) &&
+    first.max.every((value, axis) => value === second.max[axis]);
+const fallbackReasonForCandidate = (before, after, boundaryEdgeKeys) => {
+    if (!after.report.isClosedOrientedManifold)
+        return "candidate-not-closed-oriented-manifold";
+    for (const key of boundaryEdgeKeys) {
+        if (!after.edges.has(key))
+            return "candidate-boundary-changed";
+    }
+    const surfaceTolerance = Math.max(before.tolerance.area * before.report.triangleCount * 8, Math.abs(before.report.surfaceArea) * 1e-10);
+    const volumeTolerance = Math.max(before.tolerance.linear ** 3 * before.report.triangleCount * 8, Math.max(1, before.extent ** 3) * 1e-10);
+    if (!boundsEqual(before.bounds, after.bounds) ||
+        Math.abs(before.report.surfaceArea - after.report.surfaceArea) > surfaceTolerance ||
+        Math.abs(before.report.signedVolume - after.report.signedVolume) > volumeTolerance) {
+        return "candidate-measurements-changed";
+    }
+    const angleToleranceDegrees = (before.tolerance.angular * 180) / Math.PI;
+    const aspectTolerance = Math.max(1, before.report.maximumTriangleAspectRatio) * 1e-10;
+    if (after.report.minimumTriangleAngleDegrees <
+        before.report.minimumTriangleAngleDegrees - angleToleranceDegrees ||
+        after.report.maximumTriangleAspectRatio >
+            before.report.maximumTriangleAspectRatio + aspectTolerance) {
+        return "candidate-quality-regressed";
+    }
+    return undefined;
+};
+/**
+ * Improves pathological planar triangulation with bounded legal diagonal flips.
+ *
+ * The operation changes indices only: it never moves, adds, welds, or removes vertices; never
+ * crosses a coplanar-patch boundary; and never changes the face count. Each accepted flip improves
+ * a deterministic ordering of triangle angles, aspect ratio, diagonal locality, and local
+ * incidence/valence concentration. Unsupported input or a failed final integrity check returns the
+ * exact original mesh object. Malformed buffers and the configured analysis complexity limit throw.
+ *
+ * @param mesh - Closed, consistently wound indexed triangle mesh in arbitrary consistent units.
+ * @param options - Patch eligibility, numeric tolerance, and deterministic work bounds.
+ * @returns Optimized connectivity and before/after diagnostics, or an unchanged safe fallback.
+ */
+export function optimizePlanarPatches(mesh, options = {}) {
+    const resolved = resolveOptions(options);
+    const before = buildTriangleMeshQualityAnalysis(mesh, options);
+    if (!before.report.isClosedOrientedManifold) {
+        return unchangedResult(mesh, before.report, 0, false, "input-not-closed-oriented-manifold");
+    }
+    const selectedPatchIds = new Set();
+    const boundaryEdgeKeys = new Set();
+    let selectedTriangleCount = 0;
+    let skippedPatchCount = 0;
+    let budgetExhausted = false;
+    for (const patch of before.patches) {
+        if (!isTriggeredPatch(patch, resolved))
+            continue;
+        if (patch.report.triangleCount > resolved.maximumPatchTriangleCount ||
+            selectedTriangleCount + patch.report.triangleCount > resolved.maximumProcessedTriangleCount) {
+            skippedPatchCount += 1;
+            budgetExhausted = true;
+            continue;
+        }
+        selectedPatchIds.add(patch.report.id);
+        selectedTriangleCount += patch.report.triangleCount;
+        for (const key of patch.boundaryEdgeKeys)
+            boundaryEdgeKeys.add(key);
+    }
+    if (selectedPatchIds.size === 0) {
+        return unchangedResult(mesh, before.report, skippedPatchCount, budgetExhausted);
+    }
+    const triangles = before.faces.map(({ vertices }) => [...vertices]);
+    const edges = new Map();
+    const vertexEdges = Array.from({ length: before.report.vertexCount }, () => new Set());
+    for (const edge of before.edges.values()) {
+        const mutable = { ...edge, uses: edge.uses.map((use) => ({ ...use })) };
+        edges.set(edge.key, mutable);
+        vertexEdges[edge.first].add(edge.key);
+        vertexEdges[edge.second].add(edge.key);
+    }
+    const incidence = new Uint32Array(before.vertexTriangleIncidence);
+    const valence = new Uint32Array(before.vertexValence);
+    const isCandidateEdge = (edge) => {
+        if (edge.uses.length !== 2 || boundaryEdgeKeys.has(edge.key))
+            return false;
+        const firstPatch = before.patchByFace[edge.uses[0].face];
+        return (firstPatch >= 0 &&
+            firstPatch === before.patchByFace[edge.uses[1].face] &&
+            selectedPatchIds.has(firstPatch));
+    };
+    const initialEdges = [...edges.values()]
+        .filter(isCandidateEdge)
+        .sort((left, right) => left.first - right.first || left.second - right.second);
+    const maximumFlipAttempts = resolved.maximumFlipAttempts ??
+        Math.min(DEFAULT_MAXIMUM_FLIP_ATTEMPTS, initialEdges.length * ATTEMPTS_PER_INITIAL_EDGE);
+    if (maximumFlipAttempts === 0) {
+        return unchangedResult(mesh, before.report, skippedPatchCount, budgetExhausted);
+    }
+    const queue = initialEdges.map(({ key }) => key);
+    const queued = new Set(queue);
+    const revisitCounts = new Map();
+    const changedPatchIds = new Set();
+    let queueOffset = 0;
+    let attemptCount = 0;
+    let flipCount = 0;
+    const removeFace = (faceIndex, triangle) => {
+        for (let localEdge = 0; localEdge < 3; localEdge += 1) {
+            const key = edgeKey(triangle[localEdge], triangle[(localEdge + 1) % 3]);
+            const edge = edges.get(key);
+            const useIndex = edge.uses.findIndex(({ face }) => face === faceIndex);
+            edge.uses.splice(useIndex, 1);
+            if (edge.uses.length === 0) {
+                edges.delete(key);
+                vertexEdges[edge.first].delete(key);
+                vertexEdges[edge.second].delete(key);
+            }
+        }
+    };
+    const addFace = (faceIndex, triangle) => {
+        for (let localEdge = 0; localEdge < 3; localEdge += 1) {
+            const start = triangle[localEdge];
+            const end = triangle[(localEdge + 1) % 3];
+            const key = edgeKey(start, end);
+            let edge = edges.get(key);
+            if (edge === undefined) {
+                edge = {
+                    first: Math.min(start, end),
+                    key,
+                    second: Math.max(start, end),
+                    uses: [],
+                };
+                edges.set(key, edge);
+                vertexEdges[edge.first].add(key);
+                vertexEdges[edge.second].add(key);
+            }
+            edge.uses.push({ end, face: faceIndex, start });
+        }
+    };
+    const enqueueAround = (vertices) => {
+        const candidates = new Map();
+        for (const vertex of vertices) {
+            for (const key of vertexEdges[vertex]) {
+                const edge = edges.get(key);
+                if (edge !== undefined && isCandidateEdge(edge))
+                    candidates.set(key, edge);
+            }
+        }
+        const sorted = [...candidates.values()].sort((left, right) => left.first - right.first || left.second - right.second);
+        for (const { key } of sorted) {
+            if (queued.has(key) || (revisitCounts.get(key) ?? 0) >= resolved.maximumEdgeRevisits) {
+                continue;
+            }
+            queued.add(key);
+            queue.push(key);
+        }
+    };
+    while (queueOffset < queue.length && attemptCount < maximumFlipAttempts) {
+        const key = queue[queueOffset++];
+        queued.delete(key);
+        const revisits = (revisitCounts.get(key) ?? 0) + 1;
+        revisitCounts.set(key, revisits);
+        const edge = edges.get(key);
+        if (edge === undefined || !isCandidateEdge(edge))
+            continue;
+        attemptCount += 1;
+        const uses = [...edge.uses].sort((left, right) => left.face - right.face);
+        const firstUse = uses[0];
+        const secondUse = uses[1];
+        if (firstUse.start !== secondUse.end || firstUse.end !== secondUse.start)
+            continue;
+        const firstTriangle = triangles[firstUse.face];
+        const secondTriangle = triangles[secondUse.face];
+        const oppositeFirst = firstTriangle.find((vertex) => vertex !== firstUse.start && vertex !== firstUse.end);
+        const oppositeSecond = secondTriangle.find((vertex) => vertex !== firstUse.start && vertex !== firstUse.end);
+        if (oppositeFirst === undefined || oppositeSecond === undefined)
+            continue;
+        const vertices = [firstUse.start, firstUse.end, oppositeFirst, oppositeSecond];
+        if (new Set(vertices).size !== 4)
+            continue;
+        const replacementKey = edgeKey(oppositeFirst, oppositeSecond);
+        if (edges.has(replacementKey))
+            continue;
+        const patchId = before.patchByFace[firstUse.face];
+        const patch = before.patches[patchId];
+        const normal = patch.report.normal;
+        const startPoint = pointAt(mesh.positions, firstUse.start);
+        const endPoint = pointAt(mesh.positions, firstUse.end);
+        const firstPoint = pointAt(mesh.positions, oppositeFirst);
+        const secondPoint = pointAt(mesh.positions, oppositeSecond);
+        const sideOfReplacementFirst = dot(cross(subtract(secondPoint, firstPoint), subtract(startPoint, firstPoint)), normal);
+        const sideOfReplacementSecond = dot(cross(subtract(secondPoint, firstPoint), subtract(endPoint, firstPoint)), normal);
+        const sideOfCurrentFirst = dot(cross(subtract(endPoint, startPoint), subtract(firstPoint, startPoint)), normal);
+        const sideOfCurrentSecond = dot(cross(subtract(endPoint, startPoint), subtract(secondPoint, startPoint)), normal);
+        const minimumDoubleArea = before.tolerance.area;
+        if (Math.abs(sideOfReplacementFirst) <= minimumDoubleArea ||
+            Math.abs(sideOfReplacementSecond) <= minimumDoubleArea ||
+            Math.sign(sideOfReplacementFirst) === Math.sign(sideOfReplacementSecond) ||
+            Math.abs(sideOfCurrentFirst) <= minimumDoubleArea ||
+            Math.abs(sideOfCurrentSecond) <= minimumDoubleArea ||
+            Math.sign(sideOfCurrentFirst) === Math.sign(sideOfCurrentSecond)) {
+            continue;
+        }
+        const replacementFirst = [oppositeFirst, firstUse.start, oppositeSecond];
+        const replacementSecond = [oppositeFirst, oppositeSecond, firstUse.end];
+        const replacementFirstArea = dot(cross(subtract(pointAt(mesh.positions, replacementFirst[1]), firstPoint), subtract(pointAt(mesh.positions, replacementFirst[2]), firstPoint)), normal);
+        const replacementSecondArea = dot(cross(subtract(pointAt(mesh.positions, replacementSecond[1]), firstPoint), subtract(pointAt(mesh.positions, replacementSecond[2]), firstPoint)), normal);
+        if (replacementFirstArea <= minimumDoubleArea || replacementSecondArea <= minimumDoubleArea) {
+            continue;
+        }
+        const qualityComparison = comparePairQuality(pairQuality(mesh.positions, firstTriangle, secondTriangle), pairQuality(mesh.positions, replacementFirst, replacementSecond), before.tolerance.angular);
+        if (qualityComparison < 0)
+            continue;
+        if (qualityComparison === 0) {
+            const currentDiagonalSquared = squaredLength(subtract(endPoint, startPoint));
+            const replacementDiagonalSquared = squaredLength(subtract(secondPoint, firstPoint));
+            const squaredLengthTolerance = before.tolerance.linear ** 2;
+            if (replacementDiagonalSquared > currentDiagonalSquared + squaredLengthTolerance)
+                continue;
+            if (Math.abs(replacementDiagonalSquared - currentDiagonalSquared) <= squaredLengthTolerance) {
+                const changes = new Map([
+                    [firstUse.start, -1],
+                    [firstUse.end, -1],
+                    [oppositeFirst, 1],
+                    [oppositeSecond, 1],
+                ]);
+                if (localConcentrationPotential(vertices, incidence, valence, changes) >=
+                    localConcentrationPotential(vertices, incidence, valence)) {
+                    continue;
+                }
+            }
+        }
+        removeFace(firstUse.face, firstTriangle);
+        removeFace(secondUse.face, secondTriangle);
+        triangles[firstUse.face] = replacementFirst;
+        triangles[secondUse.face] = replacementSecond;
+        addFace(firstUse.face, replacementFirst);
+        addFace(secondUse.face, replacementSecond);
+        incidence[firstUse.start] -= 1;
+        incidence[firstUse.end] -= 1;
+        incidence[oppositeFirst] += 1;
+        incidence[oppositeSecond] += 1;
+        valence[firstUse.start] -= 1;
+        valence[firstUse.end] -= 1;
+        valence[oppositeFirst] += 1;
+        valence[oppositeSecond] += 1;
+        flipCount += 1;
+        changedPatchIds.add(patchId);
+        enqueueAround(vertices);
+    }
+    if (queueOffset < queue.length)
+        budgetExhausted = true;
+    if (flipCount === 0) {
+        return unchangedResult(mesh, before.report, skippedPatchCount, budgetExhausted);
+    }
+    const indices = new Uint32Array(mesh.indices.length);
+    for (let faceIndex = 0; faceIndex < triangles.length; faceIndex += 1) {
+        indices.set(triangles[faceIndex], faceIndex * 3);
+    }
+    const candidate = { indices, positions: mesh.positions };
+    const after = buildTriangleMeshQualityAnalysis(candidate, options);
+    const fallbackReason = fallbackReasonForCandidate(before, after, boundaryEdgeKeys);
+    if (fallbackReason !== undefined) {
+        return unchangedResult(mesh, before.report, skippedPatchCount, budgetExhausted, fallbackReason);
+    }
+    return {
+        after: after.report,
+        before: before.report,
+        budgetExhausted,
+        changed: true,
+        flipCount,
+        mesh: candidate,
+        optimizedPatchCount: changedPatchIds.size,
+        skippedPatchCount,
+    };
+}