kinemotion 0.33.2__py3-none-any.whl → 0.35.0__py3-none-any.whl

kinemotion/core/experimental.py

@@ -0,0 +1,103 @@
+"""Decorators for marking experimental and unused features.
+
+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.
+"""
+
+import functools
+import warnings
+from collections.abc import Callable
+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. Unlike @experimental, these don't emit
+    warnings when called (they work fine), but are marked for tracking.
+
+    Use this for:
+    - Features awaiting CLI integration
+    - Alternative implementations not yet exposed
+    - Code kept for backward compatibility
+
+    Args:
+        reason: Why this is unused (e.g., "awaiting CLI parameter")
+        remove_in: Optional version when this might be removed if not integrated
+        since: Optional version when this became unused
+
+    Example:
+        >>> @unused("Not called by pipeline", remove_in="1.0.0", since="0.34.0")
+        ... def calculate_adaptive_threshold():
+        ...     pass
+
+    Returns:
+        Original function with metadata attached (no runtime behavior change)
+    """
+
+    def decorator(func: F) -> F:
+        # Don't wrap - we don't want warnings when calling it
+        # Just attach metadata for documentation/cleanup tools
+        func.__unused__ = True  # type: ignore[attr-defined]
+        func.__unused_reason__ = reason  # type: ignore[attr-defined]
+        if remove_in:
+            func.__unused_remove_in__ = remove_in  # type: ignore[attr-defined]
+        if since:
+            func.__unused_since__ = since  # type: ignore[attr-defined]
+
+        return func
+
+    return decorator

kinemotion/core/filtering.py

@@ -3,6 +3,8 @@
 import numpy as np
 from scipy.signal import medfilt
 
+from .experimental import unused
+
 
 def detect_outliers_ransac(
     positions: np.ndarray,
@@ -226,6 +228,11 @@ def reject_outliers(
     return cleaned_positions, outlier_mask
 
 
+@unused(
+    reason="Not called by analysis pipeline - alternative adaptive smoothing approach",
+    remove_in="1.0.0",
+    since="0.34.0",
+)
 def adaptive_smooth_window(
     positions: np.ndarray,
     base_window: int = 5,

kinemotion/core/smoothing.py

@@ -419,3 +419,37 @@ def smooth_landmarks_advanced(
     return _smooth_landmarks_core(
         landmark_sequence, window_length, polyorder, advanced_smoother
     )
+
+
+def interpolate_threshold_crossing(
+    vel_before: float,
+    vel_after: float,
+    velocity_threshold: float,
+) -> float:
+    """
+    Find fractional offset where velocity crosses threshold between two frames.
+
+    Uses linear interpolation assuming velocity changes linearly between frames.
+
+    Args:
+        vel_before: Velocity at frame boundary N (absolute value)
+        vel_after: Velocity at frame boundary N+1 (absolute value)
+        velocity_threshold: Threshold value
+
+    Returns:
+        Fractional offset from frame N (0.0 to 1.0)
+    """
+    # Handle edge cases
+    if abs(vel_after - vel_before) < 1e-9:  # Velocity not changing
+        return 0.5
+
+    # Linear interpolation: at what fraction t does velocity equal threshold?
+    # vel(t) = vel_before + t * (vel_after - vel_before)
+    # Solve for t when vel(t) = threshold:
+    # threshold = vel_before + t * (vel_after - vel_before)
+    # t = (threshold - vel_before) / (vel_after - vel_before)
+
+    t = (velocity_threshold - vel_before) / (vel_after - vel_before)
+
+    # Clamp to [0, 1] range
+    return float(max(0.0, min(1.0, t)))

kinemotion/core/validation.py

@@ -0,0 +1,198 @@
+"""Shared validation infrastructure for jump metrics.
+
+Provides base classes and enums for validating Counter Movement Jump (CMJ)
+and Drop Jump metrics against physiological bounds.
+
+Contains:
+- ValidationSeverity: Severity levels for issues (ERROR, WARNING, INFO)
+- ValidationIssue: Single validation issue dataclass
+- ValidationResult: Aggregated validation results
+- AthleteProfile: Athlete performance categories
+- MetricBounds: Physiological bounds for any metric
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class ValidationSeverity(Enum):
+    """Severity level for validation issues."""
+
+    ERROR = "ERROR"  # Metrics invalid, likely data corruption
+    WARNING = "WARNING"  # Metrics valid but unusual, needs review
+    INFO = "INFO"  # Normal variation, informational only
+
+
+@dataclass
+class ValidationIssue:
+    """Single validation issue."""
+
+    severity: ValidationSeverity
+    metric: str
+    message: str
+    value: float | None = None
+    bounds: tuple[float, float] | None = None
+
+
+class AthleteProfile(Enum):
+    """Athlete performance categories for metric bounds."""
+
+    ELDERLY = "elderly"  # 70+, deconditioned
+    UNTRAINED = "untrained"  # Sedentary, no training
+    RECREATIONAL = "recreational"  # Fitness class, moderate activity
+    TRAINED = "trained"  # Regular athlete, 3-5 years training
+    ELITE = "elite"  # Competitive athlete, college/professional level
+
+
+@dataclass
+class MetricBounds:
+    """Physiological bounds for a single metric.
+
+    Attributes:
+        absolute_min: Absolute minimum value (error threshold)
+        practical_min: Practical minimum for weakest athletes
+        recreational_min: Minimum for recreational athletes
+        recreational_max: Maximum for recreational athletes
+        elite_min: Minimum for elite athletes
+        elite_max: Maximum for elite athletes
+        absolute_max: Absolute maximum value (error threshold)
+        unit: Unit of measurement (e.g., "m", "s", "m/s", "degrees")
+    """
+
+    absolute_min: float
+    practical_min: float
+    recreational_min: float
+    recreational_max: float
+    elite_min: float
+    elite_max: float
+    absolute_max: float
+    unit: str
+
+    def contains(self, value: float, profile: AthleteProfile) -> bool:
+        """Check if value is within bounds for athlete profile."""
+        if profile == AthleteProfile.ELDERLY:
+            return self.practical_min <= value <= self.recreational_max
+        elif profile == AthleteProfile.UNTRAINED:
+            return self.practical_min <= value <= self.recreational_max
+        elif profile == AthleteProfile.RECREATIONAL:
+            return self.recreational_min <= value <= self.recreational_max
+        elif profile == AthleteProfile.TRAINED:
+            # Trained athletes: midpoint between recreational and elite
+            trained_min = (self.recreational_min + self.elite_min) / 2
+            trained_max = (self.recreational_max + self.elite_max) / 2
+            return trained_min <= value <= trained_max
+        elif profile == AthleteProfile.ELITE:
+            return self.elite_min <= value <= self.elite_max
+        return False
+
+    def is_physically_possible(self, value: float) -> bool:
+        """Check if value is within absolute physiological limits."""
+        return self.absolute_min <= value <= self.absolute_max
+
+
+@dataclass
+class ValidationResult:
+    """Base validation result for jump metrics."""
+
+    issues: list[ValidationIssue] = field(default_factory=list)
+    status: str = "PASS"  # "PASS", "PASS_WITH_WARNINGS", "FAIL"
+    athlete_profile: AthleteProfile | None = None
+
+    def add_error(
+        self,
+        metric: str,
+        message: str,
+        value: float | None = None,
+        bounds: tuple[float, float] | None = None,
+    ) -> None:
+        """Add error-level issue."""
+        self.issues.append(
+            ValidationIssue(
+                severity=ValidationSeverity.ERROR,
+                metric=metric,
+                message=message,
+                value=value,
+                bounds=bounds,
+            )
+        )
+
+    def add_warning(
+        self,
+        metric: str,
+        message: str,
+        value: float | None = None,
+        bounds: tuple[float, float] | None = None,
+    ) -> None:
+        """Add warning-level issue."""
+        self.issues.append(
+            ValidationIssue(
+                severity=ValidationSeverity.WARNING,
+                metric=metric,
+                message=message,
+                value=value,
+                bounds=bounds,
+            )
+        )
+
+    def add_info(
+        self,
+        metric: str,
+        message: str,
+        value: float | None = None,
+    ) -> None:
+        """Add info-level issue."""
+        self.issues.append(
+            ValidationIssue(
+                severity=ValidationSeverity.INFO,
+                metric=metric,
+                message=message,
+                value=value,
+            )
+        )
+
+    def finalize_status(self) -> None:
+        """Determine final pass/fail status based on issues."""
+        has_errors = any(
+            issue.severity == ValidationSeverity.ERROR for issue in self.issues
+        )
+        has_warnings = any(
+            issue.severity == ValidationSeverity.WARNING for issue in self.issues
+        )
+
+        if has_errors:
+            self.status = "FAIL"
+        elif has_warnings:
+            self.status = "PASS_WITH_WARNINGS"
+        else:
+            self.status = "PASS"
+
+    @abstractmethod
+    def to_dict(self) -> dict:
+        """Convert validation result to JSON-serializable dictionary."""
+        pass
+
+
+class MetricsValidator(ABC):
+    """Base validator for jump metrics."""
+
+    def __init__(self, assumed_profile: AthleteProfile | None = None):
+        """Initialize validator.
+
+        Args:
+            assumed_profile: If provided, validate against this specific profile.
+                            Otherwise, estimate from metrics.
+        """
+        self.assumed_profile = assumed_profile
+
+    @abstractmethod
+    def validate(self, metrics: dict) -> ValidationResult:
+        """Validate metrics comprehensively.
+
+        Args:
+            metrics: Dictionary with metric values
+
+        Returns:
+            ValidationResult with all issues and status
+        """
+        pass

kinemotion/dropjump/__init__.py

@@ -1,12 +1,12 @@
 """Drop jump analysis module."""
 
+from ..core.smoothing import interpolate_threshold_crossing
 from .analysis import (
     ContactState,
     calculate_adaptive_threshold,
     compute_average_foot_position,
     detect_ground_contact,
     find_interpolated_phase_transitions_with_curvature,
-    interpolate_threshold_crossing,
     refine_transition_with_curvature,
 )
 from .debug_overlay import DebugOverlayRenderer

kinemotion/dropjump/analysis.py

@@ -4,9 +4,11 @@ from enum import Enum
 
 import numpy as np
 
+from ..core.experimental import unused
 from ..core.smoothing import (
     compute_acceleration_from_derivative,
     compute_velocity_from_derivative,
+    interpolate_threshold_crossing,
 )
 
 
@@ -18,6 +20,11 @@ class ContactState(Enum):
     UNKNOWN = "unknown"
 
 
+@unused(
+    reason="Not called by analysis pipeline - awaiting CLI integration",
+    remove_in="1.0.0",
+    since="0.34.0",
+)
 def calculate_adaptive_threshold(
     positions: np.ndarray,
     fps: float,
@@ -29,6 +36,18 @@ def calculate_adaptive_threshold(
     """
     Calculate adaptive velocity threshold based on baseline motion characteristics.
 
+    .. warning::
+        **Status: Implemented but Not Integrated**
+
+        This function is fully implemented and tested but not called by the
+        analysis pipeline. See ``docs/development/errors-findings.md`` for details.
+
+        **To integrate**: Add CLI parameter ``--use-adaptive-threshold`` and
+        call this function before contact detection.
+
+        **Roadmap**: Planned for Phase 2 if users report issues with varying
+        video conditions.
+
     Analyzes the first few seconds of video (assumed to be relatively stationary,
     e.g., athlete standing on box) to determine the noise floor, then sets threshold
     as a multiple of this baseline noise.
@@ -405,40 +424,6 @@ def find_contact_phases(
     return phases
 
 
-def interpolate_threshold_crossing(
-    vel_before: float,
-    vel_after: float,
-    velocity_threshold: float,
-) -> float:
-    """
-    Find fractional offset where velocity crosses threshold between two frames.
-
-    Uses linear interpolation assuming velocity changes linearly between frames.
-
-    Args:
-        vel_before: Velocity at frame boundary N (absolute value)
-        vel_after: Velocity at frame boundary N+1 (absolute value)
-        velocity_threshold: Threshold value
-
-    Returns:
-        Fractional offset from frame N (0.0 to 1.0)
-    """
-    # Handle edge cases
-    if abs(vel_after - vel_before) < 1e-9:  # Velocity not changing
-        return 0.5
-
-    # Linear interpolation: at what fraction t does velocity equal threshold?
-    # vel(t) = vel_before + t * (vel_after - vel_before)
-    # Solve for t when vel(t) = threshold:
-    # threshold = vel_before + t * (vel_after - vel_before)
-    # t = (threshold - vel_before) / (vel_after - vel_before)
-
-    t = (velocity_threshold - vel_before) / (vel_after - vel_before)
-
-    # Clamp to [0, 1] range
-    return float(max(0.0, min(1.0, t)))
-
-
 def _interpolate_phase_start(
     start_idx: int,
     state: ContactState,
@@ -831,6 +816,10 @@ def _calculate_average_visibility(
     return float(np.mean(foot_vis)) if foot_vis else 0.0
 
 
+@unused(
+    reason="Alternative implementation not called by pipeline",
+    since="0.34.0",
+)
 def extract_foot_positions_and_visibilities(
     smoothed_landmarks: list[dict[str, tuple[float, float, float]] | None],
 ) -> tuple[np.ndarray, np.ndarray]:

kinemotion/{core/dropjump_metrics_validator.py → dropjump/metrics_validator.py}

@@ -7,114 +7,26 @@ Provides severity levels (ERROR, WARNING, INFO) for different categories
 of metric issues.
 """
 
-from dataclasses import dataclass, field
-from enum import Enum
+from dataclasses import dataclass
 
-from kinemotion.core.dropjump_validation_bounds import (
-    AthleteProfile,
+from kinemotion.core.validation import (
+    MetricsValidator,
+    ValidationResult,
+)
+from kinemotion.dropjump.validation_bounds import (
     DropJumpBounds,
     estimate_athlete_profile,
 )
 
 
-class ValidationSeverity(Enum):
-    """Severity level for validation issues."""
-
-    ERROR = "ERROR"  # Metrics invalid, likely data corruption
-    WARNING = "WARNING"  # Metrics valid but unusual, needs review
-    INFO = "INFO"  # Normal variation, informational only
-
-
 @dataclass
-class ValidationIssue:
-    """Single validation issue."""
+class DropJumpValidationResult(ValidationResult):
+    """Drop jump-specific validation result."""
 
-    severity: ValidationSeverity
-    metric: str
-    message: str
-    value: float | None = None
-    bounds: tuple[float, float] | None = None
-
-
-@dataclass
-class ValidationResult:
-    """Complete validation result for drop jump metrics."""
-
-    issues: list[ValidationIssue] = field(default_factory=list)
-    status: str = "PASS"  # "PASS", "PASS_WITH_WARNINGS", "FAIL"
-    athlete_profile: AthleteProfile | None = None
     rsi: float | None = None
     contact_flight_ratio: float | None = None
     height_kinematic_trajectory_consistency: float | None = None  # % error
 
-    def add_error(
-        self,
-        metric: str,
-        message: str,
-        value: float | None = None,
-        bounds: tuple[float, float] | None = None,
-    ) -> None:
-        """Add error-level issue."""
-        self.issues.append(
-            ValidationIssue(
-                severity=ValidationSeverity.ERROR,
-                metric=metric,
-                message=message,
-                value=value,
-                bounds=bounds,
-            )
-        )
-
-    def add_warning(
-        self,
-        metric: str,
-        message: str,
-        value: float | None = None,
-        bounds: tuple[float, float] | None = None,
-    ) -> None:
-        """Add warning-level issue."""
-        self.issues.append(
-            ValidationIssue(
-                severity=ValidationSeverity.WARNING,
-                metric=metric,
-                message=message,
-                value=value,
-                bounds=bounds,
-            )
-        )
-
-    def add_info(
-        self,
-        metric: str,
-        message: str,
-        value: float | None = None,
-    ) -> None:
-        """Add info-level issue."""
-        self.issues.append(
-            ValidationIssue(
-                severity=ValidationSeverity.INFO,
-                metric=metric,
-                message=message,
-                value=value,
-            )
-        )
-
-    def finalize_status(self) -> None:
-        """Determine final pass/fail status based on issues."""
-        has_errors = any(
-            issue.severity == ValidationSeverity.ERROR for issue in self.issues
-        )
-        has_warnings = any(
-            issue.severity == ValidationSeverity.WARNING for issue in self.issues
-        )
-
-        if has_errors:
-            self.status = "FAIL"
-        elif has_warnings:
-            self.status = "PASS_WITH_WARNINGS"
-        else:
-            self.status = "PASS"
-
     def to_dict(self) -> dict:
         """Convert validation result to JSON-serializable dictionary.
 
@@ -144,28 +56,19 @@ class ValidationResult:
         }
 
 
-class DropJumpMetricsValidator:
+class DropJumpMetricsValidator(MetricsValidator):
     """Comprehensive drop jump metrics validator."""
 
-    def __init__(self, assumed_profile: AthleteProfile | None = None):
-        """Initialize validator.
-
-        Args:
-            assumed_profile: If provided, validate against this specific profile.
-                            Otherwise, estimate from metrics.
-        """
-        self.assumed_profile = assumed_profile
-
-    def validate(self, metrics: dict) -> ValidationResult:
+    def validate(self, metrics: dict) -> DropJumpValidationResult:
         """Validate drop jump metrics comprehensively.
 
         Args:
             metrics: Dictionary with drop jump metric values
 
         Returns:
-            ValidationResult with all issues and status
+            DropJumpValidationResult with all issues and status
         """
-        result = ValidationResult()
+        result = DropJumpValidationResult()
 
         # Estimate athlete profile if not provided
         if self.assumed_profile:
@@ -208,7 +111,7 @@ class DropJumpMetricsValidator:
         return result
 
     def _check_contact_time(
-        self, contact_time_ms: float, result: ValidationResult
+        self, contact_time_ms: float, result: DropJumpValidationResult
     ) -> None:
         """Validate contact time."""
         contact_time_s = contact_time_ms / 1000.0
@@ -233,7 +136,7 @@ class DropJumpMetricsValidator:
             )
 
     def _check_flight_time(
-        self, flight_time_ms: float, result: ValidationResult
+        self, flight_time_ms: float, result: DropJumpValidationResult
     ) -> None:
         """Validate flight time."""
         flight_time_s = flight_time_ms / 1000.0
@@ -257,7 +160,7 @@ class DropJumpMetricsValidator:
             )
 
     def _check_jump_height(
-        self, jump_height_m: float, result: ValidationResult
+        self, jump_height_m: float, result: DropJumpValidationResult
     ) -> None:
         """Validate jump height."""
         bounds = DropJumpBounds.JUMP_HEIGHT
@@ -280,7 +183,10 @@ class DropJumpMetricsValidator:
             )
 
     def _check_rsi(
-        self, contact_time_ms: float, flight_time_ms: float, result: ValidationResult
+        self,
+        contact_time_ms: float,
+        flight_time_ms: float,
+        result: DropJumpValidationResult,
     ) -> None:
         """Validate RSI and cross-check consistency."""
         contact_time_s = contact_time_ms / 1000.0
@@ -313,7 +219,7 @@ class DropJumpMetricsValidator:
         self,
         jump_height_kinematic_m: float,
         jump_height_trajectory_m: float,
-        result: ValidationResult,
+        result: DropJumpValidationResult,
     ) -> None:
         """Validate consistency between kinematic and trajectory-based heights.