remesh-threejs


TypeScript library for repair and remeshing of non-manifold surfaces using Three.js.

Based on the EUROGRAPHICS 2008 paper "Adaptive Remeshing of Non-Manifold Surfaces" by Zilske, Lamecker, and Zachow.

Features

- Non-manifold mesh support: Extended halfedge data structure supporting edges with more than 2 incident faces
- Feature skeleton: Unified treatment of non-manifold edges, feature lines, and boundary edges
- Adaptive remeshing: Edge splitting, contraction, flipping, and vertex smoothing
- Fast mesh repair: Targeted repair operations 10-100x faster than full remeshing
- Analysis tools: Detect and classify non-manifold vertices and edges
- Spatial acceleration: SpatialHash and BVH for efficient queries on large meshes (500K+ triangles)
- Three.js integration: Import/export BufferGeometry with visualization helpers

Installation

``bash
npm install remesh-threejs three
`

Quick Start

$3

`typescript
import { BufferGeometry } from 'three';
import { remesh } from 'remesh-threejs';

// Remesh a geometry with default options
const result = remesh(inputGeometry, {
targetEdgeLength: 0.1,
iterations: 5,
});

console.log(Remeshed in ${result.stats.iterations} iterations);
const outputGeometry = result.geometry;
`

$3

`typescript
import { repairMesh, removeIsolatedVertices } from 'remesh-threejs';

// Quick repair (removes all common defects in optimal order)
const result = repairMesh(geometry);
console.log(Fixed ${result.stats.totalDefectsFixed} defects in ${result.stats.totalTimeMs}ms);

// Targeted repairs (10-100x faster than full remeshing)
const result2 = removeIsolatedVertices(geometry);
const result3 = removeDegenerateFaces(geometry, { areaThreshold: 1e-10 });
const result4 = removeDuplicateFaces(geometry);
const result5 = removeNonManifoldEdges(geometry, { strategy: 'auto' });
const result6 = fillHoles(geometry, { maxHoleSize: 10 });
const result7 = unifyNormals(geometry);
`

$3

`typescript
import { analyzeManifold, isManifold } from 'remesh-threejs';

// Quick check
if (!isManifold(geometry)) {
console.log('Mesh has non-manifold edges');
}

// Detailed analysis
const analysis = analyzeManifold(geometry);
console.log(Non-manifold edges: ${analysis.nonManifoldEdgeCount});
console.log(Non-manifold vertices: ${analysis.nonManifoldVertexCount});
console.log(Boundary edges: ${analysis.boundaryEdgeCount});
`

$3

`typescript
import {
NonManifoldMesh,
AdaptiveRemesher,
classifyAllVertices,
validateTopology,
exportBufferGeometry,
} from 'remesh-threejs';

// Create mesh from geometry
const mesh = NonManifoldMesh.fromBufferGeometry(inputGeometry);

// Classify vertices (required for skeleton-aware smoothing)
classifyAllVertices(mesh);

// Create remesher with options
const remesher = new AdaptiveRemesher(mesh, {
targetEdgeLength: 0.1,
minEdgeLength: 0.05,
maxEdgeLength: 0.2,
qualityThreshold: 0.3,
iterations: 10,
});

// Run remeshing
const stats = remesher.run();

// Validate result
const validation = validateTopology(mesh);
if (!validation.isValid) {
console.error('Topology errors:', validation.errors);
}

// Export result
const outputGeometry = exportBufferGeometry(mesh);
`

API Reference

$3

| Function | Description |
|----------|-------------|
| remesh(geometry, options?) | One-shot remeshing of a BufferGeometry |
| repairMesh(geometry, options?) | Fast repair for common defects |
| removeIsolatedVertices(geometry) | Remove orphaned vertices with no faces |
| removeDegenerateFaces(geometry, options?) | Remove zero-area triangles |
| removeDuplicateFaces(geometry) | Remove faces with identical vertices |
| removeNonManifoldEdges(geometry, options?) | Fix edges with >2 incident faces |
| fillHoles(geometry, options?) | Fill boundary holes via triangulation |
| unifyNormals(geometry, options?) | Make face orientations consistent |
| analyzeManifold(geometry) | Analyze mesh for non-manifold features |
| isManifold(geometry) | Quick check if mesh is manifold |
| validateTopology(mesh) | Validate mesh topology integrity |

$3

| Class | Description |
|-------|-------------|
| NonManifoldMesh | Main mesh data structure with halfedge connectivity |
| AdaptiveRemesher | Iterative remeshing algorithm |
| MeshRepairer | Composable mesh repair operations |
| ManifoldAnalyzer | Analysis with caching support |
| VertexClassifier | Classify vertices by skeleton topology |
| TopologyValidator | Validate mesh topology invariants |

$3

| Function | Description |
|----------|-------------|
| splitEdge(mesh, edge, t?) | Split an edge at parameter t |
| splitLongEdges(mesh, maxLength) | Split all edges exceeding length |
| contractEdge(mesh, edge) | Contract an edge to a single vertex |
| contractShortEdges(mesh, minLength) | Contract all edges below length |
| flipEdge(mesh, edge) | Flip a manifold edge |
| makeDelaunay(mesh) | Flip edges to achieve Delaunay triangulation |
| smoothAllVertices(mesh, skeleton?, lambda?) | Tangential smoothing |

$3

Vertices are classified based on their relationship to the feature skeleton:

| Type | Description | Constraint |
|------|-------------|------------|
| Manifold | Standard interior vertex | Free movement in 3D |
| OpenBook | On exactly 2 skeleton edges | Constrained to skeleton |
| SkeletonBranching | On 1 or >2 skeleton edges | Position fixed |
| NonManifoldOther | Other non-manifold config | Position fixed |

$3

| Type | Description |
|------|-------------|
| Manifold | Exactly 2 incident faces |
| NonManifold | More than 2 incident faces |
| Feature | User-marked feature edge |
| Boundary | Only 1 incident face |

$3

`typescript
import { SpatialHash, BVH, createBVHFromMesh } from 'remesh-threejs';

// Fast neighbor queries
const hash = new SpatialHash(cellSize);
hash.insert(vertex, vertex.position);
const neighbors = hash.queryRadius(position, radius);

// Closest point queries
const bvh = createBVHFromMesh(mesh);
const result = bvh.closestPoint(queryPoint);
`

$3

Fast, targeted repairs for common mesh defects. These operations are 10-100x faster than full remeshing when you only need to fix specific issues.

#### Functional API (Simple)

`typescript
import {
repairMesh,
removeIsolatedVertices,
removeDegenerateFaces,
removeDuplicateFaces,
removeNonManifoldEdges,
fillHoles,
unifyNormals,
} from 'remesh-threejs';

// Run all repairs in optimal order
const result = repairMesh(geometry);
console.log(Fixed ${result.stats.totalDefectsFixed} defects);

// Or use targeted repairs
const result2 = removeIsolatedVertices(geometry); // 100x+ faster
const result3 = removeDegenerateFaces(geometry); // 50-100x faster
const result4 = removeDuplicateFaces(geometry); // 30-60x faster
const result5 = removeNonManifoldEdges(geometry, { strategy: 'split' }); // 10-30x faster
const result6 = fillHoles(geometry, { maxHoleSize: 10 }); // 20-50x faster
const result7 = unifyNormals(geometry); // 40-80x faster
`

#### Class-Based API (Advanced)

`typescript
import { MeshRepairer } from 'remesh-threejs';

// Compose multiple repairs with chaining
const repairer = new MeshRepairer(geometry, {
verbose: true, // Enable logging
validateAfterEach: true, // Validate topology after each operation
});

const stats = repairer
.removeIsolatedVertices()
.removeDegenerateFaces()
.removeDuplicateFaces()
.removeNonManifoldEdges('auto')
.fillHoles(10)
.unifyNormals()
.execute();

const repairedGeometry = repairer.toBufferGeometry();

// Validate results
const validation = repairer.validate();
if (!validation.isValid) {
console.error('Topology errors:', validation.errors);
}
`

#### Common Defects Repaired

| Defect | Operation | Speedup vs Remesh |
|--------|-----------|-------------------|
| Orphaned vertices | removeIsolatedVertices() | 100x+ |
| Zero-area triangles | removeDegenerateFaces() | 50-100x |
| Duplicate faces | removeDuplicateFaces() | 30-60x |
| Edges with >2 faces | removeNonManifoldEdges() | 10-30x |
| Boundary holes | fillHoles() | 20-50x |
| Inconsistent normals | unifyNormals() | 40-80x |

$3

`typescript
import {
exportSkeletonGeometry,
exportClassificationGeometry,
exportQualityGeometry,
} from 'remesh-threejs';

// Visualize the feature skeleton as line segments
const skeletonLines = exportSkeletonGeometry(mesh);

// Color vertices by classification type
const classifiedMesh = exportClassificationGeometry(mesh);

// Color faces by triangle quality (red=poor, green=good)
const qualityMesh = exportQualityGeometry(mesh);
`

Options

$3

`typescript
interface RemeshOptions {
// Target edge length (default: auto-computed)
targetEdgeLength?: number;

// Edge length bounds (default: 0.5x and 2x target)
minEdgeLength?: number;
maxEdgeLength?: number;

// Minimum triangle quality threshold (default: 0.3)
qualityThreshold?: number;

// Maximum iterations (default: 10)
iterations?: number;

// Smoothing strength (default: 0.5)
smoothingLambda?: number;

// Preserve non-manifold features (default: true)
preserveFeatures?: boolean;
}
`

$3

`typescript
interface RepairOptions {
// Use Web Workers for parallel processing (default: auto for large meshes)
useWorkers?: boolean;

// Number of worker threads (default: navigator.hardwareConcurrency || 4)
workerCount?: number;

// Use spatial acceleration structures (default: true)
useAcceleration?: boolean;

// Minimum mesh size to trigger parallelization (default: 10000 faces)
parallelThreshold?: number;

// Enable verbose logging (default: false)
verbose?: boolean;

// Validate topology after each operation (default: false)
validateAfterEach?: boolean;
}
`

Development

`bash

Install dependencies

npm install

Run tests

npm test

Run tests with coverage

npm run test:coverage

Build library

npm run build

Lint and format

npm run quality:fix

Full validation (lint + test + build)

npm run validate
`

Test Coverage

The library includes comprehensive tests covering:

- Type system and branded IDs
- Core data structures (Vertex, Edge, Face, Halfedge)
- Geometric utilities (40+ functions)
- Spatial acceleration (SpatialHash, BVH)
- Analysis tools (manifold detection, classification, validation)
- Full remeshing pipeline integration

Run npm run test:coverage to see the detailed coverage report.

Publishing

See PUBLISHING.md for detailed instructions on publishing new versions to npm.

$3

1. Update version: npm version patch|minor|major
2. Push: git push && git push --tags
3. Create GitHub release
4. Automated CI/CD publishes to npm

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)
5. Open a Pull Request