[mimosapudical]

Description

Adds a canonical 3D surgical deformation bridge that replaces independent per-view 2D edits with one shared anatomy-space deformation, then reprojects that same edit into each camera view.

This extends #418 beyond reconstruction alone: MediaPipe observations are fit to one canonical face geometry, one 3D surgery is applied, and front / three-quarter / profile outputs become projections of the same underlying intervention.

Type of change

• Bug fix
• New feature
• New procedure preset
• Breaking change
• Documentation update
• Tests / CI improvement

What is included

• full 3D scaled-orthographic camera fitting;
• dependency-free MediaPipe-topology canonical backend for tests/demos;
• optional official FLAME backend using user-supplied FLAME assets and MediaPipe→FLAME correspondence;
• low-dimensional FLAME identity fitting;
• anatomy-specific canonical 3D surgical handles;
• Laplacian deformation with locality regularization;
• matrix-free preconditioned conjugate gradient for FLAME-scale meshes;
• projected vertex-color PLY export;
• explicit Shared 3D capability boundaries instead of silent 2D fallback;
• Gradio integration for Independent 2D vs Shared 3D comparison.

Supported 3D procedures in this first version:

• rhinoplasty
• alarplasty
• mentoplasty
• genioplasty

Validation

Held-out evaluation uses an independent analytic Gaussian 3D deformation field for synthetic ground truth, so the target is not generated by the same Laplacian operator used by Shared 3D.

The canonical fit uses training views only. The held-out post-op target is never used by fitting or deformation.

27-case validation

Across:

• 3 procedures: mentoplasty, genioplasty, rhinoplasty
• 3 intensities: 40, 60, 100
• 3 held-out yaws: 20°, 45°, 85°

with sweep-selected lambda_smooth=30, lambda_locality=0.3:

Procedure	Wins	Mean relative held-out NME change
Mentoplasty	9 / 9	-12.0%
Genioplasty	9 / 9	-47.2%
Rhinoplasty	6 / 9	-1.1%
Overall	24 / 27	-20.1%

Maximum synthetic camera-rotation error: ~0.0001°.

The three losses are all rhinoplasty at 20° yaw, where Shared 3D is ~23% worse than the independent 2D preset. The same rhinoplasty deformation improves at 45° and 85°. This limitation is documented rather than hidden by procedure-specific tuning.

A focused 70° / 80° held-out matrix gives 6 / 6 wins with ~23.7% mean relative NME improvement.

How has this been tested?

Added 24 focused Shared 3D tests covering:

• official FLAME asset loading (JSON / NPZ correspondence);
• 0° / 30° / 60° / 80° camera-yaw recovery;
• shared multi-view fitting;
• OBJ and projected-color PLY export;
• surgical handle semantics;
• matrix-free Laplacian equivalence to the dense reference;
• mapped handles on arbitrary mesh topology;
• Shared 3D / Independent 2D API behavior.

These pass on Python 3.10, 3.11, and 3.12.

Static checks on the validated branch:

• Ruff lint: pass
• Ruff format: pass
• mypy: pass
• pre-commit: pass

The repository-wide suite reaches 3579 passed / 1 unrelated existing CodeFormer warning-capture failure on each Python version. This PR does not touch the failing postprocess test or CodeFormer path.

Contributor attribution

This PR also adds mimosapudical to CONTRIBUTORS.md for the canonical 3D surgical deformation bridge, FLAME integration, and held-out multi-view validation.

The repository's CONTRIBUTING.md recognition table classifies feature-module contributions as co-author-level contributions for the project paper; final publication authorship remains subject to maintainer acceptance of the contribution.

Checklist

• My code follows the project's style guidelines
• I have added tests that cover my changes
• New Shared 3D tests pass on Python 3.10 / 3.11 / 3.12
• I have updated documentation
• My changes generate no new Ruff or mypy warnings
• Repository-wide suite is fully green (one unrelated existing CodeFormer warning-capture test remains)

Scope

Intentionally out of scope:

• 3DGS / NeRF
• FEM
• new diffusion-model training
• full phone-video reconstruction
• UV-unwrapped or multi-view photometric texture fitting
• clinical calibration of displacement magnitudes

Why this is useful

This changes the surgical representation from independent per-view 2D edits to one shared canonical 3D edit, so multi-angle results are linked by geometry instead of by repeated heuristics.

Introduced a patient-specific canonical 3D surgical deformation pathway that applies one anatomy-aware edit across views and improves held-out-view geometric consistency over independent 2D surgery.

Related issues

Closes #418.