TopoCleaner¶

Advanced mesh topology cleaning with two cleaning modes and recursive processing.

Overview¶

TopoCleaner provides intelligent mesh cleaning operations to fix common topology issues in imported or generated 3D models. It offers two cleaning modes with different levels of aggressiveness and supports recursive cleaning until convergence.

Location¶

Shift+W Menu → CLEANING → Default Clean / Aggressive Clean

Features¶

Two Cleaning Modes¶

Default Clean¶

Conservative approach suitable for most models
Removes loose geometry (vertices, edges)
Merges duplicate vertices (0.0001 threshold)
Converts triangles to quads
Limited dissolve (5° angle)
Recalculates normals (inside orientation)
Safe for models with UVs and materials

Aggressive Clean¶

Comprehensive cleaning for problematic imports
All Default Clean operations
Considers additional factors: UVs, materials, seams, sharp edges
More aggressive limited dissolve (1° angle)
Best for CAD/STL imports with topology issues

Recursive Processing¶

Hold ALT while clicking either cleaning button to enable recursive mode: - Automatic iteration until no more changes occur - Maximum 10 iterations to prevent infinite loops - Progress tracking with iteration details - Convergence detection when mesh is fully cleaned

Smart Interface¶

Buttons disabled when no cleaning is needed
Real-time feedback with progress bars
Non-blocking operation - Blender remains responsive
Detailed results showing what was cleaned

How to Use¶

Basic Cleaning¶

Select mesh objects that need cleaning
Open Shift+W → CLEANING
Choose cleaning mode:
Default Clean: For general cleanup
Aggressive Clean: For problematic imports
Review results in the popup dialog

Recursive Cleaning¶

Select mesh objects that need extensive cleaning
Hold ALT and click either cleaning button
Watch the progress bar show multiple iterations
Review detailed iteration results

Cleaning Operations¶

Loose Geometry Removal¶

Loose vertices: Vertices not connected to any face
Loose edges: Edges not connected to any face
Count reporting: Shows exactly how many elements were removed

Duplicate Vertex Merging¶

Threshold: 0.0001 units (very precise)
Automatic detection of vertices at identical positions
Preserves topology while cleaning redundancy

Triangle to Quad Conversion¶

Default Clean: Basic conversion (40° face/shape angles)
Aggressive Clean: Advanced conversion considering:
UV coordinates
Vertex colors
Seam edges
Sharp edges
Material boundaries

Limited Dissolve¶

Default Clean: 5° angle threshold (conservative)
Aggressive Clean: 1° angle threshold (aggressive)
Removes unnecessary edges while preserving shape
Respects material boundaries (Aggressive mode)

Normal Recalculation¶

Automatic detection of inside/outside orientation
Consistent normals across the entire mesh
BMesh-based processing for reliability

Results Dialog¶

Single Iteration Results¶

✅ Topology Cleaning Completed!

📊 Geometry Changes:
• Removed 15 vertices
• Removed 8 edges
• Removed 3 faces

🔧 Operations Performed:
1. Removed 10 loose vertices, 5 loose edges
2. Merged duplicate vertices (distance: 0.0001)
3. Converted triangles to quads
4. Applied limited dissolve (angle: 5°)
5. Recalculated normals (inside orientation)

🎯 Processed 1 mesh object(s)

Recursive Results¶

🔄 Recursive Cleaning Completed! (4 iterations)

📊 Total Changes:
• Removed 21 vertices
• Removed 15 edges
• Removed 8 faces

🔄 Iteration Details:
Iter 1: -15v, -8e, -3f
Iter 2: -5v, -2e, -1f
Iter 3: -1v, 0e, 0f
Iter 4: 0v, 0e, 0f ✓ CONVERGED

🔧 Operations Performed:
[Last iteration operations]

🎯 Processed 1 mesh object(s)

When to Use Each Mode¶

Default Clean¶

General mesh cleanup after modeling
Imported models with minor issues
Models with UVs/materials you want to preserve
Regular maintenance of complex meshes

Aggressive Clean¶

CAD model imports with topology issues
STL files from other software
Scanned geometry with artifacts
Meshes with overlapping geometry

Recursive Mode¶

Complex imported models requiring multiple passes
Heavily corrupted topology from conversion
When manual cleaning would require multiple attempts
CAD assemblies with multiple connection issues

Tips¶

Start with Default Clean - it's safer for most cases
Use Aggressive Clean for imports from CAD software
Try Recursive mode when single-pass cleaning isn't enough
Check results - the dialog shows exactly what was cleaned
Progress bars keep you informed during long operations
Buttons auto-disable when no cleaning is needed

Technical Details¶

BMesh-based operations for maximum reliability
Progress feedback prevents UI freezing
Error handling with graceful fallbacks
Memory efficient processing of large meshes
Thread-safe operations with proper cleanup