feat(export): Add optional mesh retopology step

[hummat]

Summary

Add an optional retopology step after marching cubes extraction to produce clean quad-dominant meshes with proper edge flow, replacing the current quadric simplification when enabled.

Motivation

Marching cubes output has uniform triangle density and staircase artifacts on oblique surfaces. Quadric edge collapse (current simplification) reduces face count but doesn't improve topology. Retopology creates clean quad meshes with:

• Edge loops following surface features
• Adaptive density based on curvature
• Better downstream usability (animation, LODs, editing)

Proposed Design

Pipeline Integration

MC (2M tris) → [remove small components] → retopo (quads) → triangulate → texture → export
              ↓
         [if retopo=off, fall back to quadric simplify as today]

Key decisions:

• Retopo runs on raw MC output (not after simplify)—preserves geometric detail for better topology reconstruction
• Retopo replaces simplify when enabled, not supplements it
• Output triangulated before texturing (xatlas/ray casting need tris; quad topology benefits preserved in edge structure)
• Small component removal automatic (handles SDF floaters)

CLI Interface

--retopo [off|instant|quadriflow]   # default: off
--retopo-target              # target face count, default: 50000

File Flow

mesh.ply          # raw MC output (existing)
mesh_retopo.ply   # retopo output (new, if enabled)
mesh.obj          # textured final (existing)

---

Recommended Tools

Primary: Instant Meshes

• License: MIT
• Pros: Fast, good quad quality, handles large meshes (~millions), small binary (~5MB), no deps
• Cons: Less robust on complex topology than QuadriFlow
• Install: Pre-built binaries or compile from source
• CLI: instant-meshes input.ply -o output.ply -f 50000
• Repo: https://github.com/wjakob/instant-meshes

Alternative: QuadriFlow

• License: MIT
• Pros: More robust on complex geometry, sharp edge preservation (-sharp)
• Cons: Slower, requires compilation
• CLI: quadriflow -i input.ply -o output.ply -f 50000 -sharp
• Repo: https://github.com/hjwdzh/QuadriFlow

Fallback: Blender QuadriFlow

• Same algorithm as QuadriFlow, accessible via Blender Python API
• Useful if users already have Blender installed

---

Future Extensions: Learning-Based Methods

These methods produce artist-like topology but have limitations. Worth monitoring for future integration:

MeshAnythingV2

• Output limit: 1,600 faces (low-poly only)
• Strength: Artist-quality topology for game LODs, stylized assets
• Use case: When you need very low poly with clean topology
• Repo: https://github.com/buaacyw/MeshAnythingV2
• Paper: https://arxiv.org/abs/2408.02555

MeshGPT

• Output limit: ~800 faces
• Strength: Autoregressive mesh generation, learns artist patterns
• Use case: Research, generative modeling
• Repo: https://github.com/lucidrains/meshgpt-pytorch (third-party reimplementation; no official code release)
• Paper: https://arxiv.org/abs/2311.15475

Meshtron

• Output limit: ~64k faces (highest among learned methods)
• Strength: Could handle practical mesh sizes
• Status: No public code yet (as of Jan 2026)
• Paper: https://arxiv.org/abs/2412.09548

Integration criteria for learned methods:

• Output limit ≥50k faces (our default target)
• Reasonable inference time (<1 min for typical mesh)
• Stable public release with clear license

---

Implementation Notes

1. Dependency handling: Bundle Instant Meshes binary in Docker image; document manual install for native use
2. Triangulation: Split quads along shorter diagonal before texture step
3. Small component removal: Use PyMeshLab (already a dependency) before retopo
4. No mesh repair needed: MC output is manifold by construction

Tasks

• Add --retopo and --retopo-target flags to run.sh
• Create scripts/retopo.sh wrapper for Instant Meshes / QuadriFlow
• Add small component removal step (PyMeshLab)
• Add quad triangulation step
• Update export.sh to route through retopo when enabled
• Update Docker image with Instant Meshes binary
• Add to README
• Add tests

References

• Instant Meshes paper: https://igl.ethz.ch/projects/instant-meshes/
• QuadriFlow paper: https://stanford.edu/~jingweih/papers/quadriflow/

Related Issues

• feat(export): PBR-ish texture extraction and BRDF-aware training #11 — PBR texture extraction (benefits from clean topology)