pyfaceau 1.3.0__tar.gz → 1.3.3__tar.gz

pyfaceau-1.3.3/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: pyfaceau
+Version: 1.3.3
+Summary: Pure Python OpenFace 2.2 AU extraction with CLNF landmark refinement
+Home-page: https://github.com/johnwilsoniv/face-analysis
+Author: John Wilson
+Author-email: 
+License: CC BY-NC 4.0
+Project-URL: Homepage, https://github.com/johnwilsoniv/pyfaceau
+Project-URL: Documentation, https://github.com/johnwilsoniv/pyfaceau
+Project-URL: Repository, https://github.com/johnwilsoniv/pyfaceau
+Project-URL: Bug Tracker, https://github.com/johnwilsoniv/pyfaceau/issues
+Keywords: facial-action-units,openface,computer-vision,facial-analysis,emotion-recognition
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: opencv-python>=4.5.0
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: onnxruntime>=1.10.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: scikit-learn>=1.0.0
+Requires-Dist: tqdm>=4.62.0
+Requires-Dist: pyfhog>=0.1.0
+Requires-Dist: pyclnf>=0.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: flake8>=4.0.0; extra == "dev"
+Provides-Extra: accel
+Requires-Dist: onnxruntime-coreml>=1.10.0; extra == "accel"
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# pyfaceau
+
+Python implementation of OpenFace 2.2's Facial Action Unit extraction pipeline.
+
+## Installation
+
+```bash
+pip install pyfaceau
+```
+
+## Usage
+
+```python
+from pyfaceau import FaceAnalyzer
+
+analyzer = FaceAnalyzer()
+result = analyzer.analyze(image)
+
+print(result.au_intensities)  # 17 action unit intensities
+print(result.landmarks)       # 68 facial landmarks
+print(result.pose)            # head pose
+```
+
+## What it does
+
+- Extracts 17 facial action units (AU01, AU02, AU04, AU05, AU06, AU07, AU09, AU10, AU12, AU14, AU15, AU17, AU20, AU23, AU25, AU26, AU45)
+- Detects 68 facial landmarks via [pyclnf](https://github.com/johnwilsoniv/pyclnf)
+- Estimates 3D head pose
+- No C++ compilation required
+
+## Citation
+
+If you use this in research, please cite:
+
+> Wilson IV, J., Rosenberg, J., Gray, M. L., & Razavi, C. R. (2025). A split-face computer vision/machine learning assessment of facial paralysis using facial action units. *Facial Plastic Surgery & Aesthetic Medicine*. https://doi.org/10.1177/26893614251394382
+
+## License
+
+CC BY-NC 4.0 — free for non-commercial use with attribution.

pyfaceau-1.3.3/README.md

@@ -0,0 +1,39 @@
+# pyfaceau
+
+Python implementation of OpenFace 2.2's Facial Action Unit extraction pipeline.
+
+## Installation
+
+```bash
+pip install pyfaceau
+```
+
+## Usage
+
+```python
+from pyfaceau import FaceAnalyzer
+
+analyzer = FaceAnalyzer()
+result = analyzer.analyze(image)
+
+print(result.au_intensities)  # 17 action unit intensities
+print(result.landmarks)       # 68 facial landmarks
+print(result.pose)            # head pose
+```
+
+## What it does
+
+- Extracts 17 facial action units (AU01, AU02, AU04, AU05, AU06, AU07, AU09, AU10, AU12, AU14, AU15, AU17, AU20, AU23, AU25, AU26, AU45)
+- Detects 68 facial landmarks via [pyclnf](https://github.com/johnwilsoniv/pyclnf)
+- Estimates 3D head pose
+- No C++ compilation required
+
+## Citation
+
+If you use this in research, please cite:
+
+> Wilson IV, J., Rosenberg, J., Gray, M. L., & Razavi, C. R. (2025). A split-face computer vision/machine learning assessment of facial paralysis using facial action units. *Facial Plastic Surgery & Aesthetic Medicine*. https://doi.org/10.1177/26893614251394382
+
+## License
+
+CC BY-NC 4.0 — free for non-commercial use with attribution.

{pyfaceau-1.3.0 → pyfaceau-1.3.3}/pyfaceau/alignment/calc_params.py

@@ -17,6 +17,7 @@ Date: 2025-10-29
 import numpy as np
 from scipy import linalg
 import cv2
+import os
 
 # Try to import Cython-optimized rotation update for 99.9% accuracy
 try:
@@ -26,10 +27,12 @@ try:
     sys.path.insert(0, str(Path(__file__).parent.parent))
     from cython_rotation_update import update_rotation_cython
     CYTHON_AVAILABLE = True
-    print("Cython rotation update module loaded - targeting 99.9% accuracy")
+    if os.environ.get('PYFACEAU_VERBOSE', '0') == '1':
+        print("Cython rotation update module loaded - targeting 99.9% accuracy")
 except ImportError:
     CYTHON_AVAILABLE = False
-    print("Warning: Cython rotation update not available - using Python (99.45% accuracy)")
+    if os.environ.get('PYFACEAU_VERBOSE', '0') == '1':
+        print("Warning: Cython rotation update not available - using Python (99.45% accuracy)")
 
 # Try to import Numba JIT-accelerated CalcParams functions for 2-5x speedup
 try:
@@ -41,7 +44,6 @@ try:
     NUMBA_AVAILABLE = True
 except ImportError:
     NUMBA_AVAILABLE = False
-    print("Warning: Numba JIT accelerator not available - using standard Python (slower)")
 
 
 class CalcParams:
@@ -97,10 +99,10 @@ class CalcParams:
     @staticmethod
     def rotation_matrix_to_euler(R):
         """
-        Convert 3x3 rotation matrix to Euler angles using robust quaternion extraction
+        Convert 3x3 rotation matrix to Euler angles
 
-        Matches RotationMatrix2Euler() from RotationHelpers.h
-        Uses Shepperd's method for robust quaternion extraction (handles all cases)
+        EXACTLY matches RotationMatrix2Euler() from RotationHelpers.h lines 73-90
+        Uses simple quaternion extraction (assumes trace+1 > 0)
 
         Args:
             R: 3x3 rotation matrix
@@ -108,47 +110,34 @@ class CalcParams:
         Returns:
             (rx, ry, rz) Euler angles in radians
         """
-        # Robust quaternion extraction using Shepperd's method
-        # This handles all rotation cases without singularities
-        trace = R[0,0] + R[1,1] + R[2,2]
-
-        if trace > 0:
-            # Standard case: trace is positive
-            s = np.sqrt(trace + 1.0) * 2.0  # s = 4*q0
-            q0 = 0.25 * s
-            q1 = (R[2,1] - R[1,2]) / s
-            q2 = (R[0,2] - R[2,0]) / s
-            q3 = (R[1,0] - R[0,1]) / s
-        elif (R[0,0] > R[1,1]) and (R[0,0] > R[2,2]):
-            # q1 is largest component
-            s = np.sqrt(1.0 + R[0,0] - R[1,1] - R[2,2]) * 2.0  # s = 4*q1
-            q0 = (R[2,1] - R[1,2]) / s
-            q1 = 0.25 * s
-            q2 = (R[0,1] + R[1,0]) / s
-            q3 = (R[0,2] + R[2,0]) / s
-        elif R[1,1] > R[2,2]:
-            # q2 is largest component
-            s = np.sqrt(1.0 + R[1,1] - R[0,0] - R[2,2]) * 2.0  # s = 4*q2
-            q0 = (R[0,2] - R[2,0]) / s
-            q1 = (R[0,1] + R[1,0]) / s
-            q2 = 0.25 * s
-            q3 = (R[1,2] + R[2,1]) / s
-        else:
-            # q3 is largest component
-            s = np.sqrt(1.0 + R[2,2] - R[0,0] - R[1,1]) * 2.0  # s = 4*q3
-            q0 = (R[1,0] - R[0,1]) / s
-            q1 = (R[0,2] + R[2,0]) / s
-            q2 = (R[1,2] + R[2,1]) / s
-            q3 = 0.25 * s
-
-        # Quaternion to Euler angles
+        # EXACT C++ implementation from RotationHelpers.h
+        # float q0 = sqrt(1 + rotation_matrix(0, 0) + rotation_matrix(1, 1) + rotation_matrix(2, 2)) / 2.0f;
+        q0 = np.sqrt(1.0 + R[0,0] + R[1,1] + R[2,2]) / 2.0
+
+        # float q1 = (rotation_matrix(2, 1) - rotation_matrix(1, 2)) / (4.0f*q0);
+        q1 = (R[2,1] - R[1,2]) / (4.0 * q0)
+        # float q2 = (rotation_matrix(0, 2) - rotation_matrix(2, 0)) / (4.0f*q0);
+        q2 = (R[0,2] - R[2,0]) / (4.0 * q0)
+        # float q3 = (rotation_matrix(1, 0) - rotation_matrix(0, 1)) / (4.0f*q0);
+        q3 = (R[1,0] - R[0,1]) / (4.0 * q0)
+
+        # Quaternion to Euler angles (exactly as in C++)
+        # float t1 = 2.0f * (q0*q2 + q1*q3);
         t1 = 2.0 * (q0*q2 + q1*q3)
-        t1 = np.clip(t1, -1.0, 1.0)  # Handle precision issues
+        # if (t1 > 1) t1 = 1.0f; if (t1 < -1) t1 = -1.0f;
+        if t1 > 1.0:
+            t1 = 1.0
+        if t1 < -1.0:
+            t1 = -1.0
 
+        # float yaw = asin(t1);
         yaw = np.arcsin(t1)
+        # float pitch = atan2(2.0f * (q0*q1 - q2*q3), q0*q0 - q1*q1 - q2*q2 + q3*q3);
         pitch = np.arctan2(2.0 * (q0*q1 - q2*q3), q0*q0 - q1*q1 - q2*q2 + q3*q3)
+        # float roll = atan2(2.0f * (q0*q3 - q1*q2), q0*q0 + q1*q1 - q2*q2 - q3*q3);
         roll = np.arctan2(2.0 * (q0*q3 - q1*q2), q0*q0 + q1*q1 - q2*q2 - q3*q3)
 
+        # return cv::Vec3f(pitch, yaw, roll);
         return np.array([pitch, yaw, roll], dtype=np.float32)
 
     @staticmethod
@@ -381,15 +370,15 @@ class CalcParams:
             euler_new = update_rotation_cython(euler_current, delta_rotation)
             updated_global[1:4] = euler_new
         else:
-            # Fallback to Python implementation (99.45% accuracy)
+            # Fallback to Python implementation matching C++ EXACTLY
             # Get current rotation matrix
             euler_current = params_global[1:4]
             R1 = self.euler_to_rotation_matrix(euler_current)
 
             # Construct incremental rotation matrix R'
-            # R' = [1,   -wz,   wy ]
-            #      [wz,   1,   -wx ]
-            #      [-wy,  wx,   1  ]
+            # R2(1,2) = -1.0*(R2(2,1) = delta_p.at<float>(1,0));  // wx
+            # R2(2,0) = -1.0*(R2(0,2) = delta_p.at<float>(2,0));  // wy
+            # R2(0,1) = -1.0*(R2(1,0) = delta_p.at<float>(3,0));  // wz
             R2 = np.eye(3, dtype=np.float32)
             R2[1, 2] = -delta_p[1]  # -wx
             R2[2, 1] = delta_p[1]   # wx
@@ -404,10 +393,12 @@ class CalcParams:
             # Combine rotations
             R3 = R1 @ R2
 
-            # Convert back to Euler angles using quaternion (matching C++ RotationHelpers.h)
-            # C++ uses: RotationMatrix2AxisAngle then AxisAngle2Euler (via quaternion)
-            # Direct quaternion conversion matches C++ better than axis-angle via OpenCV
-            euler_new = self.rotation_matrix_to_euler(R3)
+            # C++ uses: RotationMatrix2AxisAngle -> AxisAngle2Euler
+            # cv::Vec3f axis_angle = Utilities::RotationMatrix2AxisAngle(R3);
+            # cv::Vec3f euler = Utilities::AxisAngle2Euler(axis_angle);
+            # This is: Rodrigues(R3) -> Rodrigues(axis_angle) -> RotationMatrix2Euler
+            axis_angle = self.rotation_matrix_to_axis_angle(R3)
+            euler_new = self.axis_angle_to_euler(axis_angle)
 
             # Handle numerical instability
             if np.any(np.isnan(euler_new)):

{pyfaceau-1.3.0 → pyfaceau-1.3.3}/pyfaceau/alignment/face_aligner.py

@@ -37,7 +37,7 @@ class OpenFace22FaceAligner:
     # Testing shows removing eyes improves STABILITY but ruins MAGNITUDE (31° vs 5°)
     RIGID_INDICES = [1, 2, 3, 4, 12, 13, 14, 15, 27, 28, 29, 31, 32, 33, 34, 35, 36, 39, 40, 41, 42, 45, 46, 47]
 
-    def __init__(self, pdm_file: str, sim_scale: float = 0.7, output_size: Tuple[int, int] = (112, 112)):
+    def __init__(self, pdm_file: str, sim_scale: float = 0.7, output_size: Tuple[int, int] = (112, 112), y_offset: float = 0.0):
         """
         Initialize face aligner with PDM reference shape
 
@@ -45,9 +45,12 @@ class OpenFace22FaceAligner:
             pdm_file: Path to PDM model file (e.g., "pdm_68_multi_pie.txt")
             sim_scale: Scaling factor for reference shape (default: 0.7 for AU analysis)
             output_size: Output aligned face size in pixels (default: 112×112)
+            y_offset: Y-axis offset for centering (negative shifts face UP, default: 0.0)
+                      Note: Non-zero values can disrupt HOG feature alignment with C++ models.
         """
         self.sim_scale = sim_scale
         self.output_width, self.output_height = output_size
+        self.y_offset = y_offset
 
         # Load PDM and extract mean shape
         print(f"Loading PDM from: {pdm_file}")
@@ -56,15 +59,17 @@ class OpenFace22FaceAligner:
         # Preprocess mean shape: 204 values (68 landmarks × 3D) → 68 landmarks × 2D
         # OpenFace C++ logic (Face_utils.cpp:112-119):
         # 1. Scale mean shape by sim_scale
-        # 2. Discard Z component (take first 136 values = all X,Y coords)
-        # 3. Reshape to (68, 2) format
+        # 2. Extract X and Y coordinates (grouped format)
+        # 3. Stack to (68, 2) format
         #
-        # CRITICAL: PDM stores as: [x0, y0, x1, y1, ..., x67, y67, z0, z1, ..., z67]
-        # NOT as: [x0, y0, z0, x1, y1, z1, ...]
-        # So we must: take first 136 values (all X,Y), then reshape
-        mean_shape_scaled = pdm.mean_shape * sim_scale  # (204, 1)
-        mean_shape_2d = mean_shape_scaled[:136]  # First 136 = all X,Y values
-        self.reference_shape = mean_shape_2d.reshape(68, 2)  # (68, 2)
+        # CRITICAL FIX: PDM stores as GROUPED format:
+        #   [x0, x1, ..., x67, y0, y1, ..., y67, z0, z1, ..., z67]
+        # NOT interleaved: [x0, y0, x1, y1, ...]
+        # So we must: take first 68 as X, next 68 as Y, stack them
+        mean_shape_scaled = pdm.mean_shape.flatten() * sim_scale  # (204,)
+        x_coords = mean_shape_scaled[:68]    # First 68 = all X values
+        y_coords = mean_shape_scaled[68:136] # Next 68 = all Y values
+        self.reference_shape = np.column_stack([x_coords, y_coords])  # (68, 2)
 
         print(f"Face aligner initialized")
         print(f"  Sim scale: {sim_scale}")
@@ -74,7 +79,8 @@ class OpenFace22FaceAligner:
 
     def align_face(self, image: np.ndarray, landmarks_68: np.ndarray,
                    pose_tx: float, pose_ty: float, p_rz: float = 0.0,
-                   apply_mask: bool = False, triangulation=None) -> np.ndarray:
+                   apply_mask: bool = False, triangulation=None,
+                   mask_style: str = 'detected') -> np.ndarray:
         """
         Align face to canonical 112×112 reference frame
 
@@ -86,6 +92,8 @@ class OpenFace22FaceAligner:
             p_rz: Pose rotation Z in radians (from OpenFace params_global[3])
             apply_mask: If True, mask out regions outside the face (like OpenFace C++)
             triangulation: TriangulationParser object (required if apply_mask=True)
+            mask_style: 'detected' uses warped detected landmarks (C++ OpenFace style),
+                       'reference' uses reference shape (legacy behavior)
 
         Returns:
             aligned_face: 112×112 aligned face image (BGR format)
@@ -100,22 +108,12 @@ class OpenFace22FaceAligner:
         source_rigid = self._extract_rigid_points(landmarks_68)
         dest_rigid = self._extract_rigid_points(self.reference_shape)
 
-        # Compute scale (no rotation from Kabsch) - matching working commit approach
-        scale_identity = self._compute_scale_only(source_rigid, dest_rigid)
-        scale = scale_identity
-
-        # Apply INVERSE of p_rz rotation
-        # p_rz describes rotation FROM canonical TO tilted
-        # We need rotation FROM tilted TO canonical, which is -p_rz
-        angle = -p_rz
-        cos_a = np.cos(angle)
-        sin_a = np.sin(angle)
-
-        R = np.array([[cos_a, -sin_a],
-                      [sin_a,  cos_a]], dtype=np.float32)
-
-        # Combine scale and rotation
-        scale_rot_matrix = scale * R
+        # Match C++ exactly: use AlignShapesWithScale to compute BOTH scale and rotation
+        # via Kabsch algorithm. This does NOT use p_rz - the rotation comes from
+        # finding the optimal alignment between source and destination rigid points.
+        # C++ code: Face_utils.cpp line 127:
+        #   cv::Matx22f scale_rot_matrix = Utilities::AlignShapesWithScale(source_landmarks, destination_landmarks);
+        scale_rot_matrix = self._align_shapes_with_scale(source_rigid, dest_rigid)
 
         # Build 2×3 affine warp matrix using pose translation
         warp_matrix = self._build_warp_matrix(scale_rot_matrix, pose_tx, pose_ty)
@@ -133,8 +131,20 @@ class OpenFace22FaceAligner:
             if triangulation is None:
                 raise ValueError("triangulation required when apply_mask=True")
 
-            # Transform landmarks to aligned space
-            aligned_landmarks = self._transform_landmarks(landmarks_68, warp_matrix)
+            if mask_style == 'detected':
+                # C++ OpenFace style: transform detected landmarks by warp matrix
+                # This adapts the mask per-frame based on actual face shape
+                # Reference: Face_utils.cpp::AlignFaceMask() lines 186-209
+                warp_2d = scale_rot_matrix
+                translation = np.array([warp_matrix[0, 2], warp_matrix[1, 2]])
+                aligned_landmarks = landmarks_68 @ warp_2d.T + translation
+            else:
+                # Legacy style: use reference shape (consistent mask across frames)
+                center = np.array([self.output_width / 2, self.output_height / 2])
+                aligned_landmarks = self.reference_shape + center
+                # Apply correction shift for reference shape centering
+                aligned_landmarks[:, 0] += 5.0
+                aligned_landmarks[:, 1] += 3.0
 
             # Adjust eyebrow landmarks upward to include forehead (like C++)
             # Indices 17-26 are eyebrows, 0 and 16 are jaw corners
@@ -154,6 +164,80 @@ class OpenFace22FaceAligner:
 
         return aligned_face
 
+    def align_face_with_matrix(self, image: np.ndarray, landmarks_68: np.ndarray,
+                                pose_tx: float, pose_ty: float, p_rz: float = 0.0,
+                                apply_mask: bool = False, triangulation=None,
+                                mask_style: str = 'detected') -> tuple:
+        """
+        Align face and return both the aligned image and the warp matrix.
+
+        This is the same as align_face() but also returns the 2x3 affine transform
+        matrix used for alignment, which can be used to transform landmarks from
+        original frame coordinates to aligned face coordinates.
+
+        Returns:
+            tuple: (aligned_face, warp_matrix)
+                - aligned_face: 112×112 aligned face image (BGR format)
+                - warp_matrix: (2, 3) affine transform matrix
+        """
+        # Ensure landmarks are (68, 2) shape
+        if landmarks_68.shape == (136,):
+            landmarks_68 = landmarks_68.reshape(68, 2)
+        elif landmarks_68.shape != (68, 2):
+            raise ValueError(f"landmarks_68 must be (68, 2) or (136,), got {landmarks_68.shape}")
+
+        # Extract rigid points from both source and destination
+        source_rigid = self._extract_rigid_points(landmarks_68)
+        dest_rigid = self._extract_rigid_points(self.reference_shape)
+
+        # Compute scale-rotation matrix using Kabsch algorithm
+        scale_rot_matrix = self._align_shapes_with_scale(source_rigid, dest_rigid)
+
+        # Build 2×3 affine warp matrix using pose translation
+        warp_matrix = self._build_warp_matrix(scale_rot_matrix, pose_tx, pose_ty)
+
+        # Apply affine transformation
+        aligned_face = cv2.warpAffine(
+            image,
+            warp_matrix,
+            (self.output_width, self.output_height),
+            flags=cv2.INTER_LINEAR
+        )
+
+        # Apply face mask if requested
+        if apply_mask:
+            if triangulation is None:
+                raise ValueError("triangulation required when apply_mask=True")
+
+            if mask_style == 'detected':
+                # C++ OpenFace style: transform detected landmarks by warp matrix
+                warp_2d = scale_rot_matrix
+                translation = np.array([warp_matrix[0, 2], warp_matrix[1, 2]])
+                aligned_landmarks = landmarks_68 @ warp_2d.T + translation
+            else:
+                # Legacy style: use reference shape
+                center = np.array([self.output_width / 2, self.output_height / 2])
+                aligned_landmarks = self.reference_shape + center
+                aligned_landmarks[:, 0] += 5.0
+                aligned_landmarks[:, 1] += 3.0
+
+            # Adjust eyebrow landmarks upward to include forehead
+            forehead_offset = (30 / 0.7) * self.sim_scale
+            for idx in [0, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26]:
+                aligned_landmarks[idx, 1] -= forehead_offset
+
+            # Create mask
+            mask = triangulation.create_face_mask(
+                aligned_landmarks,
+                self.output_width,
+                self.output_height
+            )
+
+            # Apply mask to each channel
+            aligned_face = cv2.bitwise_and(aligned_face, aligned_face, mask=mask)
+
+        return aligned_face, warp_matrix
+
     def _transform_landmarks(self, landmarks: np.ndarray, warp_matrix: np.ndarray) -> np.ndarray:
         """
         Transform landmarks using affine warp matrix
@@ -197,6 +281,60 @@ class OpenFace22FaceAligner:
 
         return s_dst / s_src
 
+    def _align_shapes_with_scale(self, src: np.ndarray, dst: np.ndarray) -> np.ndarray:
+        """
+        Compute scale AND rotation using Kabsch algorithm (like C++ AlignShapesWithScale)
+
+        This is the correct approach used by OpenFace C++:
+        1. Mean-normalize both point sets
+        2. Compute RMS scale for each
+        3. Normalize to unit scale
+        4. Use Kabsch/SVD to find optimal rotation
+        5. Return scale * rotation matrix
+
+        Args:
+            src: (N, 2) source points (detected landmarks)
+            dst: (N, 2) destination points (reference shape)
+
+        Returns:
+            (2, 2) scale-rotation matrix
+        """
+        n = src.shape[0]
+
+        # 1. Mean normalize both
+        src_mean = src.mean(axis=0)
+        dst_mean = dst.mean(axis=0)
+        src_centered = src - src_mean
+        dst_centered = dst - dst_mean
+
+        # 2. Compute RMS scale for each
+        s_src = np.sqrt(np.sum(src_centered ** 2) / n)
+        s_dst = np.sqrt(np.sum(dst_centered ** 2) / n)
+
+        # 3. Normalize to unit scale
+        src_normed = src_centered / s_src
+        dst_normed = dst_centered / s_dst
+
+        # 4. Kabsch algorithm (SVD) to find optimal rotation
+        H = src_normed.T @ dst_normed
+        U, S, Vt = np.linalg.svd(H)
+
+        # Handle reflection (ensure proper rotation) - check BEFORE computing R
+        d = np.linalg.det(Vt.T @ U.T)
+        corr = np.eye(2)
+        if d < 0:
+            corr[1, 1] = -1
+
+        R = Vt.T @ corr @ U.T
+
+        # Note: NOT transposing R - testing if direct Kabsch matches C++
+
+        # 5. Combine scale and rotation
+        scale = s_dst / s_src
+        scale_rot = scale * R
+
+        return scale_rot.astype(np.float32)
+
     def _build_warp_matrix(self, scale_rot: np.ndarray, pose_tx: float, pose_ty: float) -> np.ndarray:
         """
         Build 2×3 affine warp matrix from 2×2 scale-rotation matrix and pose translation
@@ -233,9 +371,11 @@ class OpenFace22FaceAligner:
         # C++ code (lines 142-143):
         #   warp_matrix(0,2) = -T(0) + out_width/2;
         #   warp_matrix(1,2) = -T(1) + out_height/2;
-        # NO empirical shifts (+2, -2) - those were incorrect!
+        # We add y_offset to shift the face up slightly (negative = up)
+        # to account for small differences between Python CalcParams and C++ CLNF fitting
+
         warp_matrix[0, 2] = -T_transformed[0] + self.output_width / 2
-        warp_matrix[1, 2] = -T_transformed[1] + self.output_height / 2
+        warp_matrix[1, 2] = -T_transformed[1] + self.output_height / 2 + self.y_offset
 
         return warp_matrix
 

pyfaceau-1.3.3/pyfaceau/config.py

@@ -0,0 +1,118 @@
+"""
+Canonical Configuration for PyFaceAU Pipeline
+
+These settings match C++ OpenFace 2.2 defaults for accurate AU extraction.
+DO NOT modify without thorough testing against C++ reference output.
+
+Configuration locked on: Dec 5, 2025
+Tested against: IMG_0942.MOV (1110 frames), IMG_0422.MOV (bearded)
+Target accuracy: Sub-pixel landmark error (<1.0 px), AU correlation >0.95
+"""
+
+# =============================================================================
+# CLNF Landmark Detection Configuration
+# =============================================================================
+CLNF_CONFIG = {
+    'max_iterations': 10,
+    'convergence_threshold': 0.005,  # Gold standard (stricter than 0.01)
+    'sigma': 2.25,                   # C++ CECLM default (1.5 × 1.5 scale factor)
+    'use_eye_refinement': True,      # Enable hierarchical eye model refinement
+    'convergence_profile': 'video',  # Enable template tracking + scale adaptation
+    'detector': False,               # Disable built-in detector (pyfaceau handles)
+}
+
+# =============================================================================
+# MTCNN Face Detection Configuration
+# =============================================================================
+MTCNN_CONFIG = {
+    'backend': 'coreml',             # Deterministic backend for reproducibility
+    'confidence_threshold': 0.5,     # Face confidence threshold
+    'nms_threshold': 0.7,            # Non-max suppression threshold
+}
+
+# =============================================================================
+# HOG Feature Extraction Configuration
+# =============================================================================
+HOG_CONFIG = {
+    'hog_dim': 4464,                 # 56×14 cell grid × 9 bins (4464 total)
+    'hog_bins': 1000,                # Histogram bins for running median
+    'hog_min': -0.005,               # CRITICAL: NOT 0.0 - matches C++ OpenFace
+    'hog_max': 1.0,                  # Maximum HOG value
+}
+
+# =============================================================================
+# Geometric Feature Configuration
+# =============================================================================
+GEOM_CONFIG = {
+    'geom_dim': 238,                 # 34 PDM params × 7 derivatives
+    'geom_bins': 10000,              # Histogram bins for running median
+    'geom_min': -60.0,               # Minimum geometric feature value
+    'geom_max': 60.0,                # Maximum geometric feature value
+}
+
+# =============================================================================
+# AU Prediction Configuration
+# =============================================================================
+AU_CONFIG = {
+    # Online AU correction (C++ CorrectOnlineAUs equivalent)
+    'num_bins': 200,                 # C++ default
+    'min_val': -3.0,                 # C++ default
+    'max_val': 5.0,                  # C++ default
+    'cutoff_ratio': 0.10,            # 10th percentile baseline
+    'min_frames': 10,                # Minimum frames before correction
+    'skip_au17_cutoff': True,        # AU17 exception (unusual weight distribution)
+    'apply_online_dyn_shift': False,  # Online 10% shift (no impact in testing)
+
+    # Two-pass processing
+    'max_stored_frames': 3000,       # OpenFace default for re-prediction
+
+    # AU-specific cutoff overrides
+    # Python raw predictions are systematically higher than C++ for certain AUs.
+    # These adjusted cutoffs compensate to match C++ behavior.
+    # See diagnose_raw_prediction_diff.py for derivation.
+    'cutoff_overrides': {
+        'AU20_r': 0.40,              # Original: 0.65 -> 0.9729 correlation (PASS)
+        'AU26_r': 0.12,              # Original: 0.30 -> 0.9317 correlation (best achievable)
+    },
+}
+
+# =============================================================================
+# Running Median Tracker Configuration
+# =============================================================================
+RUNNING_MEDIAN_CONFIG = {
+    'hog_dim': HOG_CONFIG['hog_dim'],
+    'geom_dim': GEOM_CONFIG['geom_dim'],
+    'hog_bins': HOG_CONFIG['hog_bins'],
+    'hog_min': HOG_CONFIG['hog_min'],
+    'hog_max': HOG_CONFIG['hog_max'],
+    'geom_bins': GEOM_CONFIG['geom_bins'],
+    'geom_min': GEOM_CONFIG['geom_min'],
+    'geom_max': GEOM_CONFIG['geom_max'],
+}
+
+# =============================================================================
+# CLNF Optimizer Defaults (in pyclnf/clnf.py)
+# =============================================================================
+# These are documented here for reference - actual defaults are in pyclnf:
+#   regularization: 22.5          # C++ CECLM: 25.0 base × 0.9 = 22.5
+#   sigma: 2.25                   # C++ CECLM: 1.5 base × 1.5 = 2.25
+#   weight_multiplier: 0.0        # C++ disables NU-RLMS weighting
+
+# =============================================================================
+# Known Fixes Applied
+# =============================================================================
+# 1. Optimizer defaults: reg=22.5, sigma=2.25 (in pyclnf/clnf.py)
+# 2. PDM epsilon: No +1e-10 in eigenvalue regularization (in pyclnf/core/pdm.py)
+# 3. BORDER_REPLICATE: Used in patch extraction (in pyclnf/core/optimizer.py)
+# 4. Template tracking: Enabled in video mode (in pyclnf/clnf.py)
+# 5. PyMTCNN bbox: [x,y,w,h] format handled correctly (in pymtcnn_detector.py)
+# 6. HOG min: -0.005 (NOT 0.0) matches C++ OpenFace
+
+# =============================================================================
+# Validation Targets
+# =============================================================================
+VALIDATION_TARGETS = {
+    'max_landmark_error_px': 1.0,    # Mean error threshold
+    'min_au_correlation': 0.95,      # For expressed AUs (std > 0.02)
+    'test_video': 'IMG_0942.MOV',    # Primary test video
+}