kinemotion 0.36.0__tar.gz → 0.37.0__tar.gz

{kinemotion-0.36.0 → kinemotion-0.37.0}/.claude/settings.local.json

@@ -5,6 +5,7 @@
       "Bash(cat:*)",
       "Bash(chmod:*)",
       "Bash(curl:*)",
+      "Bash(ffmpeg:*)",
       "Bash(ffprobe:*)",
       "Bash(find:*)",
       "Bash(gh run view:*)",
@@ -37,6 +38,7 @@
       "mcp__ref__ref_read_url",
       "mcp__ref__ref_search_documentation",
       "mcp__sequential__sequentialthinking",
+      "mcp__sequential-thinking__generate_summary",
       "mcp__sequential-thinking__process_thought",
       "mcp__sequential-thinking__sequentialthinking",
       "mcp__serena__check_onboarding_performed",
@@ -63,8 +65,7 @@
       "WebFetch(domain:realpython.com)",
       "WebFetch(domain:sonarcloud.io)",
       "WebFetch(domain:www.pyopensci.org)",
-      "WebFetch(domain:www.sonarsource.com)",
-      "Bash(ffmpeg:*)"
+      "WebFetch(domain:www.sonarsource.com)"
     ]
   },
   "enableAllProjectMcpServers": true,

{kinemotion-0.36.0 → kinemotion-0.37.0}/.github/workflows/deploy-backend.yml

@@ -130,7 +130,7 @@ jobs:
           region: ${{ env.GCP_REGION }}
           image: ${{ env.REGISTRY }}/${{ env.GCP_PROJECT_ID }}/${{ env.SERVICE_NAME }}:${{ github.sha }}
           flags: |
-            --memory=2Gi
+            --memory=4Gi
             --allow-unauthenticated
             --service-account=kinemotion-backend-runtime@${{ env.GCP_PROJECT_ID }}.iam.gserviceaccount.com
             --set-env-vars=CORS_ORIGINS=https://kinemotion.vercel.app,JSON_LOGS=true,LOG_LEVEL=INFO

{kinemotion-0.36.0 → kinemotion-0.37.0}/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## v0.37.0 (2025-12-09)
+
+### Chores
+
+- Organize permissions list and add sequential-thinking tool
+  ([`64aaf72`](https://github.com/feniix/kinemotion/commit/64aaf72b44fbb3561f84ec5e12f9ec14c2d0d05b))
+
+### Features
+
+- **backend**: Add determinism testing endpoints for M1 vs Intel comparison
+  ([`8447790`](https://github.com/feniix/kinemotion/commit/8447790f6aef2bd11fdfa086ce4e67b5226de9e2))
+
+
+## v0.36.1 (2025-12-08)
+
+### Bug Fixes
+
+- **dropjump**: Improve analysis reproducibility with temporal averaging
+  ([`6f98b1f`](https://github.com/feniix/kinemotion/commit/6f98b1f918539e714b604ac1a0bf6187c6ff28a6))
+
+### Chores
+
+- Up the mem of the backend
+  ([`67133ca`](https://github.com/feniix/kinemotion/commit/67133ca2cded45df74ef5bfe3e9d9b7d85bde1a9))
+
+
 ## v0.36.0 (2025-12-07)
 
 ### Bug Fixes

{kinemotion-0.36.0 → kinemotion-0.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.36.0
+Version: 0.37.0
 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 → kinemotion-0.37.0}/backend/src/kinemotion_backend/app.py

@@ -682,6 +682,87 @@ async def analyze_local_video(
 # ========== Error Handlers ==========
 
 
+@app.get("/determinism/platform-info", tags=["Determinism"])
+async def get_platform_info() -> dict[str, Any]:
+    """Get platform info for cross-platform determinism testing."""
+    import platform
+
+    import cv2
+    import numpy as np
+
+    return {
+        "platform": {
+            "machine": platform.machine(),
+            "processor": platform.processor(),
+            "python_version": platform.python_version(),
+        },
+        "libraries": {
+            "numpy": np.__version__,
+            "opencv": cv2.__version__,
+        },
+    }
+
+
+@app.post("/determinism/extract-landmarks", tags=["Determinism"])
+async def extract_landmarks_determinism(video: UploadFile = File(...)) -> JSONResponse:  # noqa: B008
+    """Extract raw MediaPipe landmarks for cross-platform comparison."""
+    import platform
+
+    from kinemotion.core.pose import PoseTracker
+    from kinemotion.core.video_io import VideoProcessor
+
+    with tempfile.NamedTemporaryFile(delete=False, suffix=".MOV") as tmp:
+        content = await video.read()
+        tmp.write(content)
+        tmp_path = tmp.name
+
+    try:
+        tracker = PoseTracker()
+        video_proc = VideoProcessor(tmp_path)
+
+        all_landmarks = []
+        frame_idx = 0
+
+        while True:
+            ret, frame = video_proc.cap.read()
+            if not ret:
+                break
+
+            landmarks = tracker.process_frame(frame)
+
+            if landmarks:
+                frame_landmarks = {
+                    "frame": frame_idx,
+                    "landmarks": {
+                        name: {
+                            "x": float(coords[0]),
+                            "y": float(coords[1]),
+                            "visibility": float(coords[2]),
+                        }
+                        for name, coords in landmarks.items()
+                    },
+                }
+            else:
+                frame_landmarks = {"frame": frame_idx, "landmarks": None}
+
+            all_landmarks.append(frame_landmarks)
+            frame_idx += 1
+
+        video_proc.close()
+
+        return JSONResponse(
+            content={
+                "video_filename": video.filename,
+                "platform": platform.machine(),
+                "num_frames": frame_idx,
+                "landmarks": all_landmarks,
+            }
+        )
+
+    finally:
+        os.unlink(tmp_path)
+
+
 @app.exception_handler(HTTPException)
 async def http_exception_handler(request: Any, exc: HTTPException) -> JSONResponse:
     """Handle HTTP exceptions with consistent response format."""

kinemotion-0.37.0/docs/strategy/pose2sim-migration-evaluation.md

@@ -0,0 +1,269 @@
+# Pose2Sim Migration Evaluation and Strategy
+
+**Date:** 2025-12-08
+**Analysis Method:** Sequential thinking + Multi-tool research (exa, ref, serena, basic-memory)
+**Decision:** DEFER to Phase 2+ (post-MVP)
+
+______________________________________________________________________
+
+## Executive Summary
+
+**Recommendation: DO NOT migrate to Pose2Sim during MVP phase (Weeks 1-3)**
+
+Pose2Sim would provide 67-73% accuracy improvement but requires:
+
+- 2-4 weeks integration time (delays MVP launch)
+- $2,000-5,000 hardware investment (premature before market validation)
+- Multi-camera setup (adds complexity for users)
+- Batch processing only (may conflict with real-time needs)
+
+**Strategic timing is wrong.** Focus on MVP launch, gather user feedback, then reassess based on validated market needs.
+
+______________________________________________________________________
+
+## Current State Analysis
+
+### MediaPipe Monocular (Kinemotion Current)
+
+- **Joint angle error:** ~10-15°
+- **Position RMSE:** 56mm
+- **Ankle/knee visibility:** 18-27% (lateral view, occlusion issues)
+- **Cost:** $0 (single camera/smartphone)
+- **Setup time:** Minutes
+- **Processing:** Real-time capable
+- **Architecture:** PoseTracker class wraps MediaPipe, processes frames sequentially
+
+### Recent Optimizations (Dec 2025)
+
+- 92% improvement in detection accuracy (within 5 frames target)
+- Fixed non-deterministic analysis (temporal averaging)
+- 45° oblique angle validated as optimal for MediaPipe
+
+______________________________________________________________________
+
+## Pose2Sim Technical Analysis
+
+### Accuracy Improvements
+
+| Metric                | Current (MediaPipe) | Pose2Sim  | Improvement    |
+| --------------------- | ------------------- | --------- | -------------- |
+| Joint angle error     | ~10-15°             | 3-4°      | **67-73%** ↓   |
+| Position RMSE         | 56mm                | 30-40mm   | **29-46%** ↓   |
+| Ankle/knee visibility | 18-27%              | 80-95%    | **3-5x** ↑     |
+| CMC correlation       | Not available       | 0.90-0.98 | Research-grade |
+
+### Technical Requirements
+
+- **Hardware:** 4-8 RGB cameras (1080p+, 60-240 Hz)
+- **Sync:** Hardware preferred, software acceptable
+- **Calibration:** ChArUco board, intrinsic + extrinsic
+- **Compute:** GPU recommended but NOT required (CPU works, 2-3x slower)
+- **Software:** Python, OpenSim, pose2sim package
+
+### Integration Architecture
+
+**Pose2Sim Pipeline:**
+
+```python
+from Pose2Sim import Pose2Sim
+
+Pose2Sim.calibration()      # Camera calibration
+Pose2Sim.poseEstimation()   # 2D pose (uses OpenPose/MediaPipe/AlphaPose)
+Pose2Sim.triangulation()    # 3D reconstruction
+Pose2Sim.filtering()        # Butterworth smoothing (6 Hz)
+Pose2Sim.kinematics()       # OpenSim inverse kinematics
+```
+
+**Kinemotion Integration Points:**
+
+1. Replace `PoseTracker` class (src/kinemotion/core/pose.py)
+1. Modify `process_dropjump_video()` / `process_cmj_video()` (src/kinemotion/api.py)
+1. Keep existing: smoothing, signed velocity, backward search, analysis logic
+1. Add: multi-camera input handling, calibration management, OpenSim output parsing
+
+______________________________________________________________________
+
+## Cost-Benefit Analysis
+
+### Investment Required
+
+| Item                               | Cost             | Time          |
+| ---------------------------------- | ---------------- | ------------- |
+| 4-8 RGB cameras (1080p, 60-120 Hz) | $2,000-3,000     | 1 week        |
+| Optional GPU for faster 2D pose    | $1,000-2,000     | N/A           |
+| Integration development            | $0 (internal)    | 2-4 weeks     |
+| Testing & validation               | $0 (internal)    | 1 week        |
+| **Total**                          | **$2,000-5,000** | **3-5 weeks** |
+
+### Benefits
+
+- **Accuracy:** Research-grade (publishable validation studies)
+- **Credibility:** Gold-standard validation vs Vicon/Qualisys
+- **Market differentiation:** Can claim highest accuracy in market
+- **Biomechanical validity:** OpenSim constraints ensure physically plausible poses
+- **Multi-view:** Eliminates occlusion problems (45° + frontal + lateral)
+
+### Risks
+
+- **Complexity:** Multi-camera setup increases user friction
+- **Cost barrier:** $2-5k hardware may limit adoption
+- **No real-time:** Batch processing only (if real-time needed, Pose2Sim won't work)
+- **Integration delay:** 3-5 weeks delays MVP launch and market feedback
+- **Premature optimization:** Unknown if accuracy is validated user pain point
+
+______________________________________________________________________
+
+## Go/No-Go Decision Framework
+
+**Phase 1 (MVP - Weeks 1-3): GO = 0/5 ❌**
+
+| Criteria                                 | Status                 | Weight   |
+| ---------------------------------------- | ---------------------- | -------- |
+| Is MediaPipe accuracy blocking adoption? | ❌ NO (no users yet)   | Critical |
+| User feedback demanding better accuracy? | ❌ NO (pre-launch)     | Critical |
+| Research publication planned?            | ⚠️ TBD (not immediate) | High     |
+| Can afford 3-5 week delay?               | ❌ NO (Week 3 of MVP)  | Critical |
+| $2-5k justified by revenue?              | ❌ NO (pre-revenue)    | High     |
+
+**Recommendation: DEFER**
+
+**Phase 2+ (Post-MVP): Reassess when GO ≥ 3/5**
+
+Wait for:
+
+1. MVP launch (Week 3)
+1. User feedback (Weeks 4-8)
+1. Market validation (revenue/engagement)
+1. Feature prioritization from actual users
+
+______________________________________________________________________
+
+## Phased Migration Roadmap (IF NEEDED)
+
+### Immediate (Week 4 - Post-MVP Launch)
+
+**Action:** Test OpenCap as low-risk validation
+
+- Record sample videos with 2 smartphones
+- Upload to opencap.ai, download results
+- Compare accuracy vs MediaPipe on validation dataset
+- Assess if improvement justifies complexity
+- **Cost:** $0, **Time:** 2-3 days
+
+### Short-term (Weeks 5-8 - IF accuracy validated as pain point)
+
+**Action:** Implement hybrid architecture
+
+- Create `Pose2SimAdapter` class alongside `PoseTracker`
+- Add `--multi-camera` flag to CLI
+- Keep MediaPipe for single-camera (backward compatible)
+- Add Pose2Sim for research-grade offline analysis
+- Share analysis logic (smoothing, metrics calculation)
+- **Cost:** $2-3k (cameras), **Time:** 2-4 weeks
+
+### Long-term (Months 2-3 - IF market demands it)
+
+**Action:** Full Pose2Sim integration
+
+- Multi-camera calibration UI
+- Batch processing optimization
+- OpenSim biomechanical constraints
+- Validation study publication (if academic goals)
+- Market as "research-grade" premium tier
+- **Cost:** $2-5k, **Time:** 4-6 weeks
+
+______________________________________________________________________
+
+## Alternative: OpenCap Comparison
+
+### OpenCap Advantages vs Pose2Sim
+
+- **Cost:** $0 (use existing smartphones)
+- **Setup:** Minutes (no calibration needed)
+- **Processing:** Cloud-based (no local compute)
+- **Accuracy:** ~4-6° joint angle errors (vs 3-4° for Pose2Sim)
+- **Biomechanics:** Automatic OpenSim constraints
+
+### OpenCap Disadvantages
+
+- **Internet required:** Cloud processing dependency
+- **Less control:** Can't customize pipeline
+- **Validation:** Still emerging (fewer published studies than Pose2Sim)
+- **Output format:** May require parsing/conversion
+
+### Recommendation
+
+**Test OpenCap first** (Week 4) before committing to Pose2Sim hardware investment.
+
+______________________________________________________________________
+
+## Key Technical Insights
+
+### GPU Requirements
+
+- **OpenCap:** NO GPU needed (cloud processing)
+- **Pose2Sim:** GPU only speeds up 2D pose step (3-5x faster)
+  - With GPU: ~2-5 min per camera (1000 frames)
+  - With CPU: ~10-30 min per camera (1000 frames)
+- **Recommendation:** CPU-only Pose2Sim acceptable for research use
+
+### Current Architecture (Kinemotion)
+
+- **PoseTracker:** Wraps MediaPipe, processes frames sequentially
+- **API entry points:** `process_dropjump_video()`, `process_cmj_video()` (376-628 lines)
+- **Data flow:** Video → PoseTracker.process_frame() → landmarks → smoothing → analysis → metrics
+- **Integration points:** Replace PoseTracker or add parallel Pose2Sim path
+
+### Integration Complexity
+
+- **Low:** OpenCap (parse output, feed to existing analysis)
+- **Medium:** Hybrid Pose2Sim (new code path, keep MediaPipe)
+- **High:** Full Pose2Sim replacement (breaking change)
+
+______________________________________________________________________
+
+## Strategic Recommendation
+
+### Phase 1 (NOW): Ship MVP with MediaPipe
+
+**Focus:** Get product in coaches' hands, gather feedback
+
+- Current accuracy sufficient for initial validation
+- Real-time capability preserved (may be needed)
+- No hardware barriers for early adopters
+- Fast time-to-market
+
+### Phase 2 (Week 4+): Market-Driven Decision
+
+**If users say:** "Accuracy is not good enough" → Pose2Sim migration
+**If users say:** "Real-time feedback is critical" → Stay with MediaPipe
+**If users say:** "Both accuracy and real-time needed" → Hybrid architecture
+
+### Key Principle
+
+**Optimize for learning, not accuracy.** Ship fast, validate with real users, then invest based on validated needs rather than technical possibilities.
+
+______________________________________________________________________
+
+## References
+
+- **Pose2Sim validation:** Pagnon et al. (2022), Sensors 22(7), 2712
+- **Stereo MediaPipe:** Dill et al. (2024), Sensors 24(23), 7772
+- **AthletePose3D dataset:** Yeung et al. (2025), arXiv:2503.07499
+- **Kinemotion docs:** docs/reference/pose-systems.md, docs/research/sports-biomechanics-pose-estimation.md
+- **Current architecture:** src/kinemotion/core/pose.py, src/kinemotion/api.py
+
+______________________________________________________________________
+
+## Conclusion
+
+Pose2Sim migration is **technically feasible** (2-4 weeks, $2-5k) and would provide **67-73% accuracy improvement**, but **strategic timing is wrong**.
+
+**Action:** Focus on MVP launch (Phase 1), gather real market feedback, then decide based on validated user needs rather than technical possibilities.
+
+**Next steps:**
+
+1. Complete MVP launch (Week 3)
+1. Collect user feedback (Weeks 4-8)
+1. Test OpenCap if accuracy emerges as pain point (Week 4)
+1. Reassess Pose2Sim decision when GO score ≥ 3/5

{kinemotion-0.36.0 → kinemotion-0.37.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kinemotion"
-version = "0.36.0"
+version = "0.37.0"
 description = "Video-based kinematic analysis for athletic performance"
 readme = "README.md"
 requires-python = ">=3.10,<3.13"

{kinemotion-0.36.0 → kinemotion-0.37.0}/src/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-0.37.0/src/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-0.36.0 → kinemotion-0.37.0}/src/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-0.36.0 → kinemotion-0.37.0}/src/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 → kinemotion-0.37.0}/uv.lock

@@ -894,7 +894,7 @@ wheels = [
 
 [[package]]
 name = "kinemotion"
-version = "0.36.0"
+version = "0.37.0"
 source = { editable = "." }
 dependencies = [
     { name = "click" },