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

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:

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/dropjump/kinematics.py

@@ -57,6 +57,7 @@ class DropJumpMetrics:
         self.jump_height: float | None = None
         self.jump_height_kinematic: float | None = None  # From flight time
         self.jump_height_trajectory: float | None = None  # From position tracking
+        self.drop_start_frame: int | None = None  # Frame when athlete leaves box
         self.contact_start_frame: int | None = None
         self.contact_end_frame: int | None = None
         self.flight_start_frame: int | None = None
@@ -164,7 +165,7 @@ def _determine_drop_start_frame(
             foot_y_positions,
             fps,
             min_stationary_duration=0.5,
-            position_change_threshold=0.005,
+            position_change_threshold=0.01,  # Improved from 0.005 for better accuracy
             smoothing_window=smoothing_window,
         )
     return drop_start_frame
@@ -412,6 +413,11 @@ def calculate_drop_jump_metrics(
         drop_start_frame, foot_y_positions, fps, smoothing_window
     )
 
+    # Store drop start frame in metrics
+    metrics.drop_start_frame = (
+        drop_start_frame_value if drop_start_frame_value > 0 else None
+    )
+
     # Find contact phases
     phases = find_contact_phases(contact_states)
     interpolated_phases = find_interpolated_phase_transitions_with_curvature(