mvmp 1.3.1

3D Multi-View MediaPipe - Facial landmark detection for 3D meshes

MVMP: 3D Multi-View MediaPipe

Description

MVMP detects 478 MediaPipe-compatible 3D facial landmarks on textured meshes. It renders the mesh from 5 deterministic zone-based viewpoints (front, left/right sides, upper/lower), detects 2D landmarks with MediaPipe, and back-projects each to the mesh surface via raycasting. An optional Fibonacci-sphere auto-alignment phase orients the face toward +Z before detection.

Supported mesh formats: .obj, .ply, .stl, .gltf, .glb, .off

Installation

pip install mvmp

The MediaPipe Face Landmarker model is bundled in the package.

From Source

git clone https://github.com/gfacchi-dev/mvmp.git
cd mvmp
pip install .

Usage

Python API

from mvmp import Facemarker

marker = Facemarker()
result = marker.predict("path/to/mesh.obj")
print(result)  # FacemarkerResult(478 landmarks, 478 vertex indices)

landmarks_3d = result.landmarks_3d              # dict[int, [x, y, z]]
vertex_indices = result.closest_vertices_ids    # dict[int, int]

result.save_json("landmarks.json")

Quiet mode / debug output

marker = Facemarker(verbose=False)

# Save per-zone renders and auto-align report
marker = Facemarker(debug_output_dir="debug/")

Camera distance

# Move cameras closer (0.5×) or farther (2×)
marker = Facemarker(camera_distance_multiplier=0.8)

Disable auto-alignment

# Skip Fibonacci-sphere alignment (mesh assumed to already face +Z)
marker = Facemarker(auto_orient=False)

Command Line

mvmp path/to/mesh.obj -o output/

# Process a folder
mvmp meshes/ -o results/

# With debug renders
mvmp mesh.obj --debug debug_output/

# Closer camera, no auto-align
mvmp mesh.obj --camera-distance 0.8 --no-auto-orient

Arguments:

• path: Mesh file or directory
• -o, --output-path: Output directory (default: ./output/)
• --debug: Save debug renders and auto-align report to this directory
• --camera-distance: Camera distance multiplier (default: 1.0)
• --no-auto-orient: Skip Fibonacci-sphere auto-alignment

Output Format

{
  "coordinates": {"0": [x, y, z], ...},
  "closest_vertex_indexes": {"0": 12345, ...}
}

Contributing

1. Fork the repository and create a feature branch.
2. Make your changes with clear commit messages.
3. Open a pull request.

License

MIT License

Contact

Questions or suggestions? Open an issue on GitHub.