feat(manipulation): modularize NumPy RBF pre-warp stage for TPS pipeline PR#4

[Flames4fun]

Description

Implements PR4 scope by extracting the NumPy RBF deformation into an explicit, reusable
pre-warp stage while preserving current behavior.

This keeps TPS pipeline work incremental and auditable:

• apply_procedure_preset(...) now routes through a dedicated modular RBF stage, unless a
  data-driven displacement model path is provided.
• No ONNX artifact expansion, CLI productization, or packaging changes are included in this PR.

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 explicit RBF pre-warp stage API in landmarkdiff/manipulation.py:
  • build_rbf_prewarp_handles(...)
  • apply_rbf_prewarp_stage(...)
• Extracted execution helper:
  • _apply_rbf_handles_to_face(...)
• Refactored apply_procedure_preset(...) to call apply_rbf_prewarp_stage(...) on the NumPy
  RBF path.
• Preserved data-driven path behavior (displacement_model_path) and fallback semantics.
• Clarified API contract for image_size in the modular RBF path:
  • Treated as a legacy compatibility argument for this route.
  • Added an explicit docstring and docs note.
• Clarified confidence semantics:
  • build_rbf_prewarp_handles(...) is confidence-agnostic.
  • apply_rbf_prewarp_stage(...) applies landmark-confidence weighting.
• Added focused parity and regression tests:
  • New file: tests/test_manipulation_rbf_stage.py
  • Parity vs. the legacy inline algorithm across all procedures at intensities 0, 50, and 100
  • Clinical flags parity
  • Regional intensity parity
  • Handle-builder parity
  • Routing tests in apply_procedure_preset(...)
  • Contract test for image_size compatibility behavior in the RBF path
  • Contract test for a confidence-agnostic builder vs. a confidence-weighted stage
• Updated API docs:
  • docs/api/manipulation.md

Testing

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

Scoped checks executed locally:

python -m ruff check landmarkdiff/manipulation.py tests/test_manipulation.py tests/test_manipulation_extended.py tests/test_manipulation_rbf_stage.py tests/test_inference_extended.py
python -m ruff format --check landmarkdiff/manipulation.py tests/test_manipulation_rbf_stage.py
python -m mypy landmarkdiff/manipulation.py --ignore-missing-imports
python -m pytest -q tests/test_manipulation.py tests/test_manipulation_extended.py tests/test_manipulation_rbf_stage.py -p no:faulthandler
python -m pytest -q tests/test_inference_extended.py -p no:faulthandler

Results:

• 194 passed (test_manipulation* + new RBF stage suite)
• 37 passed (test_inference_extended.py)

Screenshots / outputs

N/A (backend modularization + tests/docs only).

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

Related issues: #374
@dreamlessx

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!