pyfaceau 1.0.6__tar.gz → 1.3.0__tar.gz

pyfaceau-1.3.0/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.0.6/pyfaceau.egg-info → pyfaceau-1.3.0}/PKG-INFO

@@ -1,15 +1,15 @@
 Metadata-Version: 2.4
 Name: pyfaceau
-Version: 1.0.6
+Version: 1.3.0
 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/face-analysis
-Project-URL: Documentation, https://github.com/johnwilsoniv/face-analysis/tree/main/S0%20PyfaceAU
-Project-URL: Repository, https://github.com/johnwilsoniv/face-analysis
-Project-URL: Bug Tracker, https://github.com/johnwilsoniv/face-analysis/issues
+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
@@ -32,7 +32,7 @@ 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: Cython>=0.29.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"
@@ -74,8 +74,14 @@ pyfaceau is a Python reimplementation of the [OpenFace 2.2](https://github.com/T
 #### Option 1: Install from PyPI (Recommended)
 
 ```bash
-# Install pyfaceau
-pip install pyfaceau
+# For NVIDIA GPU (CUDA):
+pip install pyfaceau[cuda]
+
+# For Apple Silicon (M1/M2/M3):
+pip install pyfaceau[coreml]
+
+# For CPU-only:
+pip install pyfaceau[cpu]
 
 # Download model weights (14MB)
 python -m pyfaceau.download_weights
@@ -84,12 +90,14 @@ python -m pyfaceau.download_weights
 # https://github.com/johnwilsoniv/face-analysis/tree/main/S0%20PyfaceAU/weights
 ```
 
+**Note:** PyFaceAU v1.1.0+ uses [PyMTCNN](https://pypi.org/project/pymtcnn/) for cross-platform face detection with CUDA/CoreML/CPU support.
+
 #### Option 2: Install from Source
 
 ```bash
 # Clone repository
 git clone https://github.com/johnwilsoniv/face-analysis.git
-cd "face-analysis/S0 PyfaceAU"
+cd "face-analysis/pyfaceau"
 
 # Install in development mode
 pip install -e .
@@ -104,13 +112,13 @@ pip install -e .
 ```python
 from pyfaceau import ParallelAUPipeline
 
-# Initialize parallel pipeline 
+# Initialize parallel pipeline
 pipeline = ParallelAUPipeline(
-    retinaface_model='weights/retinaface_mobilenet025_coreml.onnx',
     pfld_model='weights/pfld_cunjian.onnx',
     pdm_file='weights/In-the-wild_aligned_PDM_68.txt',
     au_models_dir='path/to/AU_predictors',
     triangulation_file='weights/tris_68_full.txt',
+    mtcnn_backend='auto',  # or 'cuda', 'coreml', 'cpu'
     num_workers=6,  # Adjust based on CPU cores
     batch_size=30
 )
@@ -125,20 +133,19 @@ print(f"Processed {len(results)} frames")
 # Typical output: ~28-50 FPS depending on CPU cores
 ```
 
-#### Standard Mode (4.6 FPS)
+#### Standard Mode (5-35 FPS depending on backend)
 
 ```python
 from pyfaceau import FullPythonAUPipeline
 
 # Initialize standard pipeline
 pipeline = FullPythonAUPipeline(
-    retinaface_model='weights/retinaface_mobilenet025_coreml.onnx',
     pfld_model='weights/pfld_cunjian.onnx',
     pdm_file='weights/In-the-wild_aligned_PDM_68.txt',
     au_models_dir='path/to/AU_predictors',
     triangulation_file='weights/tris_68_full.txt',
+    mtcnn_backend='auto',  # Automatically selects best backend
     use_calc_params=True,
-    use_coreml=True,  # macOS only
     verbose=False
 )
 
@@ -149,6 +156,11 @@ results = pipeline.process_video(
 )
 ```
 
+**Performance by backend:**
+- CUDA (NVIDIA GPU): ~35 FPS
+- CoreML (Apple Silicon): ~20-25 FPS
+- CPU: ~5-10 FPS
+
 ### Example Output
 
 ```csv
@@ -166,7 +178,7 @@ pyfaceau replicates the complete OpenFace 2.2 AU extraction pipeline:
 ```
 Video Input
     ↓
-Face Detection (RetinaFace ONNX)
+Face Detection (PyMTCNN - CUDA/CoreML/CPU)
     ↓
 Landmark Detection (PFLD 68-point)
     ↓

{pyfaceau-1.0.6 → pyfaceau-1.3.0}/README.md

@@ -29,8 +29,14 @@ pyfaceau is a Python reimplementation of the [OpenFace 2.2](https://github.com/T
 #### Option 1: Install from PyPI (Recommended)
 
 ```bash
-# Install pyfaceau
-pip install pyfaceau
+# For NVIDIA GPU (CUDA):
+pip install pyfaceau[cuda]
+
+# For Apple Silicon (M1/M2/M3):
+pip install pyfaceau[coreml]
+
+# For CPU-only:
+pip install pyfaceau[cpu]
 
 # Download model weights (14MB)
 python -m pyfaceau.download_weights
@@ -39,12 +45,14 @@ python -m pyfaceau.download_weights
 # https://github.com/johnwilsoniv/face-analysis/tree/main/S0%20PyfaceAU/weights
 ```
 
+**Note:** PyFaceAU v1.1.0+ uses [PyMTCNN](https://pypi.org/project/pymtcnn/) for cross-platform face detection with CUDA/CoreML/CPU support.
+
 #### Option 2: Install from Source
 
 ```bash
 # Clone repository
 git clone https://github.com/johnwilsoniv/face-analysis.git
-cd "face-analysis/S0 PyfaceAU"
+cd "face-analysis/pyfaceau"
 
 # Install in development mode
 pip install -e .
@@ -59,13 +67,13 @@ pip install -e .
 ```python
 from pyfaceau import ParallelAUPipeline
 
-# Initialize parallel pipeline 
+# Initialize parallel pipeline
 pipeline = ParallelAUPipeline(
-    retinaface_model='weights/retinaface_mobilenet025_coreml.onnx',
     pfld_model='weights/pfld_cunjian.onnx',
     pdm_file='weights/In-the-wild_aligned_PDM_68.txt',
     au_models_dir='path/to/AU_predictors',
     triangulation_file='weights/tris_68_full.txt',
+    mtcnn_backend='auto',  # or 'cuda', 'coreml', 'cpu'
     num_workers=6,  # Adjust based on CPU cores
     batch_size=30
 )
@@ -80,20 +88,19 @@ print(f"Processed {len(results)} frames")
 # Typical output: ~28-50 FPS depending on CPU cores
 ```
 
-#### Standard Mode (4.6 FPS)
+#### Standard Mode (5-35 FPS depending on backend)
 
 ```python
 from pyfaceau import FullPythonAUPipeline
 
 # Initialize standard pipeline
 pipeline = FullPythonAUPipeline(
-    retinaface_model='weights/retinaface_mobilenet025_coreml.onnx',
     pfld_model='weights/pfld_cunjian.onnx',
     pdm_file='weights/In-the-wild_aligned_PDM_68.txt',
     au_models_dir='path/to/AU_predictors',
     triangulation_file='weights/tris_68_full.txt',
+    mtcnn_backend='auto',  # Automatically selects best backend
     use_calc_params=True,
-    use_coreml=True,  # macOS only
     verbose=False
 )
 
@@ -104,6 +111,11 @@ results = pipeline.process_video(
 )
 ```
 
+**Performance by backend:**
+- CUDA (NVIDIA GPU): ~35 FPS
+- CoreML (Apple Silicon): ~20-25 FPS
+- CPU: ~5-10 FPS
+
 ### Example Output
 
 ```csv
@@ -121,7 +133,7 @@ pyfaceau replicates the complete OpenFace 2.2 AU extraction pipeline:
 ```
 Video Input
     ↓
-Face Detection (RetinaFace ONNX)
+Face Detection (PyMTCNN - CUDA/CoreML/CPU)
     ↓
 Landmark Detection (PFLD 68-point)
     ↓

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

@@ -100,12 +100,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)
-        scale_identity = self._align_shapes_with_scale(source_rigid, dest_rigid)
-        scale = scale_identity[0, 0]  # Extract scale from identity matrix
+        # 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 CSV p_rz rotation
-        # CSV p_rz describes rotation FROM canonical TO tilted
+        # 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)
@@ -117,7 +117,7 @@ class OpenFace22FaceAligner:
         # Combine scale and rotation
         scale_rot_matrix = scale * R
 
-        # Build 2×3 affine warp matrix
+        # 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
@@ -239,6 +239,37 @@ class OpenFace22FaceAligner:
 
         return warp_matrix
 
+    def _build_warp_matrix_centroid(self, scale_rot: np.ndarray, src_centroid: np.ndarray, dst_centroid: np.ndarray) -> np.ndarray:
+        """
+        Build 2×3 affine warp matrix using source and destination centroids
+
+        This is the corrected version that uses rigid point centroids instead of
+        pose translation parameters, which gives better alignment with C++ OpenFace.
+
+        Args:
+            scale_rot: (2, 2) similarity transform matrix (scale × rotation)
+            src_centroid: (2,) centroid of source rigid points
+            dst_centroid: (2,) centroid of destination rigid points
+
+        Returns:
+            (2, 3) affine warp matrix for cv2.warpAffine
+        """
+        # Initialize 2×3 warp matrix
+        warp_matrix = np.zeros((2, 3), dtype=np.float32)
+
+        # Copy scale-rotation to first 2×2 block
+        warp_matrix[:2, :2] = scale_rot
+
+        # Transform source centroid through scale-rotation
+        T_src = scale_rot @ src_centroid
+
+        # Translation: map src_centroid to dst_centroid, then center in output
+        # dst_centroid is in PDM space (centered around 0), so add output_center
+        warp_matrix[0, 2] = dst_centroid[0] - T_src[0] + self.output_width / 2
+        warp_matrix[1, 2] = dst_centroid[1] - T_src[1] + self.output_height / 2
+
+        return warp_matrix
+
     def _extract_rigid_points(self, landmarks: np.ndarray) -> np.ndarray:
         """
         Extract 24 rigid points from 68 landmarks
@@ -286,37 +317,34 @@ class OpenFace22FaceAligner:
 
         # Rotation matrix: R = V^T × corr × U^T
         # OpenFace C++ uses: R = svd.vt.t() * corr * svd.u.t()
+        # But we need to transpose to match C++ behavior
+        # Testing showed R.T gives correct rotation direction (+18° vs -18°)
         R = Vt.T @ corr @ U.T
 
-        return R
+        return R.T  # Transpose to match C++ rotation direction
 
-    def _align_shapes_with_scale(self, src: np.ndarray, dst: np.ndarray) -> np.ndarray:
+    def _align_shapes_with_scale_and_rotation(self, src: np.ndarray, dst: np.ndarray) -> np.ndarray:
         """
-        Compute similarity transform (scale only, NO rotation) between two point sets
+        Compute similarity transform (scale + rotation via Kabsch) between two point sets
 
-        CRITICAL FIX: Since CSV landmarks are PDM-reconstructed (via CalcShape2D),
-        they are already in canonical orientation. We only need scale + translation,
-        NOT rotation via Kabsch.
+        This matches C++ AlignShapesWithScale in RotationHelpers.h lines 195-241.
 
-        Background: FaceAnalyser.cpp calls CalcParams TWICE:
-        1. On raw landmarks → params_global₁ → CalcShape2D → reconstructed landmarks (CSV output)
-        2. On reconstructed landmarks → params_global₂ → AlignFace
+        CRITICAL: p_rz is NOT used for alignment! C++ computes rotation from landmarks
+        using Kabsch algorithm.
 
-        The second CalcParams produces near-zero rotation because reconstructed landmarks
-        are already canonical. Our Python uses CSV landmarks (already canonical), so we
-        skip rotation computation entirely.
-
-        Algorithm:
+        Algorithm (matching C++):
         1. Mean-normalize both src and dst
         2. Compute RMS scale for each
-        3. Return: (s_dst / s_src) × Identity (scale only, no rotation)
+        3. Normalize by scale
+        4. Compute rotation via Kabsch2D
+        5. Return: (s_dst / s_src) × R_kabsch
 
         Args:
             src: (N, 2) source points (detected landmarks)
             dst: (N, 2) destination points (reference shape)
 
         Returns:
-            (2, 2) similarity transform matrix (scale × identity)
+            (2, 2) similarity transform matrix (scale × rotation)
         """
         n = src.shape[0]
 
@@ -335,18 +363,20 @@ class OpenFace22FaceAligner:
         dst_mean_normed[:, 1] -= mean_dst_y
 
         # 2. Compute RMS scale for each point set
-        # OpenFace C++ uses: sqrt(sum(points^2) / n)
+        # C++ RotationHelpers.h line 221-222
         src_sq = src_mean_normed ** 2
         dst_sq = dst_mean_normed ** 2
 
         s_src = np.sqrt(np.sum(src_sq) / n)
         s_dst = np.sqrt(np.sum(dst_sq) / n)
 
-        # 3. Normalize by scale
+        # 3. Normalize by scale (C++ line 224-225)
         src_norm = src_mean_normed / s_src
         dst_norm = dst_mean_normed / s_dst
 
-        # 3. Return scale only (no rotation computed via Kabsch)
-        # Rotation will be provided externally from CSV p_rz
+        # 4. Get rotation via Kabsch2D (C++ line 230)
+        R = self._align_shapes_kabsch_2d(src_norm, dst_norm)
+
+        # 5. Return scale * rotation (C++ line 233)
         scale = s_dst / s_src
-        return scale * np.eye(2, dtype=np.float32)
+        return scale * R

pyfaceau-1.3.0/pyfaceau/alignment/paw.py

@@ -0,0 +1,285 @@
+"""
+Piecewise Affine Warp (PAW) for face alignment.
+
+Based on OpenFace implementation:
+- lib/local/LandmarkDetector/src/PAW.cpp
+- Active Appearance Models Revisited (Matthews & Baker, IJCV 2004)
+
+This implementation matches the C++ PAW algorithm for pixel-perfect alignment.
+"""
+
+import numpy as np
+import cv2
+from typing import Tuple, Optional
+
+
+class PAW:
+    """
+    Piecewise Affine Warp using triangulation.
+
+    Warps faces by applying independent affine transforms to each triangle,
+    allowing for complex non-affine deformations.
+    """
+
+    def __init__(self, destination_landmarks: np.ndarray, triangulation: np.ndarray,
+                 min_x: Optional[float] = None, min_y: Optional[float] = None,
+                 max_x: Optional[float] = None, max_y: Optional[float] = None):
+        """
+        Initialize PAW with destination shape and triangulation.
+
+        Args:
+            destination_landmarks: (2*N,) array with [x0...xN, y0...yN] format
+            triangulation: (M, 3) array of triangle vertex indices
+            min_x, min_y, max_x, max_y: Optional bounds for output image
+        """
+        self.destination_landmarks = destination_landmarks.copy()
+        self.triangulation = triangulation.copy()
+
+        num_points = len(destination_landmarks) // 2
+        num_tris = len(triangulation)
+
+        # Extract x and y coordinates
+        xs = destination_landmarks[:num_points]
+        ys = destination_landmarks[num_points:]
+
+        # Pre-compute alpha and beta coefficients for each triangle
+        self.alpha = np.zeros((num_tris, 3), dtype=np.float32)
+        self.beta = np.zeros((num_tris, 3), dtype=np.float32)
+
+        # Store triangle bounding boxes for optimization
+        self.triangle_bounds = []
+
+        for tri_idx in range(num_tris):
+            j, k, l = triangulation[tri_idx]
+
+            # Compute coefficients (from PAW.cpp lines 83-96)
+            c1 = ys[l] - ys[j]
+            c2 = xs[l] - xs[j]
+            c4 = ys[k] - ys[j]
+            c3 = xs[k] - xs[j]
+            c5 = c3 * c1 - c2 * c4
+
+            if abs(c5) < 1e-10:
+                # Degenerate triangle, skip
+                continue
+
+            self.alpha[tri_idx, 0] = (ys[j] * c2 - xs[j] * c1) / c5
+            self.alpha[tri_idx, 1] = c1 / c5
+            self.alpha[tri_idx, 2] = -c2 / c5
+
+            self.beta[tri_idx, 0] = (xs[j] * c4 - ys[j] * c3) / c5
+            self.beta[tri_idx, 1] = -c4 / c5
+            self.beta[tri_idx, 2] = c3 / c5
+
+            # Store triangle vertices and bounding box for point-in-triangle tests
+            tri_xs = [xs[j], xs[k], xs[l]]
+            tri_ys = [ys[j], ys[k], ys[l]]
+            self.triangle_bounds.append({
+                'vertices': [(tri_xs[i], tri_ys[i]) for i in range(3)],
+                'min_x': min(tri_xs),
+                'max_x': max(tri_xs),
+                'min_y': min(tri_ys),
+                'max_y': max(tri_ys)
+            })
+
+        # Determine output image bounds
+        if min_x is None:
+            min_x = float(np.min(xs))
+            min_y = float(np.min(ys))
+            max_x = float(np.max(xs))
+            max_y = float(np.max(ys))
+
+        self.min_x = min_x
+        self.min_y = min_y
+
+        width = int(max_x - min_x + 1.5)
+        height = int(max_y - min_y + 1.5)
+
+        # Create pixel mask and triangle ID map
+        self.pixel_mask = np.zeros((height, width), dtype=np.uint8)
+        self.triangle_id = np.full((height, width), -1, dtype=np.int32)
+
+        # Determine which triangle each pixel belongs to
+        curr_tri = -1
+        for y in range(height):
+            for x in range(width):
+                px = x + min_x
+                py = y + min_y
+                curr_tri = self._find_triangle(px, py, curr_tri)
+                if curr_tri != -1:
+                    self.triangle_id[y, x] = curr_tri
+                    self.pixel_mask[y, x] = 1
+
+        # Pre-allocate arrays
+        self.coefficients = np.zeros((num_tris, 6), dtype=np.float32)
+        self.map_x = np.zeros((height, width), dtype=np.float32)
+        self.map_y = np.zeros((height, width), dtype=np.float32)
+
+    def warp(self, image: np.ndarray, source_landmarks: np.ndarray) -> np.ndarray:
+        """
+        Warp image using source landmarks to destination landmarks.
+
+        Args:
+            image: Source image to warp
+            source_landmarks: (2*N,) array with [x0...xN, y0...yN] format
+
+        Returns:
+            Warped image matching destination shape
+        """
+        # Compute warp coefficients from source landmarks
+        self._calc_coeff(source_landmarks)
+
+        # Compute pixel mapping (where to sample from)
+        self._warp_region()
+
+        # Apply warp using OpenCV remap with bilinear interpolation
+        warped = cv2.remap(image, self.map_x, self.map_y, cv2.INTER_LINEAR)
+
+        return warped
+
+    def _calc_coeff(self, source_landmarks: np.ndarray):
+        """
+        Calculate warping coefficients from source landmarks.
+        Matches PAW::CalcCoeff() in PAW.cpp lines 338-370.
+        """
+        num_points = len(source_landmarks) // 2
+
+        for tri_idx in range(len(self.triangulation)):
+            i, j, k = self.triangulation[tri_idx]
+
+            # Extract source coordinates for triangle vertices
+            c1 = source_landmarks[i]
+            c2 = source_landmarks[j] - c1
+            c3 = source_landmarks[k] - c1
+            c4 = source_landmarks[i + num_points]
+            c5 = source_landmarks[j + num_points] - c4
+            c6 = source_landmarks[k + num_points] - c4
+
+            # Get precomputed alpha and beta
+            alpha = self.alpha[tri_idx]
+            beta = self.beta[tri_idx]
+
+            # Compute 6 coefficients for affine transform
+            self.coefficients[tri_idx, 0] = c1 + c2 * alpha[0] + c3 * beta[0]
+            self.coefficients[tri_idx, 1] = c2 * alpha[1] + c3 * beta[1]
+            self.coefficients[tri_idx, 2] = c2 * alpha[2] + c3 * beta[2]
+            self.coefficients[tri_idx, 3] = c4 + c5 * alpha[0] + c6 * beta[0]
+            self.coefficients[tri_idx, 4] = c5 * alpha[1] + c6 * beta[1]
+            self.coefficients[tri_idx, 5] = c5 * alpha[2] + c6 * beta[2]
+
+    def _warp_region(self):
+        """
+        Compute source pixel coordinates for each destination pixel.
+        Matches PAW::WarpRegion() in PAW.cpp lines 374-436.
+        """
+        height, width = self.pixel_mask.shape
+
+        for y in range(height):
+            yi = float(y) + self.min_y
+
+            for x in range(width):
+                xi = float(x) + self.min_x
+
+                if self.pixel_mask[y, x] == 0:
+                    # Outside face region
+                    self.map_x[y, x] = -1
+                    self.map_y[y, x] = -1
+                else:
+                    # Get triangle for this pixel
+                    tri_idx = self.triangle_id[y, x]
+                    coeff = self.coefficients[tri_idx]
+
+                    # Apply affine transform: x_src = coeff[0] + coeff[1]*xi + coeff[2]*yi
+                    self.map_x[y, x] = coeff[0] + coeff[1] * xi + coeff[2] * yi
+                    self.map_y[y, x] = coeff[3] + coeff[4] * xi + coeff[5] * yi
+
+    @staticmethod
+    def _same_side(x0: float, y0: float, x1: float, y1: float,
+                    x2: float, y2: float, x3: float, y3: float) -> bool:
+        """
+        Check if point (x0,y0) is on same side of line (x2,y2)-(x3,y3) as point (x1,y1).
+        Matches PAW::sameSide() in PAW.cpp lines 443-451.
+        """
+        x = (x3 - x2) * (y0 - y2) - (x0 - x2) * (y3 - y2)
+        y = (x3 - x2) * (y1 - y2) - (x1 - x2) * (y3 - y2)
+        return x * y >= 0
+
+    @staticmethod
+    def _point_in_triangle(x0: float, y0: float, x1: float, y1: float,
+                           x2: float, y2: float, x3: float, y3: float) -> bool:
+        """
+        Check if point (x0,y0) is inside triangle (x1,y1)-(x2,y2)-(x3,y3).
+        Matches PAW::pointInTriangle() in PAW.cpp lines 454-461.
+        """
+        same_1 = PAW._same_side(x0, y0, x1, y1, x2, y2, x3, y3)
+        same_2 = PAW._same_side(x0, y0, x2, y2, x1, y1, x3, y3)
+        same_3 = PAW._same_side(x0, y0, x3, y3, x1, y1, x2, y2)
+        return same_1 and same_2 and same_3
+
+    def _find_triangle(self, x: float, y: float, guess: int = -1) -> int:
+        """
+        Find which triangle contains point (x, y).
+        Matches PAW::findTriangle() in PAW.cpp lines 465-515.
+
+        Args:
+            x, y: Point coordinates
+            guess: Previous triangle index for optimization
+
+        Returns:
+            Triangle index or -1 if point is outside all triangles
+        """
+        # Try guess first for speed
+        if guess != -1:
+            bounds = self.triangle_bounds[guess]
+            vertices = bounds['vertices']
+            if self._point_in_triangle(x, y, vertices[0][0], vertices[0][1],
+                                      vertices[1][0], vertices[1][1],
+                                      vertices[2][0], vertices[2][1]):
+                return guess
+
+        # Search all triangles
+        for tri_idx, bounds in enumerate(self.triangle_bounds):
+            # Quick bounding box check
+            if (x < bounds['min_x'] or x > bounds['max_x'] or
+                y < bounds['min_y'] or y > bounds['max_y']):
+                continue
+
+            # Precise point-in-triangle test
+            vertices = bounds['vertices']
+            if self._point_in_triangle(x, y, vertices[0][0], vertices[0][1],
+                                      vertices[1][0], vertices[1][1],
+                                      vertices[2][0], vertices[2][1]):
+                return tri_idx
+
+        return -1
+
+
+def load_triangulation(filepath: str) -> np.ndarray:
+    """
+    Load triangulation file in OpenFace format.
+
+    Format:
+        Line 1: Number of triangles
+        Line 2: Number of columns (always 3)
+        Lines 3+: Triangle vertex indices (3 per line)
+
+    Args:
+        filepath: Path to triangulation file (e.g., tris_68_full.txt)
+
+    Returns:
+        (M, 3) array of triangle vertex indices
+    """
+    with open(filepath, 'r') as f:
+        lines = f.readlines()
+
+    num_tris = int(lines[0].strip())
+    num_cols = int(lines[1].strip())
+
+    assert num_cols == 3, f"Expected 3 columns, got {num_cols}"
+
+    triangulation = np.zeros((num_tris, 3), dtype=np.int32)
+    for i in range(num_tris):
+        parts = lines[i + 2].strip().split()
+        triangulation[i] = [int(parts[j]) for j in range(3)]
+
+    return triangulation