kinemotion 0.76.2__py3-none-any.whl → 1.0.0__py3-none-any.whl

kinemotion/core/experimental.py

@@ -1,6 +1,6 @@
-"""Decorator for marking unused features.
+"""Decorators for marking experimental and unused features.
 
-This decorator helps identify code that is implemented but not yet
+These decorators help identify code that is implemented but not yet
 integrated into the main pipeline, making it easier to track features
 for future enhancement or cleanup.
 """
@@ -13,14 +13,61 @@ from typing import TypeVar
 F = TypeVar("F", bound=Callable)
 
 
+def experimental(
+    reason: str, *, issue: int | None = None, since: str | None = None
+) -> Callable[[F], F]:
+    """Mark a feature as experimental/not fully integrated.
+
+    Experimental features are working implementations that haven't been
+    fully integrated into the main pipeline. They emit warnings when called
+    to alert developers they're using untested/unstable APIs.
+
+    Args:
+        reason: Why this is experimental (e.g., "API unstable", "needs validation")
+        issue: Optional GitHub issue number for tracking integration
+        since: Optional version when this became experimental
+
+    Example:
+        >>> @experimental("API may change", issue=123, since="0.34.0")
+        ... def new_feature():
+        ...     pass
+
+    Returns:
+        Decorated function that warns on use
+    """
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):  # type: ignore
+            msg = f"{func.__name__} is experimental: {reason}"
+            if issue:
+                msg += f" (GitHub issue #{issue})"
+            if since:
+                msg += f" [since v{since}]"
+            warnings.warn(msg, FutureWarning, stacklevel=2)
+            return func(*args, **kwargs)
+
+        # Add metadata for documentation/tooling
+        wrapper.__experimental__ = True  # type: ignore[attr-defined]
+        wrapper.__experimental_reason__ = reason  # type: ignore[attr-defined]
+        if issue:
+            wrapper.__experimental_issue__ = issue  # type: ignore[attr-defined]
+        if since:
+            wrapper.__experimental_since__ = since  # type: ignore[attr-defined]
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
 def unused(
     reason: str, *, remove_in: str | None = None, since: str | None = None
 ) -> Callable[[F], F]:
     """Mark a feature as implemented but not integrated into pipeline.
 
     Unused features are fully working implementations that aren't called
-    by the main analysis pipeline. These don't emit warnings when called
-    (they work fine), but are marked for tracking.
+    by the main analysis pipeline. Unlike @experimental, these don't emit
+    warnings when called (they work fine), but are marked for tracking.
 
     Use this for:
     - Features awaiting CLI integration
@@ -54,54 +101,3 @@ def unused(
         return func
 
     return decorator
-
-
-def experimental(
-    reason: str, *, issue: int | None = None, since: str | None = None
-) -> Callable[[F], F]:
-    """Mark a feature as experimental/not fully integrated.
-
-    Experimental features are working implementations that may change
-    or be removed. They emit a warning when called to alert users.
-
-    Use this for:
-    - Features under active development
-    - APIs that may change
-    - Functionality that needs more testing
-
-    Args:
-        reason: Why this is experimental (e.g., "API may change")
-        issue: Optional GitHub issue number tracking this feature
-        since: Optional version when this became experimental
-
-    Example:
-        >>> @experimental("API may change", issue=42, since="0.35.0")
-        ... def new_analysis_method():
-        ...     pass
-
-    Returns:
-        Wrapped function that emits ExperimentalWarning when called
-    """
-
-    def decorator(func: F) -> F:
-        @functools.wraps(func)
-        def wrapper(*args, **kwargs):  # type: ignore[no-untyped-def]
-            issue_ref = f" (see issue #{issue})" if issue else ""
-            version_ref = f" since {since}" if since else ""
-            warnings.warn(
-                f"{func.__name__} is experimental{version_ref}: {reason}{issue_ref}",
-                category=FutureWarning,
-                stacklevel=2,
-            )
-            return func(*args, **kwargs)
-
-        wrapper.__experimental__ = True  # type: ignore[attr-defined]
-        wrapper.__experimental_reason__ = reason  # type: ignore[attr-defined]
-        if issue:
-            wrapper.__experimental_issue__ = issue  # type: ignore[attr-defined]
-        if since:
-            wrapper.__experimental_since__ = since  # type: ignore[attr-defined]
-
-        return wrapper  # type: ignore[return-value]
-
-    return decorator

kinemotion/core/filtering.py

@@ -1,25 +1,11 @@
 """Advanced filtering techniques for robust trajectory processing."""
 
 import numpy as np
-from numpy.lib.stride_tricks import sliding_window_view
-from scipy.ndimage import convolve1d
 from scipy.signal import medfilt
 
 from .experimental import unused
 
 
-def _ensure_odd_window_length(window_length: int) -> int:
-    """Ensure window_length is odd (required for Savitzky-Golay filter).
-
-    Args:
-        window_length: Desired window length
-
-    Returns:
-        Odd window length (increments by 1 if even)
-    """
-    return window_length + 1 if window_length % 2 == 0 else window_length
-
-
 def detect_outliers_ransac(
     positions: np.ndarray,
     window_size: int = 15,
@@ -33,8 +19,6 @@ def detect_outliers_ransac(
     from a polynomial fit of nearby points. This catches MediaPipe tracking glitches
     where landmarks jump to incorrect positions.
 
-    Vectorized implementation using convolution for 10-20x speedup.
-
     Args:
         positions: 1D array of position values (e.g., y-coordinates)
         window_size: Size of sliding window for local fitting
@@ -50,82 +34,41 @@ def detect_outliers_ransac(
     if n < window_size:
         return is_outlier
 
-    window_size = _ensure_odd_window_length(window_size)
-    half_window = window_size // 2
-
-    # For centered quadratic fit, we can compute the predicted value at
-    # the window center using convolution. This is much faster than
-    # calling np.polyfit for each window.
-    #
-    # For a quadratic fit y = ax² + bx + c with centered window:
-    # - Predicted value at center (x=0) is just the intercept c
-    # - c can be computed from sum(y) and sum(x²*y) using precomputed constants
-    #
-    # The key insight: sum(y) and sum(x²*y) are convolution operations!
-
-    # Window indices (centered at 0)
-    x = np.arange(-half_window, half_window + 1)
-
-    # Precompute constants for the normal equations
-    sum_x2 = np.sum(x**2)
-    sum_x4 = np.sum(x**4)
-    det = window_size * sum_x4 - sum_x2**2
-
-    # Handle edge case where determinant is zero (shouldn't happen with valid window)
-    if det == 0:
-        return is_outlier
-
-    # Kernels for convolution
-    ones_kernel = np.ones(window_size)
-    x2_kernel = x**2
-
-    # Pad positions for boundary handling (use edge padding like original)
-    pad_width = half_window
-    padded = np.pad(positions, pad_width, mode="edge")
+    # Ensure window size is odd
+    if window_size % 2 == 0:
+        window_size += 1
 
-    # Compute sums via convolution
-    # sum_y[i] = sum of positions in window centered at i
-    # sum_x2y[i] = sum of (x² * positions) in window centered at i
-    sum_y = convolve1d(padded, ones_kernel, mode="constant")
-    sum_x2y = convolve1d(padded, x2_kernel, mode="constant")
-
-    # Remove padding to match original positions length
-    sum_y = sum_y[pad_width:-pad_width]
-    sum_x2y = sum_x2y[pad_width:-pad_width]
-
-    # Compute predicted values at window centers
-    # For centered fit: predicted = c = (sum_x4 * sum_y - sum_x2 * sum_x2y) / det
-    predicted = (sum_x4 * sum_y - sum_x2 * sum_x2y) / det
-
-    # Calculate residuals
-    residuals = np.abs(positions - predicted)
+    half_window = window_size // 2
 
-    # Mark outliers based on threshold
-    outlier_candidates = residuals > threshold
+    for i in range(n):
+        # Define window around current point
+        start = max(0, i - half_window)
+        end = min(n, i + half_window + 1)
+        window_positions = positions[start:end]
+        window_indices = np.arange(start, end)
 
-    if not np.any(outlier_candidates):
-        return is_outlier
+        if len(window_positions) < 3:
+            continue
 
-    # RANSAC criterion: point is outlier if most OTHER points in window are inliers
-    # Compute fraction of inliers in each window using convolution
-    inlier_mask = (residuals <= threshold).astype(float)
-    inliers_in_window = convolve1d(
-        np.pad(inlier_mask, pad_width, mode="edge"),
-        ones_kernel,
-        mode="constant",
-    )
-    inliers_in_window = inliers_in_window[pad_width:-pad_width]
-
-    # Account for variable window sizes at boundaries
-    # At boundaries, windows are smaller, so we need to adjust the count
-    for i in range(n):
-        actual_window_size = min(i + half_window + 1, n) - max(0, i - half_window)
-        if actual_window_size < 3:
+        # Fit polynomial (quadratic) to window
+        # Use polyfit with degree 2 (parabolic motion)
+        try:
+            coeffs = np.polyfit(window_indices, window_positions, deg=2)
+            predicted = np.polyval(coeffs, window_indices)
+
+            # Calculate residuals
+            residuals = np.abs(window_positions - predicted)
+
+            # Point is outlier if its residual is large
+            local_idx = i - start
+            if local_idx < len(residuals) and residuals[local_idx] > threshold:
+                # Also check if most other points are inliers (RANSAC criterion)
+                inliers = np.sum(residuals <= threshold)
+                if inliers / len(residuals) >= min_inliers:
+                    is_outlier[i] = True
+        except np.linalg.LinAlgError:
+            # Polyfit failed, skip this window
             continue
-        if outlier_candidates[i]:
-            inlier_fraction = inliers_in_window[i] / actual_window_size
-            if inlier_fraction >= min_inliers:
-                is_outlier[i] = True
 
     return is_outlier
 
@@ -150,7 +93,9 @@ def detect_outliers_median(
     if len(positions) < window_size:
         return np.zeros(len(positions), dtype=bool)
 
-    window_size = _ensure_odd_window_length(window_size)
+    # Ensure window size is odd
+    if window_size % 2 == 0:
+        window_size += 1
 
     # Apply median filter
     median_filtered = medfilt(positions, kernel_size=window_size)
@@ -358,8 +303,6 @@ def bilateral_temporal_filter(
     1. Temporal distance (like regular smoothing)
     2. Intensity similarity (preserves edges)
 
-    Vectorized implementation using sliding_window_view for 10-30x speedup.
-
     Args:
         positions: 1D array of position values
         window_size: Temporal window size (must be odd)
@@ -370,39 +313,36 @@ def bilateral_temporal_filter(
         Filtered position array
     """
     n = len(positions)
-    if n == 0:
-        return np.array([])
+    filtered = np.zeros(n)
 
-    window_size = _ensure_odd_window_length(window_size)
-    half_window = window_size // 2
+    # Ensure window size is odd
+    if window_size % 2 == 0:
+        window_size += 1
 
-    # Pad edges with boundary values to maintain consistent window size
-    # This provides context for boundary positions while preserving edge information
-    padded = np.pad(positions, half_window, mode="edge")
+    half_window = window_size // 2
 
-    # Create all sliding windows at once: shape (n, window_size)
-    # Each row represents the window centered at the corresponding input position
-    windows = sliding_window_view(padded, window_size)
+    for i in range(n):
+        # Define window
+        start = max(0, i - half_window)
+        end = min(n, i + half_window + 1)
 
-    # Precompute spatial weights (only depends on distance from center)
-    temporal_indices = np.arange(-half_window, half_window + 1)
-    spatial_weights = np.exp(-(temporal_indices**2) / (2 * sigma_spatial**2))
+        # Get window positions
+        window_pos = positions[start:end]
+        center_pos = positions[i]
 
-    # Extract center positions for intensity weight computation
-    center_positions = windows[:, half_window]  # Shape: (n,)
-    center_positions = center_positions.reshape(-1, 1)  # Shape: (n, 1) for broadcast
+        # Compute spatial (temporal) weights
+        temporal_indices = np.arange(start - i, end - i)
+        spatial_weights = np.exp(-(temporal_indices**2) / (2 * sigma_spatial**2))
 
-    # Compute intensity weights (data-dependent, varies by window)
-    # intensity_diff[i, j] = windows[i, j] - windows[i, center]
-    intensity_diff = windows - center_positions  # Broadcasting: (n, window_size)
-    intensity_weights = np.exp(-(intensity_diff**2) / (2 * sigma_intensity**2))
+        # Compute intensity (position difference) weights
+        intensity_diff = window_pos - center_pos
+        intensity_weights = np.exp(-(intensity_diff**2) / (2 * sigma_intensity**2))
 
-    # Combine weights: spatial_weights broadcasts to (n, window_size)
-    weights = spatial_weights * intensity_weights
-    # Normalize each window's weights to sum to 1
-    weights /= weights.sum(axis=1, keepdims=True)
+        # Combined weights (bilateral)
+        weights = spatial_weights * intensity_weights
+        weights /= np.sum(weights)  # Normalize
 
-    # Compute weighted average for each window
-    filtered = (weights * windows).sum(axis=1)
+        # Weighted average
+        filtered[i] = np.sum(weights * window_pos)
 
     return filtered

kinemotion/core/pipeline_utils.py

@@ -8,8 +8,8 @@ from typing import TypeVar
 import cv2
 import numpy as np
 
-from ..countermovement_jump.analysis import compute_average_hip_position
-from ..drop_jump.analysis import compute_average_foot_position
+from ..cmj.analysis import compute_average_hip_position
+from ..dropjump.analysis import compute_average_foot_position
 from .auto_tuning import AnalysisParameters, QualityPreset, VideoCharacteristics
 from .pose import MediaPipePoseTracker
 from .smoothing import smooth_landmarks, smooth_landmarks_advanced

kinemotion/core/pose.py

@@ -198,6 +198,55 @@ class PoseTrackerFactory:
 
         return MediaPipePoseTracker(**filtered_kwargs)
 
+    @classmethod
+    def get_available_backends(cls) -> list[str]:
+        """Get list of available backends.
+
+        Returns:
+            List containing 'mediapipe'
+        """
+        return ["mediapipe"]
+
+    @classmethod
+    def get_backend_info(cls, backend: str) -> dict[str, str]:
+        """Get information about a backend.
+
+        Args:
+            backend: Backend name
+
+        Returns:
+            Dictionary with backend information
+        """
+        if backend.lower() in ("mediapipe", "mp"):
+            return {
+                "name": "MediaPipe",
+                "description": "Pose tracking using MediaPipe Tasks API",
+                "performance": "~48 FPS",
+                "accuracy": "Reference (validated for jumps)",
+                "requirements": "mediapipe package",
+            }
+        return {}
+
+
+def get_tracker_info(tracker: object) -> str:
+    """Get detailed information about a pose tracker instance.
+
+    Args:
+        tracker: Pose tracker instance
+
+    Returns:
+        Formatted string with tracker details
+    """
+    tracker_class = type(tracker).__name__
+    module = type(tracker).__module__
+
+    info = f"{tracker_class} (from {module})"
+
+    if tracker_class == "MediaPipePoseTracker":
+        info += " [MediaPipe Tasks API]"
+
+    return info
+
 
 def _extract_landmarks_from_results(
     pose_landmarks: mp.tasks.vision.components.containers.NormalizedLandmark,  # type: ignore[valid-type]
@@ -224,6 +273,28 @@ def _extract_landmarks_from_results(
     return landmarks
 
 
+# Legacy compatibility aliases for Solution API enum values
+class _LegacyPoseLandmark:
+    """Compatibility shim for Solution API enum values."""
+
+    LEFT_ANKLE = 27
+    RIGHT_ANKLE = 28
+    LEFT_HEEL = 29
+    RIGHT_HEEL = 30
+    LEFT_FOOT_INDEX = 31
+    RIGHT_FOOT_INDEX = 32
+    LEFT_HIP = 23
+    RIGHT_HIP = 24
+    LEFT_SHOULDER = 11
+    RIGHT_SHOULDER = 12
+    NOSE = 0
+    LEFT_KNEE = 25
+    RIGHT_KNEE = 26
+
+
+PoseLandmark = _LegacyPoseLandmark
+
+
 def compute_center_of_mass(
     landmarks: dict[str, tuple[float, float, float]],
     visibility_threshold: float = 0.5,
@@ -302,37 +373,6 @@ def compute_center_of_mass(
     return (com_x, com_y, com_visibility)
 
 
-def _compute_mean_landmark_position(
-    landmark_keys: list[str],
-    landmarks: dict[str, tuple[float, float, float]],
-    vis_threshold: float,
-) -> tuple[float, float, float] | None:
-    """Compute mean position and visibility from multiple landmarks.
-
-    Args:
-        landmark_keys: List of landmark key names to average
-        landmarks: Dictionary of landmark positions
-        vis_threshold: Minimum visibility threshold
-
-    Returns:
-        (x, y, visibility) tuple if any landmarks are visible, else None
-    """
-    positions = [
-        (x, y, vis)
-        for key in landmark_keys
-        if key in landmarks
-        for x, y, vis in [landmarks[key]]
-        if vis > vis_threshold
-    ]
-    if not positions:
-        return None
-
-    x = float(np.mean([p[0] for p in positions]))
-    y = float(np.mean([p[1] for p in positions]))
-    vis = float(np.mean([p[2] for p in positions]))
-    return (x, y, vis)
-
-
 def _add_head_segment(
     segments: list,
     weights: list,
@@ -358,17 +398,20 @@ def _add_trunk_segment(
 ) -> None:
     """Add trunk segment (50% body mass) if visible."""
     trunk_keys = ["left_shoulder", "right_shoulder", "left_hip", "right_hip"]
-    trunk_pos = _compute_mean_landmark_position(trunk_keys, landmarks, vis_threshold)
-
-    if trunk_pos is not None:
-        # Require at least 2 visible landmarks for valid trunk
-        visible_count = sum(
-            1 for key in trunk_keys if key in landmarks and landmarks[key][2] > vis_threshold
-        )
-        if visible_count >= 2:
-            segments.append((trunk_pos[0], trunk_pos[1]))
-            weights.append(0.50)
-            visibilities.append(trunk_pos[2])
+    trunk_pos = [
+        (x, y, vis)
+        for key in trunk_keys
+        if key in landmarks
+        for x, y, vis in [landmarks[key]]
+        if vis > vis_threshold
+    ]
+    if len(trunk_pos) >= 2:
+        trunk_x = float(np.mean([p[0] for p in trunk_pos]))
+        trunk_y = float(np.mean([p[1] for p in trunk_pos]))
+        trunk_vis = float(np.mean([p[2] for p in trunk_pos]))
+        segments.append((trunk_x, trunk_y))
+        weights.append(0.50)
+        visibilities.append(trunk_vis)
 
 
 def _add_limb_segment(
@@ -408,9 +451,17 @@ def _add_foot_segment(
 ) -> None:
     """Add foot segment (1.5% body mass per foot) if visible."""
     foot_keys = [f"{side}_ankle", f"{side}_heel", f"{side}_foot_index"]
-    foot_pos = _compute_mean_landmark_position(foot_keys, landmarks, vis_threshold)
-
-    if foot_pos is not None:
-        segments.append((foot_pos[0], foot_pos[1]))
+    foot_pos = [
+        (x, y, vis)
+        for key in foot_keys
+        if key in landmarks
+        for x, y, vis in [landmarks[key]]
+        if vis > vis_threshold
+    ]
+    if foot_pos:
+        foot_x = float(np.mean([p[0] for p in foot_pos]))
+        foot_y = float(np.mean([p[1] for p in foot_pos]))
+        foot_vis = float(np.mean([p[2] for p in foot_pos]))
+        segments.append((foot_x, foot_y))
         weights.append(0.015)
-        visibilities.append(foot_pos[2])
+        visibilities.append(foot_vis)

kinemotion/core/quality.py

@@ -86,11 +86,13 @@ def calculate_position_stability(
     if len(positions) < window_size:
         return float(np.var(positions))
 
-    # Vectorized rolling variance using sliding window view
-    from numpy.lib.stride_tricks import sliding_window_view
+    # Calculate rolling variance
+    rolling_vars = []
+    for i in range(len(positions) - window_size + 1):
+        window = positions[i : i + window_size]
+        rolling_vars.append(np.var(window))
 
-    windows = sliding_window_view(positions, window_size)
-    return float(np.mean(np.var(windows, axis=1)))
+    return float(np.mean(rolling_vars))
 
 
 def assess_tracking_quality(