kinemotion 0.64.0__tar.gz → 0.65.0__tar.gz

kinemotion-0.65.0/.basic-memory/development/athlete-pose3-d-validation-status-and-pending-work.md

@@ -0,0 +1,30 @@
+---
+title: AthletePose3D Validation Status and Pending Work
+type: note
+permalink: development/athlete-pose3-d-validation-status-and-pending-work
+---
+
+# AthletePose3D Validation Status - Dec 18, 2025
+
+## 🏁 Overview
+The validation scripts for AthletePose3D (AP3D) have been remade after being lost from the workspace. They are currently in a "Phase 1: Infrastructure Ready" state.
+
+## 🔗 Verified Resources
+- **Repository:** https://github.com/calvinyeungck/AthletePose3D
+- **License:** https://github.com/calvinyeungck/athletepose3d/blob/main/license/README.md
+- **Download Link:** [Google Drive](https://drive.google.com/drive/folders/10YnMJAluiscnLkrdiluIeehNetdry5Ft?usp=sharing) (Verified Dec 18, 2025)
+
+## 📊 Code Evaluation
+- **Structural Integrity:** High. Scripts follow modular `prepare -> validate -> report` flow.
+- **Scientific Validity:** Medium. Current implementation lack **Coordinate Normalization** (World mm vs Image px).
+- **Temporal Alignment:** High. Uses linear interpolation to align research sequences (60/120fps) with video processing.
+
+## 🚀 Critical Pending Tasks
+1. **Coordinate Normalization:** Implement scaling (e.g., torso-length based) and Procrustes alignment.
+2. **3D Angles:** Implement 3D kinematic angle calculations (currently placeholders).
+3. **Data Verification:** Test `.pkl` loader against actual AP3D files once downloaded.
+
+## 📝 Roadmap Integration
+- **Status:** Non-blocking for MVP.
+- **Priority:** High for scientific credibility (post-Week 3).
+- **Goal:** Prove MediaPipe's "accurate" preset achieves <100mm MPJPE on athletic movements.

{kinemotion-0.64.0 → kinemotion-0.65.0}/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## kinemotion-v0.65.0 (2025-12-18)
+
+### Feat
+
+- **ap3d**: add AthletePose3D validation scripts and setup guide
+
 ## kinemotion-v0.64.0 (2025-12-15)
 
 ### Feat

{kinemotion-0.64.0 → kinemotion-0.65.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.64.0
+Version: 0.65.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.64.0 → kinemotion-0.65.0}/pyproject.toml

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

kinemotion-0.65.0/scripts/ap3d/PENDING.md

@@ -0,0 +1,43 @@
+# AthletePose3D Scripts - Pending Tasks & Status
+
+These scripts were remade on Dec 18, 2025, after being lost from the workspace. While structurally complete, they require scientific refinement once the dataset is downloaded.
+
+## 🎯 Current Status: **Phase 1 (Infrastructure Ready)**
+
+The scripts can scan directories, generate manifests, and perform basic MPJPE calculations. However, they are currently in **Image Space (Pixels)**, not **World Space (MM)**.
+
+## 🚀 Pending Work (High Priority)
+
+### 1. Coordinate Normalization
+
+- [ ] **Problem:** MediaPipe is normalized \[0,1\], AP3D Ground Truth is likely in mm or centralized camera coordinates.
+- [ ] **Task:** Implement a scaling/normalization factor (e.g., using torso length) to make MPJPE meaningful.
+- [ ] **Task:** Add Procrustes Alignment (Kabsch Algorithm) to handle translation/rotation offsets between models.
+
+### 2. 3D Kinematics
+
+- [ ] **Task:** Implement 3D joint angle calculations for Hip, Knee, and Ankle.
+- [ ] **Task:** Compare Kinemotion's 2D-derived angles vs AP3D's 3D ground truth angles.
+
+### 3. Data Integration
+
+- [ ] **Task:** Verify `.pkl` / `.npy` loading logic against actual AP3D files (once downloaded).
+- [ ] **Task:** Handle multi-view data (if present) - current scripts assume single view per video.
+- [ ] **Task:** Add regex-based mapping for complex filenames (e.g., `S01_Run_V1.mp4` -> `S01_Run.pkl`).
+
+### 4. Robustness & Presets
+
+- [ ] **Task:** Use results to validate the "athletic" preset (smoothing/filtering optimization).
+- [ ] **Task:** Handle detection failures (frames where MediaPipe returns no landmarks).
+
+## 📊 Evaluation Summary (Code Reasoning)
+
+| Script                 | Purpose           | Confidence | Primary Risk                   |
+| ---------------------- | ----------------- | ---------- | ------------------------------ |
+| `prepare_ap3d_data.py` | Data indexing     | High       | Naive filename mapping         |
+| `ap3d_validator.py`    | Error calculation | Medium     | Lacks 3D coordinate projection |
+| `validate_baseline.py` | Execution         | High       | None                           |
+
+______________________________________________________________________
+
+**Note:** Do not use MPJPE values from the current version for scientific reports until **Coordinate Normalization** is implemented.

kinemotion-0.65.0/scripts/ap3d/ap3d_validator.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""
+AP3DValidator: Core validation logic for AthletePose3D dataset.
+Calculates MPJPE, joint angle errors, and temporal consistency.
+"""
+
+import json
+import logging
+import pickle
+from typing import Any
+from pathlib import Path
+
+import numpy as np
+import scipy.interpolate as interpolate
+from numpy.typing import NDArray
+from kinemotion.core.pose import PoseTracker
+from kinemotion.core.video_io import VideoProcessor
+
+# Configure logging
+logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
+logger = logging.getLogger(__name__)
+
+class AP3DValidator:
+    """Validator for AthletePose3D dataset."""
+
+    def __init__(self, ap3d_root: Path):
+        self.ap3d_root = ap3d_root
+        self.manifest_path = ap3d_root / "manifest.json"
+        self.manifest = self._load_manifest()
+        self.mapping = self.manifest.get("mapping", {})
+        # Inverse mapping for easy lookup: MediaPipe index -> COCO index
+        self.inv_mapping = {int(v): int(k) for k, v in self.mapping.items()}
+
+    def _load_manifest(self) -> dict[str, Any]:
+        if not self.manifest_path.exists():
+            raise FileNotFoundError(f"Manifest not found: {self.manifest_path}")
+        with open(self.manifest_path) as f:
+            return json.load(f)
+
+    def load_ground_truth(self, gt_path: str) -> Any:
+        """Load ground truth from .pkl or .npy file."""
+        full_path = self.ap3d_root / gt_path
+        if full_path.suffix == ".pkl":
+            with open(full_path, "rb") as f:
+                data = pickle.load(f)
+                # Assume data is a numpy array of shape (frames, 17, 3)
+                # Some PKL might be dicts, adjust if needed
+                if isinstance(data, dict) and "keypoints_3d" in data:
+                    return data["keypoints_3d"]
+                return data
+        elif full_path.suffix == ".npy":
+            return np.load(full_path)
+        else:
+            raise ValueError(f"Unsupported ground truth format: {full_path.suffix}")
+
+    def temporal_alignment(self, source_data: NDArray[np.float64], target_len: int) -> NDArray[np.float64]:
+        """Align source_data to target_len using linear interpolation."""
+        source_len = len(source_data)
+        if source_len == target_len:
+            return source_data
+
+        x_source = np.linspace(0, 1, source_len)
+        x_target = np.linspace(0, 1, target_len)
+
+        # Reshape to (len, -1) for easier interpolation
+        orig_shape = source_data.shape
+        flat_source = source_data.reshape(source_len, -1)
+
+        f = interpolate.interp1d(x_source, flat_source, axis=0, kind="linear", fill_value="extrapolate")
+        flat_target: NDArray[np.float64] = f(x_target).astype(np.float64)
+
+        return flat_target.reshape((target_len,) + orig_shape[1:])
+
+    def calculate_mpjpe(self, gt_poses: NDArray[np.float64], mp_poses: NDArray[np.float64]) -> float:
+        """
+        Calculate Mean Per Joint Position Error.
+        Assumes both are (frames, joints, 3) and aligned.
+        """
+        # Calculate Euclidean distance per joint per frame
+        errors = np.linalg.norm(gt_poses - mp_poses, axis=2)
+        return float(np.mean(errors))
+
+    def validate_single(self, entry: dict[str, Any]) -> dict[str, Any]:
+        """Validate a single video entry from the manifest."""
+        video_path = entry["video_path"]
+        gt_path = entry["gt_path"]
+
+        logger.info(f"Validating {video_path}...")
+
+        # Load Ground Truth: (frames, joints, 3)
+        gt_data = self.load_ground_truth(gt_path)
+
+        # Initialize PoseTracker
+        tracker = PoseTracker()
+        mp_poses = []
+
+        full_video_path = self.ap3d_root / video_path
+        with VideoProcessor(str(full_video_path)) as video:
+            width, height = video.width, video.height
+            for frame in video:
+                landmarks = tracker.process_frame(frame)
+
+                # Create pose array for this frame (17 joints, 3 coords: x, y, z)
+                # MediaPipe PoseTracker returns (x, y, visibility) in normalized coords
+                # For MPJPE we need to convert to pixels or mm.
+                # Let's start with pixel-level validation (MPJPE-px)
+                frame_pose = np.zeros((17, 3))
+
+                if landmarks:
+                    # Mapping from PoseTracker names to COCO indices
+                    name_to_coco = {
+                        "nose": 0,
+                        "left_shoulder": 5, "right_shoulder": 6,
+                        "left_hip": 11, "right_hip": 12,
+                        "left_knee": 13, "right_knee": 14,
+                        "left_ankle": 15, "right_ankle": 16
+                    }
+
+                    for name, coco_idx in name_to_coco.items():
+                        if name in landmarks:
+                            x, y, _ = landmarks[name]
+                            # Scale normalized to pixels
+                            frame_pose[coco_idx] = [x * width, y * height, 0] # Z is 0 for now
+
+                mp_poses.append(frame_pose)
+
+        tracker.close()
+        mp_poses_arr = np.array(mp_poses)
+
+        # Temporal alignment
+        # Align GT to MP frame count
+        gt_aligned = self.temporal_alignment(gt_data, len(mp_poses_arr))
+
+        # Calculate MPJPE for visible joints (joints 0, 5, 6, 11, 12, 13, 14, 15, 16)
+        visible_joints = [0, 5, 6, 11, 12, 13, 14, 15, 16]
+
+        # Slice both to only include visible joints
+        gt_visible = gt_aligned[:, visible_joints, :2] # only X, Y
+        mp_visible = mp_poses_arr[:, visible_joints, :2]
+
+        mpjpe = self.calculate_mpjpe(gt_visible, mp_visible)
+
+        return {"mpjpe": float(mpjpe), "video": video_path}
+
+    def validate_split(self, split_name: str) -> dict[str, Any]:
+        """Validate all videos in a specific split."""
+        entries = self.manifest["splits"].get(split_name, [])
+        results = []
+        for entry in entries:
+            res = self.validate_single(entry)
+            results.append(res)
+
+        return self.aggregate_results(results)
+
+    def aggregate_results(self, results: list[dict[str, Any]]) -> dict[str, Any]:
+        """Aggregate results and calculate summary statistics."""
+        if not results:
+            return {}
+        mpjpes = [r["mpjpe"] for r in results]
+        return {
+            "mean_mpjpe": float(np.mean(mpjpes)),
+            "std_mpjpe": float(np.std(mpjpes)),
+            "count": len(results)
+        }
+
+    def generate_report(self, summary: dict[str, Any], output_path: Path) -> None:
+        """Generate a markdown report."""
+        report = f"""# AP3D Validation Report
+
+## Summary Statistics
+- **Total Videos:** {summary.get('count')}
+- **Mean MPJPE:** {summary.get('mean_mpjpe'):.2f} mm
+- **Std MPJPE:** {summary.get('std_mpjpe'):.2f} mm
+
+## Recommendations
+{"Acceptable baseline accuracy." if summary.get('mean_mpjpe', 999) < 100 else "Needs optimization."}
+"""
+        with open(output_path, "w") as f:
+            f.write(report)
+        logger.info(f"Report generated at {output_path}")
+
+if __name__ == "__main__":
+    # Example usage
+    validator = AP3DValidator(Path("data/athletepose3d"))
+    # summary = validator.validate_split("test")
+    # validator.generate_report(summary, Path("reports/ap3d_baseline_validation.md"))

kinemotion-0.65.0/scripts/ap3d/prepare_ap3d_data.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""
+Prepare AthletePose3D dataset for validation.
+Scans directories, extracts metadata, and creates a manifest.json.
+"""
+
+import json
+import logging
+import random
+from pathlib import Path
+from typing import Any
+
+import click
+import cv2
+
+# Configure logging
+logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
+logger = logging.getLogger(__name__)
+
+# COCO 17 keypoints to MediaPipe 33 landmarks mapping
+# COCO: [nose, l_eye, r_eye, l_ear, r_ear, l_shoulder, r_shoulder, l_elbow, r_elbow, l_wrist, r_wrist, l_hip, r_hip, l_knee, r_knee, l_ankle, r_ankle]
+COCO_TO_MEDIAPIPE = {
+    0: 0,   # nose
+    1: 2,   # l_eye
+    2: 5,   # r_eye
+    3: 7,   # l_ear
+    4: 8,   # r_ear
+    5: 11,  # l_shoulder
+    6: 12,  # r_shoulder
+    7: 13,  # l_elbow
+    8: 14,  # r_elbow
+    9: 15,  # l_wrist
+    10: 16, # r_wrist
+    11: 23, # l_hip
+    12: 24, # r_hip
+    13: 25, # l_knee
+    14: 26, # r_knee
+    15: 27, # l_ankle
+    16: 28, # r_ankle
+}
+
+def get_video_metadata(video_path: Path) -> dict[str, Any]:
+    """Extract metadata from video file."""
+    cap = cv2.VideoCapture(str(video_path))
+    if not cap.isOpened():
+        return {}
+
+    fps = cap.get(cv2.CAP_PROP_FPS)
+    frame_count = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+    width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+    height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+    cap.release()
+
+    return {
+        "fps": fps,
+        "frame_count": frame_count,
+        "width": width,
+        "height": height,
+        "duration": frame_count / fps if fps > 0 else 0
+    }
+
+@click.command()
+@click.option("--ap3d-root", type=click.Path(exists=True, path_type=Path), default="data/athletepose3d", help="Root directory of AP3D dataset")
+@click.option("--train-split", type=float, default=0.7, help="Ratio of training data")
+@click.option("--val-split", type=float, default=0.15, help="Ratio of validation data")
+@click.option("--seed", type=int, default=42, help="Random seed for splitting")
+def main(ap3d_root: Path, train_split: float, val_split: float, seed: int) -> None:
+    """Scan AP3D dataset and generate manifest.json."""
+    video_dir = ap3d_root / "videos"
+    gt_dir = ap3d_root / "ground_truth"
+
+    if not video_dir.exists():
+        logger.error(f"Video directory not found: {video_dir}")
+        return
+
+    logger.info(f"Scanning videos in {video_dir}...")
+    video_files = list(video_dir.glob("*.mp4")) + list(video_dir.glob("*.mov"))
+    logger.info(f"Found {len(video_files)} videos.")
+
+    manifest_entries = []
+
+    for video_path in video_files:
+        # Match with ground truth
+        # AP3D often has matching names, e.g., video1.mp4 -> video1.pkl or video1.npy
+        gt_path_pkl = gt_dir / f"{video_path.stem}.pkl"
+        gt_path_npy = gt_dir / f"{video_path.stem}.npy"
+
+        gt_path = None
+        if gt_path_pkl.exists():
+            gt_path = gt_path_pkl
+        elif gt_path_npy.exists():
+            gt_path = gt_path_npy
+
+        if not gt_path:
+            logger.warning(f"No ground truth found for {video_path.name}, skipping.")
+            continue
+
+        metadata = get_video_metadata(video_path)
+        if not metadata:
+            logger.warning(f"Could not read metadata for {video_path.name}, skipping.")
+            continue
+
+        entry = {
+            "video_path": str(video_path.relative_to(ap3d_root)),
+            "gt_path": str(gt_path.relative_to(ap3d_root)),
+            "metadata": metadata,
+            "movement_type": video_path.stem.split("-")[0] if "-" in video_path.stem else "unknown"
+        }
+        manifest_entries.append(entry)
+
+    if not manifest_entries:
+        logger.error("No valid video/ground-truth pairs found.")
+        return
+
+    # Shuffle and split
+    random.seed(seed)
+    random.shuffle(manifest_entries)
+
+    num_total = len(manifest_entries)
+    num_train = int(num_total * train_split)
+    num_val = int(num_total * val_split)
+
+    train_entries = manifest_entries[:num_train]
+    val_entries = manifest_entries[num_train:num_train+num_val]
+    test_entries = manifest_entries[num_train+num_val:]
+
+    manifest = {
+        "dataset": "AthletePose3D",
+        "mapping": COCO_TO_MEDIAPIPE,
+        "splits": {
+            "train": train_entries,
+            "validation": val_entries,
+            "test": test_entries
+        },
+        "summary": {
+            "total": num_total,
+            "train": len(train_entries),
+            "validation": len(val_entries),
+            "test": len(test_entries)
+        }
+    }
+
+    manifest_path = ap3d_root / "manifest.json"
+    with open(manifest_path, "w") as f:
+        json.dump(manifest, f, indent=2)
+
+    logger.info(f"Manifest generated at {manifest_path}")
+    logger.info(f"Total: {num_total} (Train: {len(train_entries)}, Val: {len(val_entries)}, Test: {len(test_entries)})")
+
+if __name__ == "__main__":
+    main()

kinemotion-0.65.0/scripts/ap3d/validate_baseline.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+"""
+Baseline validation script for AthletePose3D.
+Runs validation on the test split and generates a report.
+"""
+
+import logging
+from pathlib import Path
+
+import click
+from scripts.ap3d.ap3d_validator import AP3DValidator
+
+# Configure logging
+logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
+logger = logging.getLogger(__name__)
+
+@click.command()
+@click.option("--ap3d-root", type=click.Path(exists=True, path_type=Path), default="data/athletepose3d", help="Root directory of AP3D dataset")
+@click.option("--split", type=str, default="test", help="Split to validate (train, validation, test)")
+@click.option("--output-report", type=click.Path(path_type=Path), default="reports/ap3d_baseline_validation.md", help="Path to save validation report")
+def main(ap3d_root: Path, split: str, output_report: Path) -> None:
+    """Run baseline validation on AP3D dataset."""
+    logger.info(f"Starting AP3D validation on '{split}' split...")
+
+    try:
+        validator = AP3DValidator(ap3d_root)
+        summary = validator.validate_split(split)
+
+        if not summary:
+            logger.error(f"No results found for split '{split}'.")
+            return
+
+        # Ensure reports directory exists
+        output_report.parent.mkdir(parents=True, exist_ok=True)
+
+        validator.generate_report(summary, output_report)
+
+        logger.info("Validation complete!")
+        logger.info(f"Mean MPJPE: {summary.get('mean_mpjpe'):.2f} px")
+        logger.info(f"Report saved to: {output_report}")
+
+    except Exception as e:
+        logger.error(f"Validation failed: {e}")
+        import traceback
+        logger.error(traceback.format_exc())
+
+if __name__ == "__main__":
+    main()

{kinemotion-0.64.0 → kinemotion-0.65.0}/src/kinemotion/core/video_io.py

@@ -203,6 +203,17 @@ class VideoProcessor:
         """Release video capture."""
         self.cap.release()
 
+    def __iter__(self) -> "VideoProcessor":
+        """Make the processor iterable."""
+        return self
+
+    def __next__(self) -> np.ndarray:
+        """Get the next frame during iteration."""
+        frame = self.read_frame()
+        if frame is None:
+            raise StopIteration
+        return frame
+
     def __enter__(self) -> "VideoProcessor":
         return self
 

{kinemotion-0.64.0 → kinemotion-0.65.0}/uv.lock

@@ -913,7 +913,7 @@ wheels = [
 
 [[package]]
 name = "kinemotion"
-version = "0.63.0"
+version = "0.64.0"
 source = { editable = "." }
 dependencies = [
     { name = "click" },