MeshRepair

The high-performance, WebAssembly-powered mesh repair engine for the browser.

MeshRepair is a lightweight, headless port of VCGlib (Visualization and Computer Graphics Library) specialized for the automated repair and sanitization of STL files. Built with Emscripten, it brings the industrial-grade mesh processing power of MeshLab directly into web-based 3D printing slicers, viewers, and CAD tools.

Features

• Fast: Native-speed mesh processing via WebAssembly
• Complete: Full suite of mesh repair operations from VCGlib
• Simple: Clean TypeScript API with presets for common use cases
• Flexible: Works in browsers and Node.js
• Lightweight: No external dependencies, ~200-400KB WASM

Installation

npm install @goodtools/meshrepair

Usage

Basic Usage

import { MeshRepair } from '@goodtools/meshrepair';
import loadMeshRepair from '@goodtools/meshrepair/wasm';

// Initialize
const meshrepair = await MeshRepair.init(loadMeshRepair);

// Load and repair an STL file
const stlData = await fetch('/model.stl').then((r) => r.arrayBuffer());
const { result, output } = meshrepair.repair('model.stl', new Uint8Array(stlData), 'print-ready');

console.log(`Repaired: ${result.originalFaces} -> ${result.finalFaces} faces`);
console.log(`Holes filled: ${result.holesFilled}`);

// Download repaired file
const blob = new Blob([output], { type: 'application/octet-stream' });
const url = URL.createObjectURL(blob);

Using Presets

MeshRepair includes three presets for common use cases:

// Minimal - just remove duplicates and degenerate geometry
const { result } = meshrepair.repair('model.stl', data, 'minimal');

// Print-ready - fill holes, fix normals (recommended for 3D printing)
const { result } = meshrepair.repair('model.stl', data, 'print-ready');

// Aggressive - all repairs enabled
const { result } = meshrepair.repair('model.stl', data, 'aggressive');

Custom Options

import { MeshRepair, PRESETS } from '@goodtools/meshrepair';

const { result, output } = meshrepair.repair('model.stl', data, {
  // Start from a preset
  ...PRESETS['print-ready'],

  // Customize options
  maxHoleSize: 50, // Only fill holes with <=50 edges
  removeNonManifoldFace: true,
  removeNonManifoldVertex: true,
});

Progress Callback

const { result, output } = meshrepair.repair('model.stl', data, 'print-ready', (step, progress) => {
  console.log(`${step}: ${(progress * 100).toFixed(0)}%`);
});

Large Files

For large files, write directly to the virtual filesystem to avoid extra memory copies:

const meshrepair = await MeshRepair.init(loadMeshRepair);

// Write large file directly to virtual FS
meshrepair.FS.writeFile('/uploads/huge-model.stl', hugeBuffer);

// Repair by path (memory efficient)
const { result, outputPath } = meshrepair.repairFileInPlace('/uploads/huge-model.stl', {
  options: 'print-ready',
  onProgress: (step, p) => updateProgressBar(step, p),
});

// Read output when ready
const repairedData = meshrepair.FS.readFile(outputPath);

Custom WASM Location

const meshrepair = await MeshRepair.init(loadMeshRepair, {
  locateFile: (path, prefix) => {
    if (path.endsWith('.wasm')) return '/assets/meshrepair.wasm';
    return prefix + path;
  },
});

API Reference

MeshRepair.init(loader, options?)

Initialize the MeshRepair WASM module.

Parameters:

• loader: MeshRepairLoader - Function that loads the WASM module (import from @goodtools/meshrepair/wasm)
• options?: InitOptions - Optional initialization options
  • locateFile?: (path: string, prefix: string) => string - Custom function to locate WASM files

Returns: Promise<MeshRepair>

meshrepair.repair(name, data, options?, onProgress?)

Repair an STL file by passing data directly.

Parameters:

• name: string - Filename (used for virtual FS path)
• data: string | ArrayBufferView - STL file data
• options?: RepairOptions | PresetName - Repair options or preset name
• onProgress?: (step: string, progress: number) => void - Progress callback

Returns: { result: RepairResult, output: Uint8Array }

meshrepair.repairFile(inputPath, options?)

Repair an STL file from a path in the virtual filesystem.

meshrepair.repairFileInPlace(inputPath, options?)

Repair without reading output back to JavaScript (memory efficient).

meshrepair.FS

Direct access to Emscripten virtual filesystem for large file handling.

meshrepair.destroy()

Clean up resources.

Repair Options

Option	Type	Default	Description
removeDuplicateVertex	boolean	true	Remove vertices at the same position
removeDuplicateFace	boolean	true	Remove faces with identical vertex references
removeUnreferencedVertex	boolean	true	Remove vertices not referenced by any face
removeDegenerateFace	boolean	true	Remove faces with zero area
fillHoles	boolean	false	Fill holes in the mesh
maxHoleSize	number	100	Maximum hole size to fill (edge count)
removeNonManifoldFace	boolean	false	Remove non-manifold faces
removeNonManifoldVertex	boolean	false	Remove non-manifold vertices
fixNormalOrientation	boolean	false	Make face orientations consistent
flipNormalsOutside	boolean	false	Orient normals to point outward
removeTVertexByFlip	boolean	false	Remove T-vertices by edge flipping
removeFaceFoldByFlip	boolean	false	Remove face folds by edge flipping
binaryOutput	boolean	true	Output binary STL (false for ASCII)

Repair Result

interface RepairResult {
  code: number; // 0 = success
  error?: string; // Error message if failed
  originalVertices: number; // Vertices before repair
  originalFaces: number; // Faces before repair
  finalVertices: number; // Vertices after repair
  finalFaces: number; // Faces after repair
  duplicateVerticesRemoved: number;
  duplicateFacesRemoved: number;
  unreferencedVerticesRemoved: number;
  degenerateFacesRemoved: number;
  nonManifoldFacesRemoved: number;
  nonManifoldVerticesRemoved: number;
  holesFilled: number;
}

Build

Prerequisites

• Docker
• Node.js 22+

Building

# Build the Docker image with Emscripten
npm run build:builder

# Build the WASM library
npm run build:emscripten

# Build the TypeScript wrapper
npm install
npm run build

Local Build (without Docker)

Requires Emscripten SDK, Meson, and Ninja installed locally.

npm run build:emscripten-local
npm run build

Contributing

This project uses Changesets for version management and changelog generation.

Adding a Changeset

When making changes that should be included in the next release:

npm run changeset

Select the package, choose the change type (major/minor/patch), and write a summary. This creates a changeset file that will be included in the next release.

Change Types

• major: Breaking changes (e.g., API changes, renamed exports)
• minor: New features (backward compatible)
• patch: Bug fixes

License

MeshRepair is licensed under the GNU General Public License v3.0, the same license as VCGlib.

VCGlib is developed by the Visual Computing Lab at ISTI-CNR.

Credits

• VCGlib - The underlying mesh processing library
• MeshLab - VCGlib's flagship application
• Emscripten - C++ to WebAssembly compiler
• Wiregasm - Architectural inspiration