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

kinemotion/api.py

@@ -11,6 +11,7 @@ import numpy as np
 from .cmj.analysis import detect_cmj_phases
 from .cmj.debug_overlay import CMJDebugOverlayRenderer
 from .cmj.kinematics import CMJMetrics, calculate_cmj_metrics
+from .cmj.metrics_validator import CMJMetricsValidator
 from .core.auto_tuning import (
     AnalysisParameters,
     QualityPreset,
@@ -18,8 +19,6 @@ from .core.auto_tuning import (
     analyze_video_sample,
     auto_tune_parameters,
 )
-from .core.cmj_metrics_validator import CMJMetricsValidator
-from .core.dropjump_metrics_validator import DropJumpMetricsValidator
 from .core.filtering import reject_outliers
 from .core.metadata import (
     AlgorithmConfig,
@@ -44,6 +43,7 @@ from .dropjump.analysis import (
 )
 from .dropjump.debug_overlay import DebugOverlayRenderer
 from .dropjump.kinematics import DropJumpMetrics, calculate_drop_jump_metrics
+from .dropjump.metrics_validator import DropJumpMetricsValidator
 
 
 def _parse_quality_preset(quality: str) -> QualityPreset:

kinemotion/cmj/analysis.py

@@ -5,6 +5,7 @@ from enum import Enum
 import numpy as np
 from scipy.signal import savgol_filter
 
+from ..core.experimental import unused
 from ..core.smoothing import compute_acceleration_from_derivative
 
 
@@ -52,6 +53,10 @@ class CMJPhase(Enum):
     UNKNOWN = "unknown"
 
 
+@unused(
+    reason="Alternative implementation not called by pipeline",
+    since="0.34.0",
+)
 def find_standing_phase(
     positions: np.ndarray,
     velocities: np.ndarray,
@@ -101,6 +106,10 @@ def find_standing_phase(
     return None
 
 
+@unused(
+    reason="Alternative implementation not called by pipeline",
+    since="0.34.0",
+)
 def find_countermovement_start(
     velocities: np.ndarray,
     countermovement_threshold: float = 0.015,
@@ -184,99 +193,6 @@ def find_lowest_point(
     return lowest_frame
 
 
-def refine_transition_with_curvature(
-    positions: np.ndarray,
-    velocities: np.ndarray,
-    initial_frame: int,
-    transition_type: str,
-    search_radius: int = 3,
-    window_length: int = 5,
-    polyorder: int = 2,
-) -> float:
-    """
-    Refine transition frame using trajectory curvature (acceleration patterns).
-
-    Uses acceleration (second derivative) to identify characteristic patterns:
-    - Landing: Large acceleration spike (impact deceleration)
-    - Takeoff: Acceleration change (transition from static to flight)
-
-    Args:
-        positions: Array of vertical positions
-        velocities: Array of vertical velocities
-        initial_frame: Initial estimate of transition frame
-        transition_type: Type of transition ("takeoff" or "landing")
-        search_radius: Frames to search around initial estimate (±radius)
-        window_length: Window size for acceleration calculation
-        polyorder: Polynomial order for Savitzky-Golay filter
-
-    Returns:
-        Refined fractional frame index.
-    """
-    # Compute acceleration using second derivative
-    acceleration = compute_acceleration_from_derivative(
-        positions, window_length=window_length, polyorder=polyorder
-    )
-
-    # Define search window
-    search_start = max(0, initial_frame - search_radius)
-    search_end = min(len(positions), initial_frame + search_radius + 1)
-
-    if search_start >= search_end:
-        return float(initial_frame)
-
-    search_accel = acceleration[search_start:search_end]
-
-    if transition_type == "landing":
-        # Landing: Find maximum absolute acceleration (impact)
-        peak_idx = int(np.argmax(np.abs(search_accel)))
-    elif transition_type == "takeoff":
-        # Takeoff: Find maximum acceleration change
-        accel_change = np.abs(np.diff(search_accel))
-        if len(accel_change) > 0:
-            peak_idx = int(np.argmax(accel_change))
-        else:
-            peak_idx = 0
-    else:
-        return float(initial_frame)
-
-    curvature_frame = search_start + peak_idx
-
-    # Blend curvature-based estimate with velocity-based estimate
-    # 70% curvature, 30% velocity
-    blended_frame = 0.7 * curvature_frame + 0.3 * initial_frame
-
-    return float(blended_frame)
-
-
-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
-    t = (velocity_threshold - vel_before) / (vel_after - vel_before)
-
-    # Clamp to [0, 1] range
-    return float(max(0.0, min(1.0, t)))
-
-
 def find_cmj_takeoff_from_velocity_peak(
     positions: np.ndarray,
     velocities: np.ndarray,
@@ -372,6 +288,10 @@ def find_cmj_landing_from_position_peak(
     return float(landing_frame)
 
 
+@unused(
+    reason="Experimental alternative superseded by backward search algorithm",
+    since="0.34.0",
+)
 def find_interpolated_takeoff_landing(
     positions: np.ndarray,
     velocities: np.ndarray,
@@ -417,7 +337,7 @@ def find_interpolated_takeoff_landing(
     return (takeoff_frame, landing_frame)
 
 
-def _find_takeoff_frame(
+def find_takeoff_frame(
     velocities: np.ndarray, peak_height_frame: int, fps: float
 ) -> float:
     """Find takeoff frame as peak upward velocity before peak height.
@@ -448,7 +368,7 @@ def _find_takeoff_frame(
         return float(takeoff_search_start + peak_vel_idx)
 
 
-def _find_lowest_frame(
+def find_lowest_frame(
     velocities: np.ndarray, positions: np.ndarray, takeoff_frame: float, fps: float
 ) -> float:
     """Find lowest point frame before takeoff."""
@@ -469,7 +389,7 @@ def _find_lowest_frame(
         return float(int(takeoff_frame) - int(fps * 0.2))
 
 
-def _find_landing_frame(
+def find_landing_frame(
     accelerations: np.ndarray, peak_height_frame: int, fps: float
 ) -> float:
     """Find landing frame after peak height after takeoff.
@@ -502,7 +422,7 @@ def _find_landing_frame(
     return float(landing_search_start + landing_idx)
 
 
-def _find_standing_end(velocities: np.ndarray, lowest_point: float) -> float | None:
+def find_standing_end(velocities: np.ndarray, lowest_point: float) -> float | None:
     """Find end of standing phase before lowest point."""
     if lowest_point <= 20:
         return None
@@ -556,9 +476,9 @@ def detect_cmj_phases(
         return None  # Peak too early, invalid
 
     # Step 2-4: Find all phases using helper functions
-    takeoff_frame = _find_takeoff_frame(velocities, peak_height_frame, fps)
-    lowest_point = _find_lowest_frame(velocities, positions, takeoff_frame, fps)
-    landing_frame = _find_landing_frame(accelerations, peak_height_frame, fps)
-    standing_end = _find_standing_end(velocities, lowest_point)
+    takeoff_frame = find_takeoff_frame(velocities, peak_height_frame, fps)
+    lowest_point = find_lowest_frame(velocities, positions, takeoff_frame, fps)
+    landing_frame = find_landing_frame(accelerations, peak_height_frame, fps)
+    standing_end = find_standing_end(velocities, lowest_point)
 
     return (standing_end, lowest_point, takeoff_frame, landing_frame)

kinemotion/{core/cmj_metrics_validator.py → cmj/metrics_validator.py}

@@ -7,120 +7,33 @@ 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.cmj_validation_bounds import (
-    AthleteProfile,
+from kinemotion.cmj.validation_bounds import (
     CMJBounds,
-    MetricBounds,
     MetricConsistency,
     RSIBounds,
     TripleExtensionBounds,
     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."""
-
-    severity: ValidationSeverity
-    metric: str
-    message: str
-    value: float | None = None
-    bounds: tuple[float, float] | None = None
+from kinemotion.core.validation import (
+    AthleteProfile,
+    MetricBounds,
+    MetricsValidator,
+    ValidationResult,
+)
 
 
 @dataclass
-class ValidationResult:
-    """Complete validation result for CMJ metrics."""
+class CMJValidationResult(ValidationResult):
+    """CMJ-specific validation result."""
 
-    issues: list[ValidationIssue] = field(default_factory=list)
-    status: str = "PASS"  # "PASS", "PASS_WITH_WARNINGS", "FAIL"
-    athlete_profile: AthleteProfile | None = None
     rsi: float | None = None
     height_flight_time_consistency: float | None = None  # % error
     velocity_height_consistency: float | None = None  # % error
     depth_height_ratio: float | None = None
     contact_depth_ratio: float | 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"
-
     def to_dict(self) -> dict:
         """Convert validation result to JSON-serializable dictionary.
 
@@ -152,28 +65,19 @@ class ValidationResult:
         }
 
 
-class CMJMetricsValidator:
+class CMJMetricsValidator(MetricsValidator):
     """Comprehensive CMJ 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) -> CMJValidationResult:
         """Validate CMJ metrics comprehensively.
 
         Args:
             metrics: Dictionary with CMJ metric values
 
         Returns:
-            ValidationResult with all issues and status
+            CMJValidationResult with all issues and status
         """
-        result = ValidationResult()
+        result = CMJValidationResult()
 
         # Estimate athlete profile if not provided
         if self.assumed_profile:
@@ -209,7 +113,7 @@ class CMJMetricsValidator:
         return result
 
     def _check_flight_time(
-        self, metrics: dict, result: ValidationResult, profile: AthleteProfile
+        self, metrics: dict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Validate flight time."""
         flight_time = metrics.get("flight_time")
@@ -252,7 +156,7 @@ class CMJMetricsValidator:
             )
 
     def _check_jump_height(
-        self, metrics: dict, result: ValidationResult, profile: AthleteProfile
+        self, metrics: dict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Validate jump height."""
         jump_height = metrics.get("jump_height")
@@ -294,7 +198,7 @@ class CMJMetricsValidator:
             )
 
     def _check_countermovement_depth(
-        self, metrics: dict, result: ValidationResult, profile: AthleteProfile
+        self, metrics: dict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Validate countermovement depth."""
         depth = metrics.get("countermovement_depth")
@@ -336,7 +240,7 @@ class CMJMetricsValidator:
             )
 
     def _check_concentric_duration(
-        self, metrics: dict, result: ValidationResult, profile: AthleteProfile
+        self, metrics: dict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Validate concentric duration (contact time)."""
         duration = metrics.get("concentric_duration")
@@ -379,7 +283,7 @@ class CMJMetricsValidator:
             )
 
     def _check_eccentric_duration(
-        self, metrics: dict, result: ValidationResult, profile: AthleteProfile
+        self, metrics: dict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Validate eccentric duration."""
         duration = metrics.get("eccentric_duration")
@@ -413,7 +317,7 @@ class CMJMetricsValidator:
             )
 
     def _check_peak_velocities(
-        self, metrics: dict, result: ValidationResult, profile: AthleteProfile
+        self, metrics: dict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Validate peak eccentric and concentric velocities."""
         # Eccentric
@@ -483,7 +387,7 @@ class CMJMetricsValidator:
                 )
 
     def _check_flight_time_height_consistency(
-        self, metrics: dict, result: ValidationResult
+        self, metrics: dict, result: CMJValidationResult
     ) -> None:
         """Verify jump height is consistent with flight time."""
         flight_time = metrics.get("flight_time")
@@ -517,7 +421,7 @@ class CMJMetricsValidator:
             )
 
     def _check_velocity_height_consistency(
-        self, metrics: dict, result: ValidationResult
+        self, metrics: dict, result: CMJValidationResult
     ) -> None:
         """Verify peak velocity is consistent with jump height."""
         velocity = metrics.get("peak_concentric_velocity")
@@ -554,7 +458,7 @@ class CMJMetricsValidator:
             )
 
     def _check_rsi_validity(
-        self, metrics: dict, result: ValidationResult, profile: AthleteProfile
+        self, metrics: dict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Validate Reactive Strength Index."""
         flight_time = metrics.get("flight_time")
@@ -606,7 +510,7 @@ class CMJMetricsValidator:
                 )
 
     def _check_depth_height_ratio(
-        self, metrics: dict, result: ValidationResult
+        self, metrics: dict, result: CMJValidationResult
     ) -> None:
         """Check countermovement depth to jump height ratio."""
         depth = metrics.get("countermovement_depth")
@@ -650,7 +554,7 @@ class CMJMetricsValidator:
             )
 
     def _check_contact_depth_ratio(
-        self, metrics: dict, result: ValidationResult
+        self, metrics: dict, result: CMJValidationResult
     ) -> None:
         """Check contact time to countermovement depth ratio."""
         contact = metrics.get("concentric_duration")
@@ -691,7 +595,7 @@ class CMJMetricsValidator:
             )
 
     def _check_triple_extension(
-        self, metrics: dict, result: ValidationResult, profile: AthleteProfile
+        self, metrics: dict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Validate triple extension angles."""
         angles = metrics.get("triple_extension")
@@ -750,7 +654,7 @@ class CMJMetricsValidator:
         self._check_joint_compensation_pattern(angles, result, profile)
 
     def _check_joint_compensation_pattern(
-        self, angles: dict, result: ValidationResult, profile: AthleteProfile
+        self, angles: dict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Detect compensatory joint patterns in triple extension.
 

kinemotion/{core/cmj_validation_bounds.py → cmj/validation_bounds.py}

@@ -15,64 +15,7 @@ References:
 - Bogdanis (2012): Plyometric training effects
 """
 
-from dataclasses import dataclass
-from enum import Enum
-
-
-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
+from kinemotion.core.validation import AthleteProfile, MetricBounds
 
 
 class CMJBounds:

kinemotion/core/cli_utils.py

@@ -6,6 +6,7 @@ from typing import Any, Protocol
 import click
 
 from .auto_tuning import AnalysisParameters, QualityPreset, VideoCharacteristics
+from .experimental import unused
 from .pose import PoseTracker
 from .smoothing import smooth_landmarks, smooth_landmarks_advanced
 from .video_io import VideoProcessor
@@ -22,6 +23,11 @@ class ExpertParameters(Protocol):
     visibility_threshold: float | None
 
 
+@unused(
+    reason="Not called by analysis pipeline - remnant from CLI refactoring",
+    remove_in="1.0.0",
+    since="0.34.0",
+)
 def determine_initial_confidence(
     quality_preset: QualityPreset,
     expert_params: ExpertParameters,
@@ -54,6 +60,11 @@ def determine_initial_confidence(
     return initial_detection_conf, initial_tracking_conf
 
 
+@unused(
+    reason="Not called by analysis pipeline - remnant from CLI refactoring",
+    remove_in="1.0.0",
+    since="0.34.0",
+)
 def track_all_frames(video: VideoProcessor, tracker: PoseTracker) -> tuple[list, list]:
     """Track pose landmarks in all video frames.
 
@@ -84,6 +95,11 @@ def track_all_frames(video: VideoProcessor, tracker: PoseTracker) -> tuple[list,
     return frames, landmarks_sequence
 
 
+@unused(
+    reason="Not called by analysis pipeline - remnant from CLI refactoring",
+    remove_in="1.0.0",
+    since="0.34.0",
+)
 def apply_expert_param_overrides(
     params: AnalysisParameters, expert_params: ExpertParameters
 ) -> AnalysisParameters:
@@ -107,6 +123,11 @@ def apply_expert_param_overrides(
     return params
 
 
+@unused(
+    reason="Not called by analysis pipeline - remnant from CLI refactoring",
+    remove_in="1.0.0",
+    since="0.34.0",
+)
 def print_auto_tuned_params(
     video: VideoProcessor,
     quality_preset: QualityPreset,
@@ -161,6 +182,11 @@ def print_auto_tuned_params(
     click.echo("=" * 60 + "\n", err=True)
 
 
+@unused(
+    reason="Not called by analysis pipeline - remnant from CLI refactoring",
+    remove_in="1.0.0",
+    since="0.34.0",
+)
 def smooth_landmark_sequence(
     landmarks_sequence: list, params: AnalysisParameters
 ) -> list: