meshfix-wasm 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anthony Greco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# meshfix-wasm
+
+Client-side 3D mesh repair for the browser. Fixes broken STL, OBJ, and OFF files so they load cleanly in slicers like PrusaSlicer, Cura, and OrcaSlicer.
+
+Built on [PMP Library](https://www.pmp-library.org/) compiled to WebAssembly.
+
+See it in action at [www.justfixstl.com](https://www.justfixstl.com). All processing runs locally in the browser, no server, no uploads.
+
+## Install
+
+```bash
+npm install meshfix-wasm
+```
+
+## Quick Start
+
+```typescript
+import { MeshFixWorker } from "meshfix-wasm";
+
+// Initialize (loads WASM in a Web Worker)
+const meshfix = await MeshFixWorker.init();
+
+// Load an STL file
+const buffer = await fetch("model.stl").then((r) => r.arrayBuffer());
+
+// Analyze
+const { analysis, issues } = await meshfix.analyzeDetailed(buffer);
+console.log(`${analysis.vertexCount} vertices, ${analysis.faceCount} faces`);
+console.log(`Issues: ${issues.map((i) => i.message).join(", ") || "none"}`);
+
+// One-click repair
+const result = await meshfix.repair();
+console.log(`Vertices: ${result.verticesBefore} → ${result.verticesAfter}`);
+console.log(`Faces: ${result.facesBefore} → ${result.facesAfter}`);
+
+// Export repaired mesh
+const repaired = await meshfix.exportMesh("stl");
+const blob = new Blob([repaired], { type: "application/octet-stream" });
+
+// Clean up
+meshfix.dispose();
+```
+
+## API
+
+### `MeshFixWorker` (recommended)
+
+Runs all processing in a Web Worker so the UI stays responsive.
+
+```typescript
+const meshfix = await MeshFixWorker.init(options?);
+```
+
+**Init options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `workerUrl` | `string \| URL` | Custom worker script URL |
+| `coreUrl` | `string` | Custom meshfix-core.js URL |
+| `wasmUrl` | `string` | Custom .wasm file URL |
+
+**Methods:**
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `analyze(buffer)` | `MeshStats` | Basic geometry stats |
+| `analyzeDetailed(buffer)` | `{ analysis, issues }` | Full topology analysis with issue detection |
+| `repair(options?, onProgress?)` | `RepairResult` | Auto-repair pipeline |
+| `weldVertices(epsilon?)` | `WeldResult` | Merge duplicate vertices |
+| `removeDegenerates(minArea?)` | `RemoveDegeneratesResult` | Remove zero-area and duplicate faces |
+| `splitVertices()` | `SplitVerticesResult` | Fix non-manifold (bowtie) vertices |
+| `fillHoles(maxEdges?)` | `FillHolesResult` | Fill boundary loops |
+| `fixNormals()` | `FixNormalsResult` | Orient normals outward |
+| `reanalyze()` | `{ analysis, issues }` | Re-analyze after modifications |
+| `exportMesh(format?)` | `ArrayBuffer` | Export as `"stl"`, `"obj"`, or `"off"` |
+| `toRenderData()` | `RenderData` | Get vertex/index buffers for 3D rendering |
+| `dispose()` | `void` | Terminate worker and free memory |
+
+### `MeshFix` (main thread)
+
+Same API as `MeshFixWorker` but synchronous. Useful for debugging or environments without Web Workers.
+
+```typescript
+import { MeshFix } from "meshfix-wasm";
+const meshfix = await MeshFix.init();
+```
+
+### Repair Options
+
+```typescript
+await meshfix.repair({
+  weldEpsilon: 1e-6,   // vertex merge distance (default: 1e-6)
+  minArea: 1e-10,       // degenerate face threshold (default: 1e-10)
+  maxHoleEdges: 100,    // max hole size to fill (default: 100)
+});
+```
+
+### Repair Pipeline
+
+The `repair()` method runs these steps in order:
+
+1. **Weld vertices** — merge duplicates within epsilon distance
+2. **Remove degenerates** — delete zero-area and duplicate faces (skipped if mesh is already watertight)
+3. **Split vertices** — fix non-manifold (bowtie) vertices
+4. **Fill holes** — close boundary loops with fan triangulation
+5. **Fix normals** — orient all faces outward using signed volume
+
+### Progress Callbacks
+
+```typescript
+await meshfix.repair({}, (event) => {
+  console.log(`Step ${event.stepIndex + 1}/${event.totalSteps}: ${event.step}`);
+});
+```
+
+### Three.js Integration
+
+```typescript
+const renderData = await meshfix.toRenderData();
+
+const geometry = new THREE.BufferGeometry();
+geometry.setAttribute("position", new THREE.BufferAttribute(renderData.positions, 3));
+geometry.setAttribute("normal", new THREE.BufferAttribute(renderData.normals, 3));
+geometry.setIndex(new THREE.BufferAttribute(renderData.indices, 1));
+```
+
+The `renderData.faceFlags` field contains per-face bitmask flags for issue visualization:
+
+| Flag | Bit | Meaning |
+|------|-----|---------|
+| `0x01` | Degenerate | Zero-area face |
+| `0x02` | Duplicate | Identical to another face |
+| `0x04` | Flipped | Normal points inward |
+| `0x08` | Boundary | Face has an open edge |
+| `0x10` | Non-manifold | Adjacent to a non-manifold vertex |
+
+## Browser Support
+
+Requires browsers with WebAssembly and Web Worker support:
+- Chrome 57+
+- Firefox 52+
+- Safari 11+
+- Edge 16+
+
+## Acknowledgments
+
+This library uses [PMP Library](https://www.pmp-library.org/) (MIT License) by the Polygon Mesh Processing Library developers and Computer Graphics Group, RWTH Aachen.
+
+## License
+
+[MIT](LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import type { MeshStats, MeshAnalysis, MeshIssue, MeshFixCoreModule, MeshAnalyzerInstance, WeldResult, RemoveDegeneratesResult, FixNormalsResult, FillHolesResult, SplitVerticesResult, RepairResult, RepairOptions, ProgressEvent, RenderData } from "./types.js";
+export type { MeshStats, MeshAnalysis, MeshIssue, MeshFixCoreModule, MeshAnalyzerInstance, WeldResult, RemoveDegeneratesResult, FixNormalsResult, FillHolesResult, SplitVerticesResult, RepairResult, RepairOptions, ProgressEvent, RenderData };
+export type { IssueType, IssueSeverity, RepairStep } from "./types.js";
+export { buildIssues } from "./issues.js";
+export { MeshFixWorker } from "./worker-client.js";
+export type { WorkerInitOptions } from "./worker-types.js";
+export type ExportFormat = "stl" | "obj" | "off";
+export interface AnalysisResult {
+    analysis: MeshAnalysis;
+    issues: MeshIssue[];
+}
+export declare class MeshFix {
+    private module;
+    private analyzer;
+    private constructor();
+    static init(): Promise<MeshFix>;
+    analyze(data: ArrayBuffer): MeshStats;
+    analyzeTestShape(name: string): MeshStats;
+    analyzeDetailed(data: ArrayBuffer): AnalysisResult;
+    analyzeTestShapeDetailed(name: string): AnalysisResult;
+    weldVertices(epsilon?: number): WeldResult;
+    removeDegenerates(minArea?: number): RemoveDegeneratesResult;
+    fixNormals(): FixNormalsResult;
+    fillHoles(maxEdges?: number): FillHolesResult;
+    splitVertices(): SplitVerticesResult;
+    repair(options?: RepairOptions, onProgress?: (event: ProgressEvent) => void): RepairResult;
+    reanalyze(): AnalysisResult;
+    exportMesh(format?: ExportFormat): ArrayBuffer;
+    /** @deprecated Use exportMesh("stl") instead */
+    exportSTL(): ArrayBuffer;
+    toRenderData(): RenderData;
+    dispose(): void;
+}

package/dist/index.js

@@ -0,0 +1,212 @@
+import { buildIssues } from "./issues.js";
+export { buildIssues } from "./issues.js";
+export { MeshFixWorker } from "./worker-client.js";
+export class MeshFix {
+    constructor(module) {
+        this.module = module;
+        this.analyzer = new module.MeshAnalyzer();
+    }
+    static async init() {
+        const module = await createMeshFixCore();
+        return new MeshFix(module);
+    }
+    analyze(data) {
+        const uint8 = new Uint8Array(data);
+        const path = "/tmp/input.stl";
+        try {
+            this.module.FS.writeFile(path, uint8);
+            const ok = this.analyzer.loadFromFile(path);
+            if (!ok) {
+                throw new Error(this.analyzer.getLastError() || "Failed to load mesh");
+            }
+            return this.analyzer.getStats();
+        }
+        finally {
+            try {
+                this.module.FS.unlink(path);
+            }
+            catch {
+                // file may not exist if write failed
+            }
+        }
+    }
+    analyzeTestShape(name) {
+        const ok = this.analyzer.loadTestShape(name);
+        if (!ok) {
+            throw new Error(this.analyzer.getLastError() || "Failed to create test shape");
+        }
+        return this.analyzer.getStats();
+    }
+    analyzeDetailed(data) {
+        const uint8 = new Uint8Array(data);
+        const path = "/tmp/input.stl";
+        try {
+            this.module.FS.writeFile(path, uint8);
+            const ok = this.analyzer.loadFromFile(path);
+            if (!ok) {
+                throw new Error(this.analyzer.getLastError() || "Failed to load mesh");
+            }
+            const analysis = this.analyzer.getAnalysis();
+            return { analysis, issues: buildIssues(analysis) };
+        }
+        finally {
+            try {
+                this.module.FS.unlink(path);
+            }
+            catch {
+                // file may not exist if write failed
+            }
+        }
+    }
+    analyzeTestShapeDetailed(name) {
+        const ok = this.analyzer.loadTestShape(name);
+        if (!ok) {
+            throw new Error(this.analyzer.getLastError() || "Failed to create test shape");
+        }
+        const analysis = this.analyzer.getAnalysis();
+        return { analysis, issues: buildIssues(analysis) };
+    }
+    weldVertices(epsilon = 1e-6) {
+        if (!this.analyzer.isLoaded()) {
+            throw new Error("No mesh loaded");
+        }
+        return this.analyzer.weldVertices(epsilon);
+    }
+    removeDegenerates(minArea = 1e-10) {
+        if (!this.analyzer.isLoaded()) {
+            throw new Error("No mesh loaded");
+        }
+        return this.analyzer.removeDegenerates(minArea);
+    }
+    fixNormals() {
+        if (!this.analyzer.isLoaded()) {
+            throw new Error("No mesh loaded");
+        }
+        return this.analyzer.fixNormals();
+    }
+    fillHoles(maxEdges = 100) {
+        if (!this.analyzer.isLoaded()) {
+            throw new Error("No mesh loaded");
+        }
+        return this.analyzer.fillHoles(maxEdges);
+    }
+    splitVertices() {
+        if (!this.analyzer.isLoaded()) {
+            throw new Error("No mesh loaded");
+        }
+        return this.analyzer.splitVertices();
+    }
+    repair(options, onProgress) {
+        if (!this.analyzer.isLoaded()) {
+            throw new Error("No mesh loaded");
+        }
+        const weldEpsilon = options?.weldEpsilon ?? 1e-6;
+        const minArea = options?.minArea ?? 1e-10;
+        const maxHoleEdges = options?.maxHoleEdges ?? 100;
+        const totalSteps = 5;
+        const verticesBefore = this.analyzer.getVertexCount();
+        const facesBefore = this.analyzer.getFaceCount();
+        const progress = (step, stepIndex) => {
+            if (onProgress)
+                onProgress({ step, stepIndex, totalSteps });
+        };
+        progress("weld", 0);
+        const weld = this.analyzer.weldVertices(weldEpsilon);
+        // Only remove degenerates if mesh is not watertight — removing
+        // faces from a closed surface tears holes that may not fill cleanly.
+        const midAnalysis = this.analyzer.getAnalysis();
+        progress("removeDegenerates", 1);
+        const removeDegenerates = midAnalysis.isWatertight
+            ? null
+            : this.analyzer.removeDegenerates(minArea);
+        progress("splitVertices", 2);
+        const splitVertices = this.analyzer.splitVertices();
+        progress("fillHoles", 3);
+        const fillHoles = this.analyzer.fillHoles(maxHoleEdges);
+        progress("fixNormals", 4);
+        const fixNormals = this.analyzer.fixNormals();
+        return {
+            weld,
+            removeDegenerates: removeDegenerates,
+            splitVertices,
+            fillHoles,
+            fixNormals,
+            verticesBefore,
+            verticesAfter: this.analyzer.getVertexCount(),
+            facesBefore,
+            facesAfter: this.analyzer.getFaceCount(),
+        };
+    }
+    reanalyze() {
+        if (!this.analyzer.isLoaded()) {
+            throw new Error("No mesh loaded");
+        }
+        const analysis = this.analyzer.getAnalysis();
+        return { analysis, issues: buildIssues(analysis) };
+    }
+    exportMesh(format = "stl") {
+        if (!this.analyzer.isLoaded()) {
+            throw new Error("No mesh loaded");
+        }
+        const path = `/tmp/export.${format}`;
+        try {
+            const ok = this.analyzer.exportMesh(path);
+            if (!ok) {
+                throw new Error(this.analyzer.getLastError() || "Failed to export mesh");
+            }
+            const data = this.module.FS.readFile(path);
+            return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+        }
+        finally {
+            try {
+                this.module.FS.unlink(path);
+            }
+            catch {
+                // file may not exist if export failed
+            }
+        }
+    }
+    /** @deprecated Use exportMesh("stl") instead */
+    exportSTL() {
+        return this.exportMesh("stl");
+    }
+    toRenderData() {
+        if (!this.analyzer.isLoaded()) {
+            throw new Error("No mesh loaded");
+        }
+        const path = "/tmp/render.bin";
+        try {
+            const ok = this.analyzer.writeRenderData(path);
+            if (!ok) {
+                throw new Error(this.analyzer.getLastError() || "Failed to write render data");
+            }
+            const data = this.module.FS.readFile(path);
+            const buf = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+            const view = new DataView(buf);
+            const vertexCount = view.getUint32(0, true);
+            const indexCount = view.getUint32(4, true);
+            const posOffset = 8;
+            const normOffset = posOffset + vertexCount * 3 * 4;
+            const idxOffset = normOffset + vertexCount * 3 * 4;
+            const flagsOffset = idxOffset + indexCount * 4;
+            const faceCount = indexCount / 3;
+            return {
+                positions: new Float32Array(buf, posOffset, vertexCount * 3),
+                normals: new Float32Array(buf, normOffset, vertexCount * 3),
+                indices: new Uint32Array(buf, idxOffset, indexCount),
+                faceFlags: new Uint8Array(buf, flagsOffset, faceCount),
+            };
+        }
+        finally {
+            try {
+                this.module.FS.unlink(path);
+            }
+            catch {
+                // file may not exist if write failed
+            }
+        }
+    }
+    dispose() {
+        this.analyzer.delete();
+    }
+}

package/dist/issues.d.ts

@@ -0,0 +1,2 @@
+import type { MeshAnalysis, MeshIssue } from "./types.js";
+export declare function buildIssues(a: MeshAnalysis): MeshIssue[];

package/dist/issues.js

@@ -0,0 +1,76 @@
+export function buildIssues(a) {
+    const issues = [];
+    if (a.nonManifoldVertexCount > 0) {
+        issues.push({
+            type: "non_manifold_vertices",
+            severity: "error",
+            count: a.nonManifoldVertexCount,
+            message: `${a.nonManifoldVertexCount} non-manifold vertex(es) found`,
+        });
+    }
+    if (a.nonManifoldEdgeCount > 0) {
+        issues.push({
+            type: "non_manifold_edges",
+            severity: "error",
+            count: a.nonManifoldEdgeCount,
+            message: `${a.nonManifoldEdgeCount} non-manifold edge(s) detected (faces skipped during import)`,
+        });
+    }
+    if (a.flippedNormalCount > 0) {
+        issues.push({
+            type: "flipped_normals",
+            severity: "warning",
+            count: a.flippedNormalCount,
+            message: `${a.flippedNormalCount} face(s) with flipped normals (inverted winding)`,
+        });
+    }
+    if (a.degenerateTriangleCount > 0) {
+        issues.push({
+            type: "degenerate_triangles",
+            severity: "warning",
+            count: a.degenerateTriangleCount,
+            message: `${a.degenerateTriangleCount} degenerate triangle(s) with near-zero area`,
+        });
+    }
+    if (a.holeCount > 0) {
+        issues.push({
+            type: "holes",
+            severity: "warning",
+            count: a.holeCount,
+            message: `${a.holeCount} hole(s) (boundary loops) found`,
+        });
+    }
+    if (a.duplicateFaceCount > 0) {
+        issues.push({
+            type: "duplicate_faces",
+            severity: "warning",
+            count: a.duplicateFaceCount,
+            message: `${a.duplicateFaceCount} duplicate face(s) found`,
+        });
+    }
+    if (a.isolatedVertexCount > 0) {
+        issues.push({
+            type: "isolated_vertices",
+            severity: "info",
+            count: a.isolatedVertexCount,
+            message: `${a.isolatedVertexCount} isolated vertex(es) not connected to any face`,
+        });
+    }
+    if (!a.isWatertight) {
+        issues.push({
+            type: "not_watertight",
+            severity: "info",
+            count: a.boundaryEdges,
+            message: `Mesh is not watertight (${a.boundaryEdges} boundary edges)`,
+        });
+    }
+    if (a.connectedComponents > 1) {
+        issues.push({
+            type: "multiple_components",
+            severity: "info",
+            count: a.connectedComponents,
+            message: `Mesh has ${a.connectedComponents} disconnected components`,
+        });
+    }
+    return issues;
+}