kinemotion 0.36.0__py3-none-any.whl → 0.36.1__py3-none-any.whl

kinemotion/api.py

@@ -417,6 +417,13 @@ def process_dropjump_video(
     if not Path(video_path).exists():
         raise FileNotFoundError(f"Video file not found: {video_path}")
 
+    # Set deterministic mode for drop jump reproducibility
+    # Note: MediaPipe has inherent non-determinism (Google issue #3945)
+    # This improves consistency but cannot eliminate all variation
+    from .core.determinism import set_deterministic_mode
+
+    set_deterministic_mode(seed=42)
+
     # Start timing
     start_time = time.time()
 

kinemotion/core/determinism.py

@@ -0,0 +1,85 @@
+"""Determinism utilities for reproducible analysis.
+
+Provides functions to set random seeds for NumPy, Python's random module,
+and TensorFlow (used by MediaPipe) to ensure deterministic behavior.
+"""
+
+import hashlib
+import os
+import random
+from pathlib import Path
+
+import numpy as np
+
+
+def get_video_hash_seed(video_path: str) -> int:
+    """Generate deterministic seed from video file path.
+
+    Uses video filename (not contents) to generate a consistent seed
+    for the same video across multiple runs.
+
+    Args:
+        video_path: Path to video file
+
+    Returns:
+        Integer seed value derived from filename
+    """
+    # Use filename only (not full path) for consistency
+    filename = Path(video_path).name
+    # Hash filename to get deterministic seed
+    hash_value = hashlib.md5(filename.encode()).hexdigest()
+    # Convert first 8 hex chars to integer
+    return int(hash_value[:8], 16)
+
+
+def set_deterministic_mode(
+    seed: int | None = None, video_path: str | None = None
+) -> None:
+    """Set random seeds for reproducible analysis.
+
+    Sets seeds for:
+    - Python's random module
+    - NumPy random number generator
+    - TensorFlow (via environment variable for TFLite)
+
+    Args:
+        seed: Random seed value. If None and video_path provided,
+              generates seed from video filename.
+        video_path: Optional video path to generate deterministic seed
+
+    Note:
+        This should be called before any MediaPipe or analysis operations
+        to ensure deterministic pose detection and metric calculation.
+    """
+    # Generate seed from video if not provided
+    if seed is None and video_path is not None:
+        seed = get_video_hash_seed(video_path)
+    elif seed is None:
+        seed = 42  # Default
+
+    # Python random
+    random.seed(seed)
+
+    # NumPy random
+    np.random.seed(seed)
+
+    # TensorFlow/TFLite (used by MediaPipe)
+    # Set via environment variable before TF is initialized
+    os.environ["PYTHONHASHSEED"] = str(seed)
+    os.environ["TF_DETERMINISTIC_OPS"] = "1"
+
+    # Try to set TensorFlow seed if available
+    try:
+        import tensorflow as tf
+
+        tf.random.set_seed(seed)
+
+        # Disable GPU non-determinism if CUDA is available
+        try:
+            tf.config.experimental.enable_op_determinism()
+        except AttributeError:
+            # Older TensorFlow versions don't have this
+            pass
+    except ImportError:
+        # TensorFlow not directly available (only via MediaPipe's bundled version)
+        pass

kinemotion/core/pose.py

@@ -22,6 +22,7 @@ class PoseTracker:
         """
         self.mp_pose = mp.solutions.pose
         self.pose = self.mp_pose.Pose(
+            static_image_mode=False,  # Use tracking mode for better performance
             min_detection_confidence=min_detection_confidence,
             min_tracking_confidence=min_tracking_confidence,
             model_complexity=1,

kinemotion/dropjump/kinematics.py

@@ -202,6 +202,36 @@ def _filter_phases_after_drop(
     return filtered_phases, filtered_interpolated
 
 
+def _compute_robust_phase_position(
+    foot_y_positions: NDArray[np.float64],
+    phase_start: int,
+    phase_end: int,
+    temporal_window: int = 11,
+) -> float:
+    """Compute robust position estimate using temporal averaging.
+
+    Uses median over a fixed temporal window to reduce sensitivity to
+    MediaPipe landmark noise, improving reproducibility.
+
+    Args:
+        foot_y_positions: Vertical position array
+        phase_start: Start frame of phase
+        phase_end: End frame of phase
+        temporal_window: Number of frames to average (default: 11)
+
+    Returns:
+        Robust position estimate using median
+    """
+    # Center the temporal window on the phase midpoint
+    phase_mid = (phase_start + phase_end) // 2
+    window_start = max(0, phase_mid - temporal_window // 2)
+    window_end = min(len(foot_y_positions), phase_mid + temporal_window // 2 + 1)
+
+    # Use median for robustness to outliers
+    window_positions = foot_y_positions[window_start:window_end]
+    return float(np.median(window_positions))
+
+
 def _identify_main_contact_phase(
     phases: list[tuple[int, int, ContactState]],
     ground_phases: list[tuple[int, int, int]],
@@ -237,17 +267,20 @@ def _identify_main_contact_phase(
 
         if ground_after_air and first_ground_idx < first_air_idx:
             # Check if first ground is at higher elevation (lower y) than
-            # ground after air
-            first_ground_y = float(
-                np.mean(foot_y_positions[first_ground_start : first_ground_end + 1])
+            # ground after air using robust temporal averaging
+            first_ground_y = _compute_robust_phase_position(
+                foot_y_positions, first_ground_start, first_ground_end
             )
             second_ground_start, second_ground_end, _ = ground_after_air[0]
-            second_ground_y = float(
-                np.mean(foot_y_positions[second_ground_start : second_ground_end + 1])
+            second_ground_y = _compute_robust_phase_position(
+                foot_y_positions, second_ground_start, second_ground_end
             )
 
-            # If first ground is significantly higher (>5% of frame), it's a drop jump
-            if second_ground_y - first_ground_y > 0.05:
+            # If first ground is significantly higher (>7% of frame), it's a drop jump
+            # Increased from 0.05 to 0.07 with 11-frame temporal averaging
+            # for reproducibility (balances detection sensitivity with noise robustness)
+            # Note: MediaPipe has inherent non-determinism (Google issue #3945)
+            if second_ground_y - first_ground_y > 0.07:
                 is_drop_jump = True
                 contact_start, contact_end = second_ground_start, second_ground_end
 

{kinemotion-0.36.0.dist-info → kinemotion-0.36.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.36.0
+Version: 0.36.1
 Summary: Video-based kinematic analysis for athletic performance
 Project-URL: Homepage, https://github.com/feniix/kinemotion
 Project-URL: Repository, https://github.com/feniix/kinemotion

{kinemotion-0.36.0.dist-info → kinemotion-0.36.1.dist-info}/RECORD

@@ -1,5 +1,5 @@
 kinemotion/__init__.py,sha256=sxdDOekOrIgjxm842gy-6zfq7OWmGl9ShJtXCm4JI7c,723
-kinemotion/api.py,sha256=nbDbyzhXIMA04tGqKPH8R0fR66zgtu14x6NgWroy_QU,39471
+kinemotion/api.py,sha256=HdbdPxc6MTJO6lldYgfKGaF7SZuroKcWITS7rjhL8PA,39764
 kinemotion/cli.py,sha256=cqYV_7URH0JUDy1VQ_EDLv63FmNO4Ns20m6s1XAjiP4,464
 kinemotion/cmj/__init__.py,sha256=Ynv0-Oco4I3Y1Ubj25m3h9h2XFqeNwpAewXmAYOmwfU,127
 kinemotion/cmj/analysis.py,sha256=OfNTMLPwZIRYbX-Yd8jgZ-7pqnHRz7L2bWAHVYFsQ60,18955
@@ -13,11 +13,12 @@ kinemotion/core/__init__.py,sha256=HsqolRa60cW3vrG8F9Lvr9WvWcs5hCmsTzSgo7imi-4,1
 kinemotion/core/auto_tuning.py,sha256=wtCUMOhBChVJNXfEeku3GCMW4qED6MF-O_mv2sPTiVQ,11324
 kinemotion/core/cli_utils.py,sha256=zbnifPhD-OYofJioeYfJtshuWcl8OAEWtqCGVF4ctAI,7966
 kinemotion/core/debug_overlay_utils.py,sha256=TyUb5okv5qw8oeaX3jsUO_kpwf1NnaHEAOTm-8LwTno,4587
+kinemotion/core/determinism.py,sha256=NwVrHqJiVxxFHTBPVy8aDBJH2SLIcYIpdGFp7glblB8,2515
 kinemotion/core/experimental.py,sha256=IK05AF4aZS15ke85hF3TWCqRIXU1AlD_XKzFz735Ua8,3640
 kinemotion/core/filtering.py,sha256=GsC9BB71V07LJJHgS2lsaxUAtJsupcUiwtZFDgODh8c,11417
 kinemotion/core/formatting.py,sha256=G_3eqgOtym9RFOZVEwCxye4A2cyrmgvtQ214vIshowU,2480
 kinemotion/core/metadata.py,sha256=iz9YdkesHo-85TVBCoQVn7zkbrSde_fqjU79s_b-TZk,6829
-kinemotion/core/pose.py,sha256=ztemdZ_ysVVK3gbXabm8qS_dr1VfJX9KZjmcO-Z-iNE,8532
+kinemotion/core/pose.py,sha256=MQa7ebbuvk_vxJzVlwARKvEaJOqSFJMRRap2dz0O__0,8613
 kinemotion/core/quality.py,sha256=dPGQp08y8DdEUbUdjTThnUOUsALgF0D2sdz50cm6wLI,13098
 kinemotion/core/smoothing.py,sha256=GAfC-jxu1eqNyDjsUXqUBicKx9um5hrk49wz1FxfRNM,15219
 kinemotion/core/validation.py,sha256=LmKfSl4Ayw3DgwKD9IrhsPdzp5ia4drLsHA2UuU1SCM,6310
@@ -26,12 +27,12 @@ kinemotion/dropjump/__init__.py,sha256=tC3H3BrCg8Oj-db-Vrtx4PH_llR1Ppkd5jwaOjhQc
 kinemotion/dropjump/analysis.py,sha256=B_N_51WoChyQ8I7yaeKeqj3vw7NufgV_3QL-FBZEtW4,28752
 kinemotion/dropjump/cli.py,sha256=n_Wfv3AC6YIgRPYhO3F2nTSai0NR7fh95nAoWjryQeY,16250
 kinemotion/dropjump/debug_overlay.py,sha256=LkPw6ucb7beoYWS4L-Lvjs1KLCm5wAWDAfiznUeV2IQ,5668
-kinemotion/dropjump/kinematics.py,sha256=yB4ws4VG59SUGcw1J-uXfDFfCMXBdzRh5C4jo0osXbs,17404
+kinemotion/dropjump/kinematics.py,sha256=GhCyXPjVcs7uNt7N9NbTlWzzmoOoMQ0EUdW4j2pomcw,18738
 kinemotion/dropjump/metrics_validator.py,sha256=sx4RodHpeiW8_PRB0GUJvkUWto1Ard1Dvrc9z8eKk7M,9351
 kinemotion/dropjump/validation_bounds.py,sha256=5b4I3CKPybuvrbn-nP5yCcGF_sH4Vtyw3a5AWWvWnBk,4645
 kinemotion/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kinemotion-0.36.0.dist-info/METADATA,sha256=oDRVIjwO8LiGTAOuFxGM5AVQAejcl5liHy3WM95eq3c,26020
-kinemotion-0.36.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-kinemotion-0.36.0.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
-kinemotion-0.36.0.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
-kinemotion-0.36.0.dist-info/RECORD,,
+kinemotion-0.36.1.dist-info/METADATA,sha256=uw4lnmICS3YUOtG7f_GXPuQFcpIx0F2H8kM-zBKO3eQ,26020
+kinemotion-0.36.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+kinemotion-0.36.1.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
+kinemotion-0.36.1.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
+kinemotion-0.36.1.dist-info/RECORD,,