autofacemonker 0.1.0__tar.gz

autofacemonker-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: autofacemonker
+Version: 0.1.0
+Summary: Automatic 3D facial template registration via MVMP + MeshMonk
+Requires-Python: >=3.11
+Requires-Dist: embreex>=4.4.0
+Requires-Dist: meshmonk[io]>=0.3.0
+Requires-Dist: mvmp>=1.3.0
+Requires-Dist: numpy
+Requires-Dist: trimesh

autofacemonker-0.1.0/README.md

@@ -0,0 +1,92 @@
+# AutoFaceMonker
+
+Automatic 3D facial template registration using [MVMP](https://github.com/gfacchi-dev/mvmp) landmark detection and [MeshMonk](https://github.com/jsnyde0/meshmonk) nonrigid surface registration.
+
+Given a template mesh and a target 3D face scan, AutoFaceMonker detects 478 MediaPipe facial landmarks via MVMP, aligns the template with Procrustes analysis, then refines the fit with MeshMonk nonrigid registration — no manual intervention required.
+
+## Installation
+
+```bash
+pip install autofacemonker
+```
+
+Requires Python ≥ 3.11.
+
+## Quick Start
+
+```bash
+autofacemonker subject.obj -o warped.ply
+```
+
+This uses the bundled template mesh and built-in 7-point anatomical landmark correspondences.
+
+## Python API
+
+```python
+from autofacemonker import AutoFaceMonker
+
+# Use default template and correspondences
+monker = AutoFaceMonker()
+warped_vertices = monker.register("subject.obj", save_path="warped.ply")
+```
+
+### Custom template and correspondences
+
+```python
+monker = AutoFaceMonker(
+    template="my_template.ply",
+    correspondences=[
+        (0,   3572),   # nasion       → template vertex 3572
+        (4,   3589),   # nose tip     → template vertex 3589
+        (133, 2436),   # left eye     → template vertex 2436
+        (362, 4648),   # right eye    → template vertex 4648
+        (61,  2310),   # left mouth   → template vertex 2310
+        (291, 4849),   # right mouth  → template vertex 4849
+        (152, 3543),   # chin         → template vertex 3543
+    ],
+    num_iterations=200,
+)
+warped = monker.register("subject.obj")
+```
+
+## CLI
+
+```
+usage: autofacemonker <target.obj> [options]
+
+positional arguments:
+  target              Path to target .obj mesh
+
+options:
+  -t, --template      Template mesh path (default: bundled template.ply)
+  -c, --correspondences
+                      JSON file with landmark→vertex mapping
+  -o, --out           Output PLY path (default: <target>_warped.ply)
+  -n, --iterations    MeshMonk nonrigid iterations (default: 120)
+```
+
+### Correspondence JSON format
+
+```json
+{"0": 3572, "4": 3589, "133": 2436, "362": 4648, "61": 2310, "291": 4849, "152": 3543}
+```
+
+## How It Works
+
+1. **MVMP** detects 478 MediaPipe facial landmarks on the target mesh using multi-view 2D projections with 5 zone cameras.
+
+2. **Procrustes** rigidly aligns the template using the 7 anatomical landmark correspondences, computing rotation, translation, and uniform scale.
+
+3. **MeshMonk nonrigid** refines the fit by deforming the template to match the target surface over 120 iterations.
+
+## Requirements
+
+- Python ≥ 3.11
+- meshmonk ≥ 0.3.0
+- mvmp ≥ 1.3.0
+- trimesh
+- numpy
+
+## License
+
+MIT

autofacemonker-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "autofacemonker"
+version = "0.1.0"
+description = "Automatic 3D facial template registration via MVMP + MeshMonk"
+requires-python = ">=3.11"
+dependencies = [
+    "embreex>=4.4.0",
+    "meshmonk[io]>=0.3.0",
+    "mvmp>=1.3.0",
+    "numpy",
+    "trimesh",
+]
+
+[project.scripts]
+autofacemonker = "autofacemonker._cli:main"
+
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+autofacemonker = ["data/*.ply"]

autofacemonker-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

autofacemonker-0.1.0/src/autofacemonker/__init__.py

@@ -0,0 +1,6 @@
+"""AutoFaceMonker: automatic 3D facial template registration via MVMP + MeshMonk."""
+
+from ._register import AutoFaceMonker, register_template
+
+__version__ = "0.1.0"
+__all__ = ["AutoFaceMonker", "register_template"]

autofacemonker-0.1.0/src/autofacemonker/_cli.py

@@ -0,0 +1,44 @@
+"""CLI entry point for meshmonker."""
+
+import argparse
+import json
+import sys
+
+from ._register import AutoFaceMonker
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Register a facial template onto a target mesh",
+        usage="autofacemonker <target.obj> [options]",
+    )
+    parser.add_argument("target", help="Path to target .obj mesh")
+    parser.add_argument("-t", "--template", default=None,
+                        help="Template mesh path (default: bundled template.ply)")
+    parser.add_argument("-c", "--correspondences", default=None,
+                        help="JSON file with landmark→vertex mapping, e.g. {\"0\": 3572, ...}")
+    parser.add_argument("-o", "--out", default=None,
+                        help="Output PLY path (default: <target>_warped.ply)")
+    parser.add_argument("-n", "--iterations", type=int, default=120,
+                        help="MeshMonk nonrigid iterations (default: 120)")
+    args = parser.parse_args()
+
+    # Load correspondences from JSON if provided
+    corr = None
+    if args.correspondences:
+        with open(args.correspondences) as f:
+            raw = json.load(f)
+        corr = [(int(k), v) for k, v in raw.items()]
+
+    out = args.out or args.target.replace(".obj", "_warped.ply")
+
+    monker = AutoFaceMonker(
+        template=args.template,
+        correspondences=corr,
+        num_iterations=args.iterations,
+    )
+    monker.register(args.target, save_path=out)
+
+
+if __name__ == "__main__":
+    main()

autofacemonker-0.1.0/src/autofacemonker/_register.py

@@ -0,0 +1,127 @@
+"""Core: MVMP landmarks → Procrustes → MeshMonk nonrigid."""
+
+from importlib.resources import files
+
+import numpy as np
+import trimesh
+import meshmonk
+from mvmp import Facemarker
+
+# 7 verified anatomical MediaPipe landmark → template vertex correspondences
+DEFAULT_CORRESPONDENCES = [
+    (0,   3572),  # nasion
+    (4,   3589),  # nose tip
+    (133, 2436),  # left eye inner
+    (362, 4648),  # right eye inner
+    (61,  2310),  # left mouth
+    (291, 4849),  # right mouth
+    (152, 3543),  # chin
+]
+
+
+def _default_template():
+    return str(files("autofacemonker.data").joinpath("template.ply"))
+
+
+class AutoFaceMonker:
+    """Register a facial template onto target meshes using MVMP + MeshMonk.
+
+    Parameters
+    ----------
+    template : str, pathlib.Path, trimesh.Trimesh, or None
+        Template mesh. None (default) uses the bundled template.ply.
+    correspondences : list of (lmk_idx, tpl_vert_id) or None
+        Manual correspondences. None (default) uses built-in 7-keypoint set.
+    num_iterations : int
+        MeshMonk nonrigid iterations (default 120).
+    """
+
+    def __init__(self, template=None, correspondences=None, num_iterations=120):
+        tpl_path = template if isinstance(template, (str, type(None))) else None
+        if tpl_path is None:
+            tpl_path = _default_template()
+        self.template = trimesh.load(tpl_path) if tpl_path is not None else template
+
+        self.correspondences = correspondences or DEFAULT_CORRESPONDENCES
+        self.num_iterations = num_iterations
+        self._marker = Facemarker()
+
+        self._lmk_indices = np.array([c[0] for c in self.correspondences])
+        self._tpl_vids = np.array([c[1] for c in self.correspondences])
+        self._tmpl_lmks = self.template.vertices[self._tpl_vids]
+
+    def register(self, target_path, save_path=None):
+        """Register the template onto *target_path*.
+
+        Parameters
+        ----------
+        target_path : str or pathlib.Path
+            Path to the target .obj mesh.
+        save_path : str, pathlib.Path, or None
+            If provided, export the warped template as PLY.
+
+        Returns
+        -------
+        warped_vertices : np.ndarray (N, 3)
+        """
+        target = trimesh.load(str(target_path))
+
+        # ── MVMP ──────────────────────────────────────────────────────────
+        res = self._marker.predict(str(target_path))
+        lmks_full = np.full((478, 3), np.nan)
+        for k, v in res.landmarks_3d.items():
+            lmks_full[int(k)] = v
+
+        # Keep only detected landmarks
+        mask = ~np.isnan(lmks_full[self._lmk_indices, 0])
+        idx = self._lmk_indices[mask]
+        vid = self._tpl_vids[mask]
+        tmpl = self._tmpl_lmks[mask]
+        tgt = lmks_full[idx]
+
+        # ── Procrustes (rotation + translation + scale) ───────────────────
+        tmpl_c = tmpl - tmpl.mean(axis=0)
+        tgt_c = tgt - tgt.mean(axis=0)
+        H = tmpl_c.T @ tgt_c
+        U, _, Vt = np.linalg.svd(H)
+        R = Vt.T @ U.T
+        if np.linalg.det(R) < 0:
+            Vt[-1] *= -1
+            R = Vt.T @ U.T
+        scale = np.sum(np.linalg.norm(tgt_c, axis=1)) / np.sum(
+            np.linalg.norm(tmpl_c, axis=1)
+        )
+        t = tgt.mean(axis=0) - scale * R @ tmpl.mean(axis=0)
+
+        aligned = scale * (R @ self.template.vertices.T).T + t
+        aligned_n = (R @ self.template.vertex_normals.T).T
+
+        resids = np.linalg.norm(aligned[self._tpl_vids[mask]] - tgt, axis=1)
+        print(
+            f"Procrustes: {mask.sum()} lmks  scale={scale:.0f}x  "
+            f"P50={np.median(resids):.1f}mm  max={resids.max():.1f}mm"
+        )
+
+        # ── MeshMonk nonrigid ─────────────────────────────────────────────
+        tgt_features = np.column_stack([target.vertices, target.vertex_normals])
+        result = meshmonk.nonrigid_register(
+            floating_features=np.column_stack([aligned, aligned_n]),
+            target_features=tgt_features,
+            floating_faces=self.template.faces,
+            target_faces=target.faces,
+            num_iterations=self.num_iterations,
+        )
+
+        if save_path:
+            out = self.template.copy()
+            out.vertices = result.aligned_vertices
+            out.export(str(save_path))
+            print(f"Saved {save_path}")
+
+        return result.aligned_vertices
+
+
+def register_template(target_path, template=None, correspondences=None, save_path=None):
+    """Convenience function.  See ``AutoFaceMonker`` for parameters."""
+    m = AutoFaceMonker(template=template, correspondences=correspondences)
+    return m.register(target_path, save_path=save_path)

autofacemonker-0.1.0/src/autofacemonker.egg-info/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: autofacemonker
+Version: 0.1.0
+Summary: Automatic 3D facial template registration via MVMP + MeshMonk
+Requires-Python: >=3.11
+Requires-Dist: embreex>=4.4.0
+Requires-Dist: meshmonk[io]>=0.3.0
+Requires-Dist: mvmp>=1.3.0
+Requires-Dist: numpy
+Requires-Dist: trimesh

autofacemonker-0.1.0/src/autofacemonker.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/autofacemonker/__init__.py
+src/autofacemonker/_cli.py
+src/autofacemonker/_register.py
+src/autofacemonker.egg-info/PKG-INFO
+src/autofacemonker.egg-info/SOURCES.txt
+src/autofacemonker.egg-info/dependency_links.txt
+src/autofacemonker.egg-info/entry_points.txt
+src/autofacemonker.egg-info/requires.txt
+src/autofacemonker.egg-info/top_level.txt
+src/autofacemonker/data/template.ply

autofacemonker-0.1.0/src/autofacemonker.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

autofacemonker-0.1.0/src/autofacemonker.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+autofacemonker = autofacemonker._cli:main

autofacemonker-0.1.0/src/autofacemonker.egg-info/requires.txt

@@ -0,0 +1,5 @@
+embreex>=4.4.0
+meshmonk[io]>=0.3.0
+mvmp>=1.3.0
+numpy
+trimesh

autofacemonker-0.1.0/src/autofacemonker.egg-info/top_level.txt

@@ -0,0 +1 @@
+autofacemonker