PR3: TPS Pipeline: add MediaPipe landmark runtime wrapper

[Flames4fun]

Description

Adds a stable MediaPipe runtime wrapper for TPS landmark extraction and integrates it into the TPS inference path with explicit failure handling, while preserving current TPS behavior and compatibility.

Type of change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• New procedure preset
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Tests or CI

Changes

• Added TPSLandmarkResult in landmarkdiff/landmarks.py with explicit fields:
  • coords (float32, shape (478, 3))
  • confidence
  • image_size ((width, height))
  • detected
  • reason
• Added extract_tps_landmarks(...) in landmarkdiff/landmarks.py as a MediaPipe-agnostic wrapper.
• Added controlled failure reasons:
  • no_face_detected
  • invalid_image
  • extractor_error
  • invalid_landmark_shape
  • invalid_landmark_values
• Updated TPS path in landmarkdiff/inference.py to use extract_tps_landmarks(...) with minimal integration changes.
• Preserved no-face observable behavior: ValueError("No face detected in image.").
• Added .hypothesis/ to .gitignore.
• Added wrapper unit/parity tests in tests/test_landmarks.py.
• Added TPS integration tests in tests/test_inference_extended.py:
  • wrapper is used in TPS generate path
  • no-face is handled predictably
  • extractor errors are handled predictably

Testing

• ruff check landmarkdiff/ scripts/ tests/ passes
• mypy landmarkdiff/ --ignore-missing-imports passes
• pytest tests/ passes
• New tests added for new functionality (if applicable)

Validation run:

• python -m pytest -q tests/test_tps_onnx_export.py -rs -p no:faulthandler → 6 passed
• pytest -q tests/test_landmarks.py tests/test_inference_extended.py -p no:faulthandler → 48 passed

Screenshots / outputs

N/A (runtime wrapper + inference integration + tests; no UI changes).

Checklist

• My code follows the project's style (ruff, 100 char line length)
• I have added tests that prove my fix or feature works
• New and existing tests pass locally
• I have updated documentation if needed

@dreamlessx

[codecov]

Codecov Report

❌ Patch coverage is 85.10638% with 7 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
landmarkdiff/landmarks.py	82.05%	7 Missing ⚠️

📢 Thoughts on this report? Let us know!

[dreamlessx]

Excellent work @Flames4fun! This is a really clean contribution:

• TPSLandmarkResult — proper dataclass with explicit detected/reason fields and NaN/shape validation. Much better than raw None checks.
• Dependency injection via extractor parameter makes testing straightforward.
• 7 comprehensive tests covering valid, no-face, invalid-image, extractor-error, and legacy parity.
• Backward-compatible — to_face_landmarks() bridges to the existing pipeline.

One minor note for a follow-up: the if face is None check on line ~560 of inference.py is now redundant since the wrapper already handles that case and raises before reaching it. Not blocking — merging now.

Great third contribution! 🔥