remesh-threejs 0.2.1 → 0.3.0

package/README.md

@@ -5,7 +5,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Build Status](https://github.com/RossGraeber/remesh-threejs/workflows/CI/badge.svg)](https://github.com/RossGraeber/remesh-threejs/actions)
 
-TypeScript library for adaptive remeshing of non-manifold surfaces using Three.js.
+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"](https://doi.org/10.1111/j.1467-8659.2008.01285.x) by Zilske, Lamecker, and Zachow.
 
@@ -14,6 +14,7 @@ Based on the EUROGRAPHICS 2008 paper ["Adaptive Remeshing of Non-Manifold Surfac
 - **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
@@ -42,6 +43,21 @@ console.log(`Remeshed in ${result.stats.iterations} iterations`);
 const outputGeometry = result.geometry;
 ```
 
+### Fast Mesh Repair
+
+```typescript
+import { repairMesh, removeIsolatedVertices } from 'remesh-threejs';
+
+// Quick repair (removes isolated vertices, degenerate faces, duplicates)
+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);
+```
+
 ### Analyze Mesh for Non-Manifold Issues
 
 ```typescript
@@ -105,6 +121,10 @@ const outputGeometry = exportBufferGeometry(mesh);
 | 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 |
 | `analyzeManifold(geometry)` | Analyze mesh for non-manifold features |
 | `isManifold(geometry)` | Quick check if mesh is manifold |
 | `validateTopology(mesh)` | Validate mesh topology integrity |
@@ -115,6 +135,7 @@ const outputGeometry = exportBufferGeometry(mesh);
 |-------|-------------|
 | `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 |
@@ -166,6 +187,64 @@ const bvh = createBVHFromMesh(mesh);
 const result = bvh.closestPoint(queryPoint);
 ```
 
+### Mesh Repair API
+
+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,
+} 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
+```
+
+#### 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()
+  .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 |
+
 ### Visualization Helpers
 
 ```typescript
@@ -187,6 +266,8 @@ const qualityMesh = exportQualityGeometry(mesh);
 
 ## Options
 
+### Remesh Options
+
 ```typescript
 interface RemeshOptions {
   // Target edge length (default: auto-computed)
@@ -210,6 +291,30 @@ interface RemeshOptions {
 }
 ```
 
+### Repair Options
+
+```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
@@ -265,7 +370,3 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 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
-
-## License
-
-MIT

package/dist/index.d.ts

@@ -432,6 +432,32 @@ export declare function cross(a: Vec3, b: Vec3): Vec3;
  */
 export declare const DEFAULT_REMESH_OPTIONS: Required<Omit<RemeshOptions, 'targetEdgeLength' | 'featureEdges'>>;
 
+/**
+ * Defect information for analysis.
+ */
+export declare interface DefectInfo {
+    type: 'non-manifold' | 'hole' | 'degenerate' | 'intersection' | 'isolated' | 'duplicate' | 'normal';
+    count: number;
+    locations: {
+        faceIndex?: number;
+        vertexIndex?: number;
+        edgeIndex?: number;
+    }[];
+}
+
+/**
+ * Repairs degenerate faces (zero-area triangles, duplicate vertices).
+ */
+export declare class DegenerateFaceRepair extends RepairOperation {
+    private degenerateFaces;
+    private areaThreshold;
+    constructor(mesh: NonManifoldMesh, verbose?: boolean, areaThreshold?: number);
+    detect(): number;
+    repair(): number;
+    getName(): string;
+    canParallelize(): boolean;
+}
+
 /**
  * Computes the Euclidean distance between two points.
  */
@@ -447,6 +473,21 @@ export declare function distanceSquared(a: Vec3, b: Vec3): number;
  */
 export declare function dot(a: Vec3, b: Vec3): number;
 
+/**
+ * Repairs duplicate faces (faces with identical vertices).
+ */
+export declare class DuplicateFaceRepair extends RepairOperation {
+    private duplicates;
+    detect(): number;
+    repair(): number;
+    /**
+     * Create canonical key from sorted vertex IDs.
+     */
+    private makeFaceKey;
+    getName(): string;
+    canParallelize(): boolean;
+}
+
 /**
  * Represents an undirected edge in the mesh.
  * For non-manifold meshes, an edge can have more than 2 halfedges.
@@ -1215,6 +1256,17 @@ export declare function isDelaunay(edge: Edge): boolean;
  */
 export declare function isManifold(geometry: BufferGeometry): boolean;
 
+/**
+ * Repairs isolated vertices (vertices with no incident halfedges).
+ */
+export declare class IsolatedVertexRepair extends RepairOperation {
+    private isolatedVertices;
+    detect(): number;
+    repair(): number;
+    getName(): string;
+    canParallelize(): boolean;
+}
+
 /**
  * Checks if a point lies inside a triangle (using barycentric coordinates).
  */
@@ -1379,6 +1431,62 @@ export declare interface MeshQualityStats {
     totalArea: number;
 }
 
+/**
+ * Advanced mesh repair with fine-grained control and composition.
+ */
+export declare class MeshRepairer {
+    private mesh;
+    private options;
+    private operations;
+    private stats;
+    constructor(meshOrGeometry: NonManifoldMesh | BufferGeometry, options?: RepairOptions);
+    /**
+     * Remove isolated vertices (vertices with no faces).
+     * @returns this for chaining
+     */
+    removeIsolatedVertices(): this;
+    /**
+     * Remove zero-area and degenerate triangles.
+     * @param areaThreshold - Minimum area threshold (default: 1e-10)
+     * @returns this for chaining
+     */
+    removeDegenerateFaces(areaThreshold?: number): this;
+    /**
+     * Remove duplicate faces with identical vertices.
+     * @returns this for chaining
+     */
+    removeDuplicateFaces(): this;
+    /**
+     * Run all common repairs in optimal order.
+     * @returns this for chaining
+     */
+    repairAll(): this;
+    /**
+     * Execute all queued operations.
+     * @returns Repair statistics
+     */
+    execute(): RepairStats;
+    /**
+     * Get current statistics.
+     */
+    getStats(): RepairStats;
+    /**
+     * Get the repaired mesh.
+     */
+    getMesh(): NonManifoldMesh;
+    /**
+     * Export to BufferGeometry.
+     */
+    toBufferGeometry(): BufferGeometry;
+    /**
+     * Validate the mesh after repairs.
+     */
+    validate(): {
+        isValid: boolean;
+        errors: string[];
+    };
+}
+
 /**
  * Computes the midpoint between two points.
  */
@@ -1585,6 +1693,24 @@ export declare interface NonManifoldVertexInfo {
  */
 export declare function normalize(v: Vec3): Vec3;
 
+/**
+ * Statistics for a single repair operation.
+ */
+export declare interface OperationStats {
+    /** Name of the operation */
+    operation: string;
+    /** Number of defects found */
+    defectsFound: number;
+    /** Number of defects fixed */
+    defectsFixed: number;
+    /** Processing time in milliseconds */
+    timeMs: number;
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Reason for failure (if any) */
+    reason?: string;
+}
+
 /**
  * Projects a point onto a line defined by two points.
  * Returns the closest point on the line to the given point.
@@ -1783,6 +1909,133 @@ export declare interface RemeshStats {
     processingTimeMs: number;
 }
 
+/**
+ * Remove degenerate faces (zero area, duplicate vertices).
+ *
+ * @param geometry - Input BufferGeometry
+ * @param options - Repair options with optional areaThreshold
+ * @returns Repaired geometry and statistics
+ */
+export declare function removeDegenerateFaces(geometry: BufferGeometry, options?: RepairOptions & {
+    areaThreshold?: number;
+}): RepairResult;
+
+/**
+ * Remove duplicate faces with identical vertices.
+ *
+ * @param geometry - Input BufferGeometry
+ * @param options - Repair options
+ * @returns Repaired geometry and statistics
+ */
+export declare function removeDuplicateFaces(geometry: BufferGeometry, options?: RepairOptions): RepairResult;
+
+/**
+ * Remove isolated vertices (vertices with no incident faces).
+ *
+ * @param geometry - Input BufferGeometry
+ * @param options - Repair options
+ * @returns Repaired geometry and statistics
+ */
+export declare function removeIsolatedVertices(geometry: BufferGeometry, options?: RepairOptions): RepairResult;
+
+/**
+ * Repair a mesh by applying all repair operations in optimal order.
+ * Fast alternative to full remeshing for common defects.
+ *
+ * @param geometry - Input BufferGeometry
+ * @param options - Repair options
+ * @returns Repaired geometry and statistics
+ */
+export declare function repairMesh(geometry: BufferGeometry, options?: RepairOptions): RepairResult;
+
+/**
+ * Base class for all repair operations.
+ */
+export declare abstract class RepairOperation {
+    protected mesh: NonManifoldMesh;
+    protected verbose: boolean;
+    constructor(mesh: NonManifoldMesh, verbose?: boolean);
+    /**
+     * Detect defects in the mesh.
+     * @returns Number of defects found
+     */
+    abstract detect(): number;
+    /**
+     * Repair the detected defects.
+     * @returns Number of defects fixed
+     */
+    abstract repair(): number;
+    /**
+     * Execute the operation (detect + repair).
+     * @returns Operation statistics
+     */
+    execute(): OperationStats;
+    /**
+     * Get the name of this operation.
+     */
+    abstract getName(): string;
+    /**
+     * Check if this operation can be parallelized.
+     */
+    abstract canParallelize(): boolean;
+}
+
+/**
+ * Options for mesh repair operations.
+ */
+export declare interface RepairOptions {
+    /** Use Web Workers for parallel processing (default: true 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;
+}
+
+/**
+ * Result of a repair operation.
+ */
+export declare interface RepairResult {
+    /** The repaired geometry */
+    geometry: BufferGeometry;
+    /** Repair statistics */
+    stats: RepairStats;
+}
+
+/**
+ * Overall repair statistics.
+ */
+export declare interface RepairStats {
+    /** Input mesh statistics */
+    input: {
+        vertices: number;
+        faces: number;
+        edges: number;
+    };
+    /** Output mesh statistics */
+    output: {
+        vertices: number;
+        faces: number;
+        edges: number;
+    };
+    /** Statistics for each operation performed */
+    operations: OperationStats[];
+    /** Total processing time in milliseconds */
+    totalTimeMs: number;
+    /** Whether all operations succeeded */
+    success: boolean;
+    /** Total defects found */
+    totalDefectsFound: number;
+    /** Total defects fixed */
+    totalDefectsFixed: number;
+}
+
 /**
  * Multiplies a vector by a scalar.
  */