Add front facing metrics module

app/models/front_facing_metrics.py

@@ -0,0 +1,1203 @@
+"""
+Front-Facing Golf Swing Metrics Calculator
+
+This module contains all the mathematical calculations for front-facing golf swing metrics.
+The metrics_calculator.py file handles DTL (Down-the-Line) view metrics.
+"""
+
+import math
+import numpy as np
+import cv2
+from typing import Dict, List, Tuple, Optional, Union
+
+# Landmark indices
+L_HIP, R_HIP = 23, 24
+L_SHO, R_SHO = 11, 12
+L_EYE, R_EYE = 2, 5
+
+# Debug helper
+VERBOSE = False
+def dbg(msg):
+    if VERBOSE: print(f"DEBUG: {msg}")
+
+# Core math utilities
+def wrap180(a): 
+    return (a + 180.0) % 360.0 - 180.0
+
+def unit2(v):
+    """Normalize 2D vector"""
+    n = (v[0]*v[0] + v[1]*v[1])**0.5
+    return (v[0]/n, v[1]/n) if n > 1e-6 else (0.0, 1.0)
+
+def signed_angle2(u, v):
+    """Signed angle between two 2D vectors in degrees (-180, 180]"""
+    dot = u[0]*v[0] + u[1]*v[1]
+    det = u[0]*v[1] - u[1]*v[0]
+    return math.degrees(math.atan2(det, dot))
+
+def smooth_landmarks(pose_data: Dict[int, List], alpha: float = 0.35) -> Dict[int, List]:
+    """Apply exponential moving average smoothing to landmarks"""
+    if not pose_data:
+        return pose_data
+    
+    frame_indices = sorted(pose_data.keys())
+    smoothed_data = {}
+    
+    for frame_idx in frame_indices:
+        landmarks = pose_data[frame_idx]
+        if not landmarks or not isinstance(landmarks, list):
+            continue
+            
+        smoothed_landmarks = []
+        for i, lm in enumerate(landmarks):
+            if lm and isinstance(lm, list) and len(lm) >= 3:
+                x, y, vis = lm[0], lm[1], lm[2]
+                
+                # Get previous smoothed values
+                if frame_idx > 0 and frame_idx - 1 in smoothed_data:
+                    prev_lms = smoothed_data[frame_idx - 1]
+                    if (i < len(prev_lms) and prev_lms[i] and 
+                        isinstance(prev_lms[i], list) and len(prev_lms[i]) >= 3):
+                        px, py, pv = prev_lms[i][0], prev_lms[i][1], prev_lms[i][2]
+                        x = alpha * x + (1 - alpha) * px
+                        y = alpha * y + (1 - alpha) * py  
+                        vis = alpha * vis + (1 - alpha) * pv
+                
+                smoothed_landmarks.append([x, y, vis])
+            else:
+                smoothed_landmarks.append(lm)
+        
+        smoothed_data[frame_idx] = smoothed_landmarks
+    
+    return smoothed_data
+
+
+def get_landmark_position(landmarks: List, landmark_idx: int) -> Optional[Tuple[float, float, float]]:
+    """Get landmark position (x, y, visibility) by index"""
+    if landmarks is None or not isinstance(landmarks, list) or landmark_idx >= len(landmarks) or landmarks[landmark_idx] is None:
+        return None
+    
+    landmark = landmarks[landmark_idx]
+    if landmark is not None and isinstance(landmark, list) and len(landmark) >= 3:
+        return (landmark[0], landmark[1], landmark[2])
+    return None
+
+
+def calculate_shoulder_tilt_at_impact(
+    pose_data,
+    swing_phases,
+    world_landmarks=None,
+    frames=None,                 # NEW: pass list/array of frames OR
+    image_shape=None,            # NEW: (H, W) if frames not available
+    handedness='right'
+):
+    """
+    Shoulder Tilt @ Impact (front-facing).
+    +ve if trail shoulder lower (right shoulder for right-handed).
+    FIXED: Uses image-plane only for shoulder tilt; 3D only for frame rejection.
+    """
+
+    import math, numpy as np
+    L_EYE, R_EYE = 2, 5
+    L_HIP, R_HIP = 23, 24
+    L_SHO, R_SHO = 11, 12
+
+    # ---------- helpers ----------
+    def _scale_xy(x, y, H, W):
+        """Unit detection guard to prevent double-scaling"""
+        if H is None or W is None:
+            return x, y
+        # If values look like pixels (>>2), don't rescale
+        if max(abs(x), abs(y), 1.0) > 2.0:
+            return x, y
+        return x * W, y * H
+
+    def _line_tilt_deg(lm, iL, iR):
+        # raw image tilt (no aspect correction); used only for small-roll estimate
+        if not lm or iL >= len(lm) or iR >= len(lm) or lm[iL] is None or lm[iR] is None:
+            return None
+        dx = lm[iR][0] - lm[iL][0]
+        dy = lm[iR][1] - lm[iL][1]
+        if abs(dx) + abs(dy) < 1e-8:
+            return None
+        return math.degrees(math.atan2(dy, dx))
+
+    def _consensus_roll_deg(lm, H, W):
+        """Camera roll from eyes/hips with unit detection"""
+        if not lm:
+            return 0.0
+        cand = []
+        for line_idxs in [(L_EYE, R_EYE), (L_HIP, R_HIP)]:
+            iL, iR = line_idxs
+            if lm[iL] and lm[iR]:
+                dx_raw = lm[iR][0] - lm[iL][0]
+                dy_raw = lm[iR][1] - lm[iL][1]
+                dx, dy = _scale_xy(dx_raw, dy_raw, H, W)
+                if abs(dx) + abs(dy) > 1e-8:
+                    tilt = math.degrees(math.atan2(dy, dx))
+                    tilt = ((tilt + 90.0) % 180.0) - 90.0  # (-90,90]
+                    if abs(tilt) <= 8.0:  # Only small rolls
+                        cand.append(tilt)
+        
+        if len(cand) < 2 or np.std(cand) > 3.0:
+            return 0.0
+        return float(np.median(cand))
+
+    def _get_HW():
+        # prefer frames; else image_shape; else no correction
+        if frames is not None and len(frames):
+            H, W = frames[0].shape[:2]
+            return float(H), float(W)
+        if image_shape is not None and len(image_shape) >= 2:
+            H, W = image_shape[:2]
+            return float(H), float(W)
+        return None, None  # no pixel aspect info
+
+    def _deroll(dx, dy, roll_deg):
+        cr = math.cos(math.radians(roll_deg))
+        sr = math.sin(math.radians(roll_deg))
+        # rotate by -roll: [ c  s; -s  c ] * [dx, dy]
+        return (cr*dx + sr*dy, -sr*dx + cr*dy)
+
+    def _width_px_derolled(lm, iL, iR, roll_deg):
+        """Get derolled horizontal width and vertical separation in pixels"""
+        if not lm or not lm[iL] or not lm[iR]:
+            return 0.0, 0.0
+        xL, yL = lm[iL][0], lm[iL][1]
+        xR, yR = lm[iR][0], lm[iR][1]
+        cr, sr = math.cos(math.radians(roll_deg)), math.sin(math.radians(roll_deg))
+        # rotate by -roll
+        dx = (cr*(xR-xL) + sr*(yR-yL))
+        dy = (-sr*(xR-xL) + cr*(yR-yL))
+        return abs(dx), dy  # horizontal width (derolled), vertical (derolled)
+
+    def _check_frame_quality(lm, H, W):
+        """Quality gates: visibility, shoulder width, basic checks"""
+        if not lm or not lm[L_SHO] or not lm[R_SHO]:
+            return False, "missing_shoulders"
+        
+        # Visibility check
+        if lm[L_SHO][2] < 0.6 or lm[R_SHO][2] < 0.6:
+            return False, "low_visibility"
+        
+        # Shoulder width check (>8% of frame width)
+        if W is not None:
+            dx_raw = abs(lm[R_SHO][0] - lm[L_SHO][0])
+            dx_scaled, _ = _scale_xy(dx_raw, 0, H, W)
+            if abs(dx_scaled) < 0.08 * W:
+                return False, "too_narrow"
+        
+        return True, "ok"
+
+    def _estimate_torso_yaw_3d(world_frame):
+        """Estimate torso yaw from 3D shoulders to reject severe angles"""
+        if not world_frame or not world_frame[L_SHO] or not world_frame[R_SHO]:
+            return None
+        
+        dx = world_frame[R_SHO][0] - world_frame[L_SHO][0]
+        dz = world_frame[R_SHO][2] - world_frame[L_SHO][2]
+        
+        if abs(dx) + abs(dz) < 1e-8:
+            return None
+        
+        # Rough yaw estimate - angle from frontal (dz=0)
+        yaw = abs(math.degrees(math.atan2(abs(dz), abs(dx))))
+        return yaw
+
+    # ---------- pick exact impact frame ----------
+    if world_landmarks:
+        setup_frames = swing_phases.get("setup", [])
+        impact_f = _impact_frame(world_landmarks, swing_phases)
+        if impact_f is None:
+            impact_frames = swing_phases.get("impact", [])
+            if impact_frames:
+                impact_f = impact_frames[0]
+        
+        # Try subframe refinement if available
+        if impact_f is not None:
+            f_refined = _subframe_impact_refinement(world_landmarks, impact_f)
+            # Use integer part for now, but structure supports fractional
+            impact_f = int(round(f_refined))
+    else:
+        impact_frames = swing_phases.get("impact", [])
+        if not impact_frames:
+            allf = sorted(pose_data.keys())
+            if not allf:
+                return None
+            impact_f = allf[-1]
+        else:
+            impact_f = impact_frames[0]
+
+    # Get the refined impact frame data
+    if impact_f not in pose_data:
+        return None
+    
+    lm = pose_data[impact_f]
+    H, W = _get_HW()
+
+    # ---------- quality checks ----------
+    quality_ok, quality_reason = _check_frame_quality(lm, H, W)
+    if not quality_ok:
+        print(f"DEBUG shoulder_tilt: frame_quality_failed - {quality_reason}")
+        # Still continue but mark as suspect
+    
+    # 3D yaw check for frame rejection only
+    yaw_ok = True
+    if world_landmarks and impact_f in world_landmarks:
+        yaw = _estimate_torso_yaw_3d(world_landmarks[impact_f])
+        if yaw is not None and yaw > 30.0:
+            yaw_ok = False
+            print(f"DEBUG shoulder_tilt: rejecting_frame - torso_yaw={yaw:.1f}° > 30°")
+
+    # ---------- 2D image-plane calculation (primary method) ----------
+    # Get shoulder positions with unit detection
+    xL, yL = lm[L_SHO][0], lm[L_SHO][1]
+    xR, yR = lm[R_SHO][0], lm[R_SHO][1]
+    
+    dx_raw = xR - xL
+    dy_raw = yR - yL
+    
+    dx, dy = _scale_xy(dx_raw, dy_raw, H, W)
+    
+    # Camera roll correction (minimal smoothing - use single frame)
+    alpha_micro = 0.8  # Much lighter smoothing for impact
+    lm_for_roll = [lm[i][:] if lm[i] else None for i in range(len(lm))]  # Copy landmarks
+    if impact_f > 0 and (impact_f - 1) in pose_data:
+        prev_lm = pose_data[impact_f - 1]
+        # Light smoothing only if previous frame available
+        if prev_lm and prev_lm[L_SHO] and prev_lm[R_SHO]:
+            for i in [L_SHO, R_SHO, L_EYE, R_EYE, L_HIP, R_HIP]:
+                if lm_for_roll[i] and prev_lm[i]:
+                    lm_for_roll[i] = [
+                        alpha_micro * lm[i][0] + (1 - alpha_micro) * prev_lm[i][0],
+                        alpha_micro * lm[i][1] + (1 - alpha_micro) * prev_lm[i][1],
+                        lm[i][2]  # Keep original visibility
+                    ]
+    
+    roll = _consensus_roll_deg(lm_for_roll, H, W)
+    
+    # Hybrid de-yaw shoulder tilt calculation
+    # Derolled shoulder and pelvis widths (pixels)
+    sho_dx_r, sho_dy_r = _width_px_derolled(lm, L_SHO, R_SHO, roll)
+    pel_dx_r, _        = _width_px_derolled(lm, L_HIP, R_HIP, roll)
+
+    # Get setup pelvis width median as scale anchor (use only good frames)
+    setup_frames = swing_phases.get("setup", [])[:8]
+    setup_pelvis_widths = []
+    for f in setup_frames:
+        lmf = pose_data.get(f)
+        if not lmf or not lmf[L_HIP] or not lmf[R_HIP]:
+            continue
+        # prefer low-yaw frames if world_landmarks are available
+        if world_landmarks and f in world_landmarks:
+            _yaw = _estimate_torso_yaw_3d(world_landmarks[f]) or 0.0
+            if _yaw > 25.0:
+                continue
+        w, _ = _width_px_derolled(lmf, L_HIP, R_HIP, roll)
+        if w > 1.0:
+            setup_pelvis_widths.append(w)
+
+    pel_setup_med = float(np.median(setup_pelvis_widths)) if setup_pelvis_widths else None
+
+    # Decide if we must de-yaw: narrow shoulders or big yaw
+    need_deyaw = (W is not None and sho_dx_r < 0.08*W) or (world_landmarks and not yaw_ok)
+
+    # Build corrected horizontal width
+    dx_corr = sho_dx_r
+    deyaw_ratio = 1.0
+    if need_deyaw and pel_setup_med and pel_dx_r > 1.0:
+        # De-yaw using pelvis scale ratio; clamp to avoid blowups
+        deyaw_ratio = pel_setup_med / pel_dx_r
+        deyaw_ratio = max(1.0, min(deyaw_ratio, 8.0))        # 1×..8×
+        dx_corr = sho_dx_r * deyaw_ratio
+
+    # As an optional second path (if 3D exists & stable), use 3D shoulder length
+    if need_deyaw and world_landmarks and impact_f in world_landmarks:
+        wf = world_landmarks[impact_f]
+        if wf and wf[L_SHO] and wf[R_SHO]:
+            Ls, Rs = wf[L_SHO], wf[R_SHO]
+            L3D = math.hypot(Rs[0]-Ls[0], Rs[2]-Ls[2])  # horizontal shoulder sep in XZ (meters, scale-free wrt yaw)
+            # Calibrate px-per-meter from setup shoulders (robust to yaw via pelvis ratio)
+            if L3D > 1e-6 and setup_frames:
+                px_per_m = None
+                for f in setup_frames:
+                    if f in world_landmarks and pose_data.get(f):
+                        wf_s, lm_s = world_landmarks[f], pose_data[f]
+                        if wf_s and lm_s and lm_s[L_SHO] and lm_s[R_SHO]:
+                            sx, _ = _width_px_derolled(lm_s, L_SHO, R_SHO, roll)
+                            L3D_s = None
+                            if wf_s[L_SHO] and wf_s[R_SHO]:
+                                L3D_s = math.hypot(wf_s[R_SHO][0]-wf_s[L_SHO][0], wf_s[R_SHO][2]-wf_s[L_SHO][2])
+                            if sx > 1.0 and L3D_s and L3D_s > 1e-6:
+                                px_per_m = sx / L3D_s
+                                break
+                if px_per_m:
+                    dx_corr_3d = L3D * px_per_m
+                    dx_corr = max(dx_corr, dx_corr_3d)  # take the more conservative (larger) width
+
+    # Now compute tilt using corrected horizontal width and derolled vertical
+    if abs(dx_corr) + abs(sho_dy_r) < 1e-8:
+        return None
+    
+    tilt_mag = math.degrees(math.atan2(abs(sho_dy_r), max(dx_corr, 1e-3)))
+    trail_lower = (sho_dy_r > 0) if handedness=='right' else (sho_dy_r < 0)
+    tilt_final = tilt_mag if trail_lower else -tilt_mag
+
+    # Plausibility clamp for front-facing tilt (pros ~30-45°)
+    if abs(tilt_final) < 10.0 or abs(tilt_final) > 70.0:
+        # If we still look crazy, median over ±1 frame
+        neigh = []
+        for f in [impact_f-1, impact_f, impact_f+1]:
+            if f in pose_data and pose_data[f] and pose_data[f][L_SHO] and pose_data[f][R_SHO]:
+                sx, sy = _width_px_derolled(pose_data[f], L_SHO, R_SHO, roll)
+                px, _  = _width_px_derolled(pose_data[f], L_HIP, R_HIP, roll)
+                if pel_setup_med and px > 1.0:
+                    r = max(1.0, min(pel_setup_med/px, 8.0))
+                    t = math.degrees(math.atan2(abs(sy), max(sx*r, 1e-3)))
+                    sgn = (sy > 0) if handedness=='right' else (sy < 0)
+                    neigh.append(t if sgn else -t)
+        if neigh:
+            tilt_final = float(np.median(neigh))
+    
+    # Hard reroute for problematic cases (already handled by hybrid path above)
+    if not yaw_ok or (W is not None and sho_dx_r < 0.08*W):
+        # force hybrid path (already handled above). Also avoid labeling as "final"
+        pass
+    
+    # Sanity clamp and flags
+    definition_suspect = False
+    if not (10.0 <= abs(tilt_final) <= 70.0):
+        definition_suspect = True
+    
+    if not quality_ok or not yaw_ok:
+        definition_suspect = True
+    
+    # Debug output with de-yaw info
+    unit_note = " (units_detected_as_pixels)" if max(abs(dx_raw), abs(dy_raw)) > 2.0 else ""
+    yaw_note = f" yaw_ok={yaw_ok}" if world_landmarks else ""
+    deyaw_note = f" hybrid_deyaw r={deyaw_ratio:.1f}, dx_corr={dx_corr:.1f}" if need_deyaw else ""
+    print(f"DEBUG shoulder_tilt: sho_dx_r={sho_dx_r:.1f}, sho_dy_r={sho_dy_r:.1f}, roll={roll:.1f}°{deyaw_note}, "
+          f"tilt={tilt_final:.1f}°{unit_note}{yaw_note}, suspect={definition_suspect}")
+    
+    if pel_setup_med and pel_dx_r > 1.0:
+        print(f"DEBUG shoulder_tilt: pel_setup_med={pel_setup_med:.1f}, pel_dx_r={pel_dx_r:.1f}")
+
+    return max(-70.0, min(70.0, tilt_final))
+
+
+
+
+
+
+def pelvis_hat(world_frame):
+    """Get unit pelvis vector (R_hip - L_hip) in XZ plane"""
+    try:
+        L = world_frame[L_HIP]  # Left hip (23)
+        R = world_frame[R_HIP]  # Right hip (24)
+        return unit2((R[0]-L[0], R[2]-L[2]))
+    except Exception:
+        return None
+
+def _target_hat_from_toes_world(world_landmarks, setup_frames, handedness='right'):
+    """Build stable target axis from toe line at address"""
+    LEFT_TOE, RIGHT_TOE = 31, 32
+    
+    toe_vecs = []
+    for f in setup_frames:
+        if f in world_landmarks:
+            frame = world_landmarks[f]
+            if frame and len(frame) > 32:
+                try:
+                    Ltoe = frame[LEFT_TOE]
+                    Rtoe = frame[RIGHT_TOE]
+                    if Ltoe and Rtoe and len(Ltoe) >= 3 and len(Rtoe) >= 3:
+                        toe_vec = (Rtoe[0]-Ltoe[0], Rtoe[2]-Ltoe[2])
+                        if (toe_vec[0]**2 + toe_vec[1]**2) > 1e-6:
+                            toe_vecs.append(toe_vec)
+                except Exception:
+                    continue
+    
+    if not toe_vecs:
+        dbg("target_axis - NO VALID TOE VECTORS, using default")
+        return (1.0, 0.0)
+    
+    # Target axis is parallel to toe line (not perpendicular)
+    target_hat = unit2(np.median(toe_vecs, axis=0))
+    
+    # Optional: flip sign for consistency if you want +X toward target for left-handed
+    if handedness == 'left':
+        target_hat = (-target_hat[0], -target_hat[1])
+    
+    return target_hat
+
+
+def _simple_pixel_sway_fallback(sm, setup_frames, top_frame):
+    """Simple pixel-based sway fallback that ALWAYS returns a value"""
+    # Get pelvis centers in pixels
+    def get_pelvis_center_px(frame_idx):
+        lm = sm.get(frame_idx)
+        if not lm or not lm[23] or not lm[24]:
+            return None
+        return [(lm[23][0] + lm[24][0]) / 2, (lm[23][1] + lm[24][1]) / 2]
+    
+    # Setup center (median)
+    setup_centers = [get_pelvis_center_px(f) for f in setup_frames]
+    setup_centers = [c for c in setup_centers if c is not None]
+    if not setup_centers:
+        return 0.0  # Default value if no setup data
+    setup_ctr = np.median(setup_centers, axis=0)
+    
+    # Top center
+    top_ctr = get_pelvis_center_px(top_frame)
+    if top_ctr is None:
+        return 0.0  # Default value if no top data
+    
+    # Simple horizontal movement in pixels, convert with rough estimate
+    delta_px = top_ctr[0] - setup_ctr[0]
+    # Rough conversion: assume ~10 pixels per inch (typical for phone videos)
+    sway_inches = delta_px / 10.0
+    
+    return float(sway_inches)
+
+
+def _subframe_impact_refinement(world_landmarks: Dict[int, List], impact_candidate: int) -> float:
+    """
+    Refine impact timing to sub-frame precision using parabolic fit to hand speed
+    Fits parabola around the impact candidate and returns fractional frame timestamp
+    """
+    try:
+        # Get frames around impact candidate for parabolic fit
+        test_frames = [f for f in range(impact_candidate-2, impact_candidate+3) 
+                      if f in world_landmarks]
+        
+        if len(test_frames) < 3:
+            return float(impact_candidate)  # Not enough data for refinement
+        
+        # Calculate hand speeds around impact
+        speeds = []
+        frame_indices = []
+        
+        for i in range(1, len(test_frames)):
+            f_curr = test_frames[i]
+            f_prev = test_frames[i-1]
+            
+            curr_frame = world_landmarks[f_curr]
+            prev_frame = world_landmarks[f_prev]
+            
+            if (curr_frame and len(curr_frame) > 16 and 
+                prev_frame and len(prev_frame) > 16 and
+                curr_frame[16] and prev_frame[16]):
+                
+                curr_wrist = curr_frame[16]
+                prev_wrist = prev_frame[16]
+                
+                # Calculate 3D speed
+                dx = curr_wrist[0] - prev_wrist[0]
+                dy = curr_wrist[1] - prev_wrist[1] 
+                dz = curr_wrist[2] - prev_wrist[2]
+                speed = math.sqrt(dx*dx + dy*dy + dz*dz)
+                
+                speeds.append(speed)
+                frame_indices.append(f_curr)
+        
+        if len(speeds) < 3:
+            return float(impact_candidate)
+        
+        # Fit parabola to speed curve: speed = a*t^2 + b*t + c
+        # Find peak (maximum) of parabola
+        t = np.array(frame_indices, dtype=float)
+        s = np.array(speeds)
+        
+        # Polynomial fit (degree 2)
+        coeffs = np.polyfit(t, s, 2)
+        a, b, c = coeffs
+        
+        if a >= 0:  # Parabola opens upward → no maximum
+            return float(impact_candidate)
+        
+        # Maximum at t = -b/(2a)
+        peak_frame_fractional = -b / (2*a)
+        
+        # Impact happens just before peak (typically 0.5-1.0 frames before)
+        # Use the original logic of peak-1, but with fractional precision
+        impact_fractional = peak_frame_fractional - 0.7  # Refined offset
+        
+        # Constrain to reasonable range around original estimate
+        if abs(impact_fractional - impact_candidate) > 2.0:
+            impact_fractional = float(impact_candidate)
+        
+        print(f"DEBUG: subframe_refinement - parabola_coeffs=[{a:.6f}, {b:.6f}, {c:.6f}]")
+        print(f"DEBUG: subframe_refinement - peak_frame={peak_frame_fractional:.2f}, impact_refined={impact_fractional:.2f}")
+        
+        return impact_fractional
+        
+    except Exception as e:
+        print(f"DEBUG: subframe_refinement - failed: {e}, using integer frame")
+        return float(impact_candidate)
+
+
+def _address_frames(swing_phases: Dict[str, List]) -> List[int]:
+    """Get address/setup frames"""
+    return swing_phases.get("setup", [])[:10]
+
+def _impact_frame(world_landmarks: Dict[int, List], swing_phases: Dict[str, List]) -> Optional[int]:
+    """Find impact using peak lead-hand speed - 1 frame with inline refinement"""
+    downswing_frames = swing_phases.get("downswing", [])
+    impact_frames = swing_phases.get("impact", [])
+    
+    analysis_frames = sorted(downswing_frames + impact_frames)
+    if len(analysis_frames) < 5:
+        return impact_frames[0] if impact_frames else None
+    
+    # Calculate hand speeds
+    hand_speeds = []
+    valid_frames = []
+    
+    for i in range(1, len(analysis_frames)):
+        f_curr = analysis_frames[i]
+        f_prev = analysis_frames[i-1]
+        
+        if f_curr in world_landmarks and f_prev in world_landmarks:
+            curr_frame = world_landmarks[f_curr]
+            prev_frame = world_landmarks[f_prev]
+            
+            if (curr_frame and len(curr_frame) > 16 and 
+                prev_frame and len(prev_frame) > 16):
+                
+                # Use lead hand (left wrist for right-handed golfer)
+                wrist_idx = 15  # Lead wrist for right-handed
+                curr_wrist = curr_frame[wrist_idx]
+                prev_wrist = prev_frame[wrist_idx]
+                
+                if (curr_wrist and len(curr_wrist) >= 3 and 
+                    prev_wrist and len(prev_wrist) >= 3):
+                    
+                    dx = curr_wrist[0] - prev_wrist[0]
+                    dy = curr_wrist[1] - prev_wrist[1]
+                    dz = curr_wrist[2] - prev_wrist[2]
+                    speed = math.sqrt(dx*dx + dy*dy + dz*dz)
+                    
+                    hand_speeds.append(speed)
+                    valid_frames.append(f_curr)
+    
+    if len(hand_speeds) >= 3:
+        # Find peak speed frame
+        max_speed_idx = np.argmax(hand_speeds)
+        peak_speed_frame = valid_frames[max_speed_idx]
+        
+        # Initial estimate: peak speed - 1 frame 
+        impact_candidate = peak_speed_frame
+        if max_speed_idx > 0:
+            impact_candidate = valid_frames[max_speed_idx - 1]
+        
+        # Optional quadratic refinement
+        try:
+            test_frames = [f for f in range(impact_candidate-1, impact_candidate+2) 
+                          if f in world_landmarks]
+            if len(test_frames) >= 3:
+                speeds = []
+                for f in test_frames:
+                    if f in valid_frames:
+                        idx = valid_frames.index(f)
+                        speeds.append(hand_speeds[idx])
+                
+                if len(speeds) >= 3:
+                    coeffs = np.polyfit(test_frames, speeds, 2)
+                    a, b, c = coeffs
+                    if a < 0:  # Parabola opens downward
+                        peak_fractional = -b / (2*a)
+                        impact_refined = peak_fractional - 1.0
+                        if abs(impact_refined - impact_candidate) <= 2.0:
+                            impact_candidate = int(round(impact_refined))
+        except:
+            pass
+        
+        # Clamp to ±2 frames around original estimate
+        original = valid_frames[max_speed_idx - 1] if max_speed_idx > 0 else peak_speed_frame
+        impact_candidate = max(original - 2, min(original + 2, impact_candidate))
+        
+        return impact_candidate
+    
+    return impact_frames[0] if impact_frames else None
+
+
+def _conf3d(world_landmarks, impact_frame, setup_frames):
+    """Compute 3D confidence and pelvis change in one function"""
+    if not world_landmarks or impact_frame not in world_landmarks:
+        return 0.0, 100.0
+    
+    try:
+        # Check frames around impact for stability
+        test_frames = [f for f in range(impact_frame-2, impact_frame+3) if f in world_landmarks]
+        if len(test_frames) < 3:
+            return 0.3, 100.0
+        
+        yaws = []
+        z_positions = []
+        
+        for f in test_frames:
+            frame = world_landmarks[f]
+            if frame and len(frame) > 24 and frame[23] and frame[24]:
+                ph = pelvis_hat(frame)
+                if ph is not None:
+                    yaw_approx = math.degrees(math.atan2(ph[1], ph[0]))
+                    yaws.append(yaw_approx)
+                    
+                    # Z position (depth stability)
+                    lz, rz = frame[23][2], frame[24][2]
+                    z_positions.append((lz + rz) / 2)
+        
+        if len(yaws) < 3:
+            return 0.3, 100.0
+        
+        # Compute stability metrics
+        yaw_std = np.std(yaws)
+        z_std = np.std(z_positions)
+        
+        # Pelvis length change from setup
+        setup_pelvis_lens = []
+        for f in setup_frames[:5]:
+            if f in world_landmarks:
+                frame = world_landmarks[f]
+                if frame and len(frame) > 24 and frame[23] and frame[24]:
+                    lx, lz = frame[23][0], frame[23][2]
+                    rx, rz = frame[24][0], frame[24][2]
+                    setup_pelvis_lens.append(math.sqrt((rx-lx)**2 + (rz-lz)**2))
+        
+        pelvis_change_pct = 100.0
+        if setup_pelvis_lens:
+            impact_frame_data = world_landmarks[impact_frame]
+            if (impact_frame_data and len(impact_frame_data) > 24 and 
+                impact_frame_data[23] and impact_frame_data[24]):
+                lx, lz = impact_frame_data[23][0], impact_frame_data[23][2]
+                rx, rz = impact_frame_data[24][0], impact_frame_data[24][2]
+                impact_pelvis_len = math.sqrt((rx-lx)**2 + (rz-lz)**2)
+                
+                avg_setup = np.mean(setup_pelvis_lens)
+                if avg_setup > 0:
+                    pelvis_change_pct = abs(impact_pelvis_len - avg_setup) / avg_setup * 100
+        
+        # Score components (higher = better)
+        yaw_score = max(0, 1.0 - yaw_std / 5.0)  # Good if <5° std
+        pelvis_score = max(0, 1.0 - pelvis_change_pct / 15.0)  # Good if <15% change
+        z_score = max(0, 1.0 - z_std / 0.05)  # Good if <5cm Z std
+        
+        # Combined confidence
+        conf_3d = (yaw_score * 0.4 + pelvis_score * 0.4 + z_score * 0.2)
+        
+        if pelvis_change_pct > 15.0:
+            dbg(f"3D_conf - pelvis_change={pelvis_change_pct:.1f}% suggests occlusion")
+        
+        return max(0.0, min(1.0, conf_3d)), pelvis_change_pct
+        
+    except Exception:
+        return 0.3, 100.0
+
+def _compute_2d_confidence(pose_data, swing_phases, setup_frames):
+    """
+    Compute 2D confidence based on homography quality and geometric consistency
+    Returns confidence score 0.0-1.0
+    """
+    try:
+        sm = smooth_landmarks(pose_data)
+        H, valid_H, reason = _build_ground_homography(sm, setup_frames)
+        
+        if not valid_H:
+            return 0.0
+        
+        # Check target/toe angle consistency
+        target_vecs_2d = []
+        toe_vecs_2d = []
+        
+        for f in setup_frames[:3]:
+            lm = sm.get(f)
+            if lm and len(lm) > 32 and lm[31] and lm[32]:
+                # Toe vector in ground plane
+                toe_img = [[lm[31][0], lm[31][1]], [lm[32][0], lm[32][1]]]
+                try:
+                    import cv2
+                    toe_ground = cv2.perspectiveTransform(np.array(toe_img, dtype=np.float32).reshape(1,-1,2), H)[0]
+                    toe_vec = toe_ground[1] - toe_ground[0]
+                    norm = np.linalg.norm(toe_vec)
+                    if norm > 1e-6:
+                        toe_vecs_2d.append(toe_vec / norm)
+                        # Target perpendicular to toe
+                        target_vec = np.array([-toe_vec[1], toe_vec[0]]) / norm
+                        target_vecs_2d.append(target_vec)
+                except:
+                    continue
+        
+        if not target_vecs_2d:
+            return 0.2
+        
+        # Check consistency of target direction
+        target_consistency = 1.0 - np.std([math.degrees(math.atan2(tv[1], tv[0])) for tv in target_vecs_2d]) / 10.0
+        
+        # Check toe-target perpendicularity
+        toe_target_angles = []
+        for toe_vec, target_vec in zip(toe_vecs_2d, target_vecs_2d):
+            angle = abs(math.degrees(math.acos(np.clip(np.dot(toe_vec, target_vec), -1, 1))))
+            toe_target_angles.append(abs(angle - 90.0))
+        
+        perp_score = max(0, 1.0 - np.mean(toe_target_angles) / 5.0)  # Good if within 5° of 90°
+        
+        # Homography quality score (det and error already checked in valid_H)
+        h_score = 0.8 if valid_H else 0.0
+        
+        conf_2d = (target_consistency * 0.3 + perp_score * 0.4 + h_score * 0.3)
+        
+        
+        return max(0.0, min(1.0, conf_2d))
+        
+    except Exception:
+        return 0.0
+
+def calculate_hip_turn_at_impact(
+    pose_data: Dict[int, List],
+    swing_phases: Dict[str, List],
+    world_landmarks: Optional[Dict[int, List]] = None,
+    frames: Optional[List[np.ndarray]] = None
+) -> Union[float, None]:
+    """
+    Hip turn @ impact: TARGET-RELATIVE degrees (positive = open to target).
+    Fixed to use target line reference instead of camera-relative angles.
+    """
+    PLAUSIBLE = 70.0
+
+    if not world_landmarks:
+        # Fallback: calculate from 2D pose data only
+        return _calculate_hip_turn_2d_fallback(pose_data, swing_phases, _impact_frame(pose_data, swing_phases))
+    
+    # Get setup frames for target axis and baseline
+    setup_frames = swing_phases.get("setup", [])[:10]
+    if not setup_frames:
+        # Fallback: use first available frames as "setup"
+        all_frames = sorted(world_landmarks.keys())
+        if all_frames:
+            setup_frames = all_frames[:min(5, len(all_frames))]
+        else:
+            return _calculate_hip_turn_2d_fallback(pose_data, swing_phases, _impact_frame(pose_data, swing_phases))
+        
+    # Build stable target axis from toe line
+    target_hat = _target_hat_from_toes_world(world_landmarks, setup_frames, handedness='right')
+    
+    # Impact frame detection
+    impact_f = _impact_frame(world_landmarks, swing_phases)
+    if impact_f is None or impact_f not in world_landmarks:
+        # Fallback: use 2D calculation
+        return _calculate_hip_turn_2d_fallback(pose_data, swing_phases, _impact_frame(pose_data, swing_phases))
+    
+    # Get pelvis direction at impact
+    impact_pelvis_hat = pelvis_hat(world_landmarks[impact_f])
+    
+    if impact_pelvis_hat is None:
+        # Fallback: use 2D calculation
+        return _calculate_hip_turn_2d_fallback(pose_data, swing_phases, impact_f)
+    
+    # ±1 frame median for stability at impact
+    impact_frames_nearby = [f for f in range(impact_f-1, impact_f+2) if f in world_landmarks]
+    if len(impact_frames_nearby) > 1:
+        impact_rels = []
+        for f in impact_frames_nearby:
+            ph = pelvis_hat(world_landmarks[f])
+            if ph is not None:
+                impact_rels.append(signed_angle2(target_hat, ph))
+        if impact_rels:
+            impact_rel = np.median(impact_rels)
+        else:
+            impact_rel = signed_angle2(target_hat, impact_pelvis_hat)
+    else:
+        impact_rel = signed_angle2(target_hat, impact_pelvis_hat)
+    
+    # Hip turn = absolute open angle vs target at impact (not delta from setup)
+    hip_turn_abs = wrap180(impact_rel)
+    
+    # 3D confidence check
+    conf_3d, pelvis_change_pct = _conf3d(world_landmarks, impact_f, setup_frames)
+    
+    # Use 3D if high confidence and stable pelvis
+    if conf_3d >= 0.75 and pelvis_change_pct <= 15.0:
+        final_turn = hip_turn_abs
+    else:
+        # Try 2D fallback
+        turn_2d = _calculate_hip_turn_2d_fallback(pose_data, swing_phases, impact_f)
+        if turn_2d is not None:
+            _, valid_H, _ = _build_ground_homography(smooth_landmarks(pose_data), setup_frames)
+            if valid_H and abs(hip_turn_abs - turn_2d) <= 20.0:
+                final_turn = turn_2d
+                dbg(f"hip_turn - using 2D fallback: {turn_2d:.1f}°")
+            else:
+                final_turn = hip_turn_abs
+        else:
+            final_turn = hip_turn_abs
+            if conf_3d < 0.75 or pelvis_change_pct > 15.0:
+                dbg(f"hip_turn - 3D unreliable (conf={conf_3d:.3f}, pelvis_change={pelvis_change_pct:.1f}%)")
+    
+    # Plausible check - but ALWAYS return something
+    if abs(final_turn) > PLAUSIBLE:
+        if conf_3d < 0.8:
+            dbg(f"hip_turn - VALUE {final_turn:.1f}° EXCEEDS PLAUSIBLE RANGE, clamping")
+            # Clamp to reasonable range rather than returning None
+            final_turn = PLAUSIBLE if final_turn > 0 else -PLAUSIBLE
+    return float(final_turn)
+
+
+def _build_ground_homography(sm, setup_frames):
+    """Build ground-plane homography using RANSAC"""
+    try:
+        import cv2
+        
+        # Find best setup frame with all required landmarks
+        best_frame = None
+        for f in setup_frames:
+            lm = sm.get(f)
+            if lm and len(lm) > 31:
+                # Check we have feet landmarks + hips for ground plane
+                if (lm[27] and lm[28] and lm[31] and lm[32] and lm[23] and lm[24] and
+                    all(lm[i][2] > 0.5 for i in [27,28,31,32,23,24])):
+                    best_frame = f
+                    break
+        
+        if best_frame is None:
+            return None, False, "no_landmarks"
+            
+        lm = sm[best_frame]
+        
+        # 4 ground points: heel tips + ball center + back marker
+        img_pts = np.array([
+            [lm[31][0], lm[31][1]],  # L heel tip
+            [lm[32][0], lm[32][1]],  # R heel tip  
+            [(lm[31][0] + lm[32][0]) / 2, min(lm[31][1], lm[32][1]) + 40],  # Ball center (estimated)
+            [(lm[23][0] + lm[24][0]) / 2, (lm[23][1] + lm[24][1]) / 2 + 20]  # Back marker (hip depth)
+        ], dtype=np.float32)
+        
+        # Ground coordinates (inches)
+        ground_pts = np.array([
+            [-10, 0], [10, 0], [0, 30], [0, -8]
+        ], dtype=np.float32)
+        
+        # RANSAC homography fitting
+        H, mask = cv2.findHomography(img_pts, ground_pts, cv2.RANSAC, 
+                                   ransacReprojThreshold=2.0)
+        
+        if H is None:
+            return None, False, "ransac_failed"
+        
+        
+        # Validation criteria - only check for non-singular matrix
+        det_H = abs(np.linalg.det(H[:2,:2])) 
+        valid_H = det_H > 1e-4
+        
+        reason = "ok" if valid_H else "singular"
+        
+        return H, valid_H, reason
+        
+    except Exception as e:
+        return None, False, "exception"
+
+def _calculate_hip_turn_2d_fallback(pose_data: Dict[int, List], swing_phases: Dict[str, List], impact_frame: int) -> Optional[float]:
+    """
+    TRUE 2D ground-plane fallback using homography
+    Only used if homography is valid and consistent
+    """
+    sm = smooth_landmarks(pose_data)
+    setup_frames = swing_phases.get("setup", [])[:5]
+    if not setup_frames:
+        # Use first available frames as setup
+        all_frames = sorted(pose_data.keys())
+        if all_frames:
+            setup_frames = all_frames[:min(5, len(all_frames))]
+        else:
+            return None
+    
+    # Handle None impact frame
+    if impact_frame is None:
+        # Use last available frame as impact
+        all_frames = sorted(pose_data.keys())
+        if all_frames:
+            impact_frame = all_frames[-1]
+        else:
+            return None
+    
+    # Build ground-plane homography
+    H, valid_H, reason = _build_ground_homography(sm, setup_frames)
+    if not valid_H:
+        print(f"DEBUG: 2D_fallback - INVALID HOMOGRAPHY: {reason}")
+        return None
+        
+    try:
+        import cv2
+        
+        def warp_pts(pts_img):
+            """Project image points to ground plane"""
+            pts_array = np.array(pts_img, dtype=np.float32).reshape(1, -1, 2)
+            ground_pts = cv2.perspectiveTransform(pts_array, H)[0]
+            return ground_pts
+        
+        # Get ground-plane toe direction for target axis
+        toe_vecs_ground = []
+        for f in setup_frames:
+            lm = sm.get(f)
+            if lm and len(lm) > 32 and lm[31] and lm[32]:
+                toe_img = [[lm[31][0], lm[31][1]], [lm[32][0], lm[32][1]]]
+                toe_ground = warp_pts(toe_img)
+                toe_vec = toe_ground[1] - toe_ground[0]  # Right - Left
+                norm = np.linalg.norm(toe_vec)
+                if norm > 1e-6:
+                    toe_vecs_ground.append(toe_vec / norm)
+        
+        if not toe_vecs_ground:
+            return None
+            
+        toe_hat_2d = np.median(toe_vecs_ground, axis=0)
+        # Target is parallel to toe line (not perpendicular)
+        target_hat_2d = toe_hat_2d
+        
+        # Get pelvis directions in ground plane
+        def pelvis_hat_ground(frame_idx):
+            lm = sm.get(frame_idx)
+            if not lm or len(lm) <= 24 or not lm[23] or not lm[24]:
+                return None
+            hip_img = [[lm[23][0], lm[23][1]], [lm[24][0], lm[24][1]]]
+            hip_ground = warp_pts(hip_img)
+            pelvis_vec = hip_ground[1] - hip_ground[0]  # Right - Left
+            norm = np.linalg.norm(pelvis_vec)
+            return pelvis_vec / norm if norm > 1e-6 else None
+        
+        # Impact pelvis direction
+        impact_pelvis_hat = pelvis_hat_ground(impact_frame)
+        
+        if impact_pelvis_hat is None:
+            return None
+        
+        # Absolute target-relative angle at impact (not delta from setup)
+        impact_rel = signed_angle2(target_hat_2d, impact_pelvis_hat)
+        turn_2d = wrap180(impact_rel)
+        
+        
+        return float(turn_2d)
+        
+    except Exception:
+        return None
+
+
+
+
+
+
+
+
+def calculate_hip_sway_at_top(pose_data: Dict[int, List], swing_phases: Dict[str, List], 
+                             world_landmarks: Optional[Dict[int, List]] = None) -> Union[float, None]:
+    """Calculate hip sway at top using 2D homography projection along toe/target axis"""
+    smoothed_pose_data = smooth_landmarks(pose_data)
+    
+    setup_frames = _address_frames(swing_phases)
+    if not setup_frames:
+        return None
+    
+    # Find top frame
+    backswing_frames = swing_phases.get("backswing", [])
+    if not backswing_frames:
+        return None
+    
+    top_frame = _pick_top_frame_hinge(smoothed_pose_data, backswing_frames, handed='right')
+    if top_frame is None:
+        top_frame = backswing_frames[-1]
+    
+    # Use 2D homography as primary method (world landmarks can re-center per frame)
+    H, valid_H, _ = _build_ground_homography(smoothed_pose_data, setup_frames)
+    if not valid_H:
+        # ALWAYS DISPLAY SOMETHING - fallback to simple pixel measurement if homography fails
+        return _simple_pixel_sway_fallback(smoothed_pose_data, setup_frames, top_frame)
+        
+    try:
+        import cv2
+        
+        def pelvis_center_ground(frame_idx):
+            lm = smoothed_pose_data.get(frame_idx)
+            if not lm or not lm[23] or not lm[24]:
+                return None
+            hip_img = np.array([[lm[23][0], lm[23][1]], [lm[24][0], lm[24][1]]], dtype=np.float32)
+            g = cv2.perspectiveTransform(hip_img.reshape(1,-1,2), H)[0]
+            return (g[0] + g[1]) / 2
+        
+        # Toe direction (ground) = target axis
+        toe_vecs = []
+        for f in setup_frames:
+            lm = smoothed_pose_data.get(f)
+            if lm and lm[31] and lm[32]:
+                toe_img = np.array([[lm[31][0], lm[31][1]], [lm[32][0], lm[32][1]]], dtype=np.float32)
+                toe_g = cv2.perspectiveTransform(toe_img.reshape(1,-1,2), H)[0]
+                v = toe_g[1] - toe_g[0]
+                n = np.linalg.norm(v)
+                if n > 1e-6:
+                    toe_vecs.append(v/n)
+        
+        if not toe_vecs:
+            return None
+            
+        target_hat_g = np.median(toe_vecs, axis=0)  # unit 2D vector in ground coords
+        
+        # Setup center (median)
+        setup_centers = [pelvis_center_ground(f) for f in setup_frames]
+        setup_centers = [c for c in setup_centers if c is not None]
+        if not setup_centers:
+            return None
+        setup_ctr = np.median(setup_centers, axis=0)
+        
+        # Top center
+        top_ctr = pelvis_center_ground(top_frame)
+        if top_ctr is None:
+            return None
+        
+        # Project movement onto toe/target axis
+        delta = top_ctr - setup_ctr
+        sway_inches = float(np.dot(delta, target_hat_g))  # ground_pts are in inches already
+        return sway_inches
+        
+    except Exception:
+        # ALWAYS DISPLAY SOMETHING - fallback if homography projection fails
+        return _simple_pixel_sway_fallback(smoothed_pose_data, setup_frames, top_frame)
+
+
+
+
+def angle_between(u, v):
+    """Calculate angle between two vectors in degrees (0-180)"""
+    u, v = np.array(u, float), np.array(v, float)
+    nu, nv = np.linalg.norm(u), np.linalg.norm(v)
+    if nu == 0 or nv == 0:
+        return float('nan')
+    c = np.clip(np.dot(u, v) / (nu * nv), -1, 1)
+    return math.degrees(math.acos(c))  # 0..180
+
+
+
+def _hinge2d(lm, handed='right'):
+    """Simple 2D hinge angle: elbow-wrist vs wrist-index (robust, repeatable)"""
+    if not lm:
+        return None
+    EL, WR = (13, 15) if handed=='right' else (14, 16)  # Lead arm
+    IM = 19 if handed=='right' else 20
+    if not lm[EL] or not lm[WR] or not lm[IM]:
+        return None
+    
+    u = np.array([lm[WR][0]-lm[EL][0], lm[WR][1]-lm[EL][1]], float)  # forearm
+    v = np.array([lm[IM][0]-lm[WR][0], lm[IM][1]-lm[WR][1]], float)  # hand
+    nu, nv = np.linalg.norm(u), np.linalg.norm(v)
+    if nu < 1e-6 or nv < 1e-6:
+        return None
+    
+    ang = math.degrees(math.acos(np.clip(np.dot(u,v)/(nu*nv), -1, 1)))  # 0..180
+    return 180.0 - ang  # more hinge → larger value
+
+
+
+
+
+
+
+def _pick_top_frame_hinge(sm, backswing_frames, handed='right'):
+    """Pick frame with maximum hinge in backswing"""
+    if not backswing_frames:
+        return None
+    
+    # Top = max hinge in backswing
+    top_vals = [(f, _hinge2d(sm.get(f), handed)) for f in backswing_frames]
+    top_vals = [(f, h) for f, h in top_vals if h is not None]
+    if not top_vals:
+        return None
+    
+    top_frame, hinge_top = max(top_vals, key=lambda x: x[1])
+    return top_frame
+
+
+
+
+
+
+
+
+def calculate_wrist_hinge_at_top(pose_data: Dict[int, List], swing_phases: Dict[str, List], 
+                                frames: Optional[List[np.ndarray]] = None) -> Union[Dict[str, float], None]:
+    """Calculate wrist hinge using simple 2D angle method"""
+    sm = smooth_landmarks(pose_data)
+    
+    backswing_frames = swing_phases.get("backswing", [])
+    if not backswing_frames:
+        # Fallback: use any available frames as "backswing"
+        all_frames = sorted(pose_data.keys())
+        if all_frames:
+            # Use middle third of available frames as "backswing"
+            mid_start = len(all_frames) // 3
+            mid_end = 2 * len(all_frames) // 3
+            backswing_frames = all_frames[mid_start:mid_end] or all_frames
+        else:
+            return None  # Truly no data
+    
+    # Top = max hinge in backswing
+    top_frame = _pick_top_frame_hinge(sm, backswing_frames, handed='right')
+    if top_frame is None:
+        top_frame = backswing_frames[-1]  # Use last frame as fallback
+    
+    hinge_top = _hinge2d(sm.get(top_frame), handed='right')
+    if hinge_top is None:
+        # Try to find any frame with valid hinge data
+        for frame_idx in backswing_frames:
+            test_hinge = _hinge2d(sm.get(frame_idx), handed='right')
+            if test_hinge is not None:
+                hinge_top = test_hinge
+                break
+        if hinge_top is None:
+            return None  # Truly no wrist data available
+    
+    # Address median for delta calculation
+    setup_frames = _address_frames(swing_phases)
+    addr_vals = [_hinge2d(sm.get(f), handed='right') for f in setup_frames[:5]]
+    addr_vals = [h for h in addr_vals if h is not None]
+    hinge_addr = np.median(addr_vals) if addr_vals else None
+
+    result = {"radial_deviation_deg": hinge_top}
+    if hinge_addr is not None:
+        delta = hinge_top - hinge_addr
+        result["delta_deg"] = delta
+        
+        # Quality check for typical range
+        if not (15.0 <= delta <= 50.0):
+            result["definition_suspect"] = True
+    
+    return result
+
+
+def compute_front_facing_metrics(pose_data: Dict[int, List], swing_phases: Dict[str, List], 
+                                world_landmarks: Optional[Dict[int, List]] = None,
+                                frames: Optional[List[np.ndarray]] = None) -> Dict[str, Dict[str, Union[float, None]]]:
+    """Compute the 4 required front-facing golf swing metrics"""
+    
+    # Calculate individual metrics
+    shoulder_tilt_impact = calculate_shoulder_tilt_at_impact(
+        pose_data, swing_phases, world_landmarks, frames=frames
+    )
+    hip_turn_impact = calculate_hip_turn_at_impact(pose_data, swing_phases, world_landmarks, frames)
+    hip_sway_top = calculate_hip_sway_at_top(pose_data, swing_phases, world_landmarks)
+    wrist_hinge_result = calculate_wrist_hinge_at_top(pose_data, swing_phases, frames)
+    
+    # Extract wrist hinge values
+    wrist_radial_dev = wrist_hinge_result.get('radial_deviation_deg') if wrist_hinge_result else None
+    wrist_hinge_delta = wrist_hinge_result.get('delta_deg') if wrist_hinge_result else None
+    definition_suspect = wrist_hinge_result.get('definition_suspect', False) if wrist_hinge_result else False
+    
+    # ALWAYS DISPLAY A METRIC - use delta first, then absolute as fallback
+    wrist_final = wrist_hinge_delta
+    if wrist_final is None and wrist_radial_dev is not None:
+        wrist_final = wrist_radial_dev  # Use absolute as fallback
+        
+    front_facing_metrics = {
+        'shoulder_tilt_impact_deg': {'value': shoulder_tilt_impact},
+        'hip_turn_impact_deg': {'value': hip_turn_impact},
+        'hip_sway_top_inches': {'value': hip_sway_top},
+        'wrist_hinge_top_deg': {'value': wrist_final}
+    }
+    
+    return front_facing_metrics