pyfaceau 1.0.9__tar.gz → 1.3.3__tar.gz

pyfaceau-1.3.3/LICENSE

@@ -0,0 +1,47 @@
+Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0)
+
+Copyright (c) 2025 John Wilson IV, MD
+
+This work is licensed under the Creative Commons Attribution-NonCommercial 4.0
+International License. To view a copy of this license, visit
+http://creativecommons.org/licenses/by-nc/4.0/ or send a letter to
+Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
+
+================================================================================
+
+You are free to:
+
+  * Share — copy and redistribute the material in any medium or format
+  * Adapt — remix, transform, and build upon the material
+
+The licensor cannot revoke these freedoms as long as you follow the license terms.
+
+================================================================================
+
+Under the following terms:
+
+  * Attribution — You must give appropriate credit, provide a link to the
+    license, and indicate if changes were made. You may do so in any reasonable
+    manner, but not in any way that suggests the licensor endorses you or your use.
+
+  * NonCommercial — You may not use the material for commercial purposes.
+
+  * No additional restrictions — You may not apply legal terms or technological
+    measures that legally restrict others from doing anything the license permits.
+
+================================================================================
+
+Notices:
+
+You do not have to comply with the license for elements of the material in the
+public domain or where your use is permitted by an applicable exception or
+limitation.
+
+No warranties are given. The license may not give you all of the permissions
+necessary for your intended use. For example, other rights such as publicity,
+privacy, or moral rights may limit how you use the material.
+
+================================================================================
+
+Full legal code available at:
+https://creativecommons.org/licenses/by-nc/4.0/legalcode

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.0.9 → 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)):