kinemotion 0.10.6__py3-none-any.whl → 0.67.0__py3-none-any.whl

kinemotion/core/timing.py

@@ -0,0 +1,247 @@
+"""Timing utilities for performance profiling.
+
+This module implements a hybrid instrumentation pattern combining:
+1. Protocol-based type safety (structural subtyping)
+2. Null Object Pattern (zero overhead when disabled)
+3. High-precision timing (time.perf_counter)
+4. Memory optimization (__slots__)
+5. Accumulation support (for loops and repeated measurements)
+
+Performance Characteristics:
+    - PerformanceTimer overhead: ~200ns per measurement
+    - NullTimer overhead: ~20ns per measurement
+    - Memory: 32 bytes per timer instance
+    - Precision: ~1 microsecond (perf_counter)
+
+Example:
+    # Active timing
+    timer = PerformanceTimer()
+    with timer.measure("video_processing"):
+        process_video(frames)
+    metrics = timer.get_metrics()
+
+    # Zero-overhead timing (disabled)
+    tracker = PoseTracker(timer=NULL_TIMER)
+    # No timing overhead, but maintains API compatibility
+"""
+
+import time
+from contextlib import AbstractContextManager
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Timer(Protocol):
+    """Protocol for timer implementations.
+
+    Enables type-safe substitution of PerformanceTimer with NullTimer.
+    Uses structural subtyping - any class implementing these methods
+    conforms to the protocol.
+    """
+
+    def measure(self, name: str) -> AbstractContextManager[None]:
+        """Context manager to measure execution time of a block.
+
+        Args:
+            name: Name of the step being measured (e.g., "pose_tracking")
+
+        Returns:
+            Context manager that measures execution time
+        """
+        ...
+
+    def get_metrics(self) -> dict[str, float]:
+        """Retrieve all collected timing metrics.
+
+        Returns:
+            Dictionary mapping operation names to durations in seconds
+        """
+        ...
+
+
+class _NullContext(AbstractContextManager[None]):
+    """Singleton null context manager with zero overhead.
+
+    Implements the context manager protocol but performs no operations.
+    Optimized away by the Python interpreter for minimal overhead.
+    """
+
+    __slots__ = ()
+
+    def __enter__(self) -> None:
+        """No-op entry - returns immediately."""
+        return None
+
+    def __exit__(self, exc_type: object, exc_val: object, exc_tb: object) -> bool:
+        """No-op exit - returns immediately.
+
+        Args:
+            exc_type: Exception type (ignored)
+            exc_val: Exception value (ignored)
+            exc_tb: Exception traceback (ignored)
+
+        Returns:
+            False (does not suppress exceptions)
+        """
+        return False
+
+
+class NullTimer:
+    """No-op timer implementing the Null Object Pattern.
+
+    Provides zero-overhead instrumentation when profiling is disabled.
+    All methods are no-ops that optimize away at runtime.
+
+    Performance: ~20-30 nanoseconds overhead per measure() call.
+    This is negligible compared to any actual work being measured.
+
+    Use Cases:
+        - Production deployments (profiling disabled)
+        - Performance-critical paths
+        - Testing without timing dependencies
+
+    Example:
+        # Use global singleton for zero allocation overhead
+        tracker = PoseTracker(timer=NULL_TIMER)
+
+        # No overhead - measure() call optimizes to nothing
+        with tracker.timer.measure("operation"):
+            do_work()
+    """
+
+    __slots__ = ()
+
+    def measure(self, name: str) -> AbstractContextManager[None]:
+        """Return a no-op context manager.
+
+        This method does nothing and is optimized away by the Python interpreter.
+        The context manager protocol (__enter__/__exit__) has minimal overhead.
+
+        Args:
+            name: Operation name (unused in no-op implementation)
+
+        Returns:
+            Singleton null context manager
+        """
+        del name  # Intentionally unused - satisfies Timer protocol
+        return _NULL_CONTEXT
+
+    def get_metrics(self) -> dict[str, float]:
+        """Return empty metrics dictionary.
+
+        Returns:
+            Empty dictionary (no metrics collected)
+        """
+        return {}
+
+
+# Singleton instances for global reuse
+# Use these instead of creating new instances to avoid allocation overhead
+_NULL_CONTEXT = _NullContext()
+NULL_TIMER: Timer = NullTimer()
+
+
+class _MeasureContext(AbstractContextManager[None]):
+    """Optimized context manager for active timing.
+
+    Uses __slots__ for memory efficiency and perf_counter for precision.
+    Accumulates durations for repeated measurements of the same operation.
+    """
+
+    __slots__ = ("_metrics", "_name", "_start")
+
+    def __init__(self, metrics: dict[str, float], name: str) -> None:
+        """Initialize measurement context.
+
+        Args:
+            metrics: Dictionary to store timing results
+            name: Name of the operation being measured
+        """
+        self._metrics = metrics
+        self._name = name
+        self._start = 0.0
+
+    def __enter__(self) -> None:
+        """Start timing measurement using high-precision counter."""
+        self._start = time.perf_counter()
+        return None
+
+    def __exit__(self, exc_type: object, exc_val: object, exc_tb: object) -> bool:
+        """Complete timing measurement and accumulate duration.
+
+        Accumulates duration if the same operation is measured multiple times.
+        This is useful for measuring operations in loops.
+
+        Args:
+            exc_type: Exception type (if any)
+            exc_val: Exception value (if any)
+            exc_tb: Exception traceback (if any)
+
+        Returns:
+            False (does not suppress exceptions)
+        """
+        duration = time.perf_counter() - self._start
+        # Accumulate for repeated measurements (e.g., in loops)
+        self._metrics[self._name] = self._metrics.get(self._name, 0.0) + duration
+        return False
+
+
+class PerformanceTimer:
+    """High-precision timer for tracking execution duration of named steps.
+
+    Uses time.perf_counter() for high-resolution monotonic timing.
+    Suitable for development, profiling, and performance analysis.
+
+    Accumulates timing data for repeated measurements of the same operation,
+    making it suitable for measuring operations in loops.
+
+    Precision: ~1 microsecond on most platforms
+    Overhead: ~200 nanoseconds per measurement
+
+    Example:
+        timer = PerformanceTimer()
+
+        # Measure single operation
+        with timer.measure("video_initialization"):
+            initialize_video(path)
+
+        # Measure in loop (accumulates)
+        for frame in frames:
+            with timer.measure("pose_tracking"):
+                track_pose(frame)
+
+        metrics = timer.get_metrics()
+        print(f"Total pose tracking: {metrics['pose_tracking']:.3f}s")
+    """
+
+    __slots__ = ("metrics",)
+
+    def __init__(self) -> None:
+        """Initialize timer with empty metrics dictionary."""
+        self.metrics: dict[str, float] = {}
+
+    def measure(self, name: str) -> AbstractContextManager[None]:
+        """Context manager to measure execution time of a block.
+
+        Uses perf_counter() for high-resolution monotonic timing.
+        More precise and reliable than time.time() for performance measurement.
+
+        Args:
+            name: Name of the step being measured (e.g., "pose_tracking")
+
+        Returns:
+            Context manager that measures execution time
+
+        Note:
+            perf_counter() is monotonic - not affected by system clock adjustments.
+            Repeated measurements of the same operation name will accumulate.
+        """
+        return _MeasureContext(self.metrics, name)
+
+    def get_metrics(self) -> dict[str, float]:
+        """Get collected timing metrics in seconds.
+
+        Returns:
+            A copy of the metrics dictionary to prevent external modification.
+        """
+        return self.metrics.copy()

kinemotion/core/types.py

@@ -0,0 +1,42 @@
+"""Central type definitions for the kinemotion package.
+
+This module provides all type aliases used throughout the codebase to ensure
+consistent typing and better IDE support.
+"""
+
+from typing import Any, TypeAlias
+
+import numpy as np
+from numpy.typing import NDArray
+
+# NumPy array types for various use cases
+FloatArray: TypeAlias = NDArray[np.floating[Any]]
+Float64Array: TypeAlias = NDArray[np.float64]
+IntArray: TypeAlias = NDArray[np.integer[Any]]
+UInt8Array: TypeAlias = NDArray[np.uint8]
+BoolArray: TypeAlias = NDArray[np.bool_]
+
+# MediaPipe landmark types
+# Using dict-based representation since MediaPipe lacks proper type stubs
+LandmarkCoord: TypeAlias = tuple[float, float, float]  # (x, y, visibility)
+LandmarkFrame: TypeAlias = dict[str, LandmarkCoord] | None
+LandmarkSequence: TypeAlias = list[LandmarkFrame]
+
+# Metrics dictionary type
+# Uses Any because metrics can contain:
+# - Simple values: float, int, str
+# - Nested dicts: e.g. "triple_extension" contains angle data
+# - Wrapper structures: e.g. {"data": {...actual metrics...}}
+MetricsDict: TypeAlias = dict[str, Any]
+
+__all__ = [
+    "FloatArray",
+    "Float64Array",
+    "IntArray",
+    "UInt8Array",
+    "BoolArray",
+    "LandmarkCoord",
+    "LandmarkFrame",
+    "LandmarkSequence",
+    "MetricsDict",
+]

kinemotion/core/validation.py

@@ -0,0 +1,201 @@
+"""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 across athlete performance levels.
+
+    Defines nested ranges for validating metrics: absolute limits mark impossible
+    values (likely data corruption), while performance-level ranges assess whether
+    results are typical for an athlete's training background.
+
+    Bounds are ordered: absolute_min < practical_min < recreational_min < elite_min
+    and elite_max < recreational_max < absolute_max (symmetric about typical values).
+
+    Attributes:
+        absolute_min: Absolute minimum (error threshold, marks data corruption)
+        practical_min: Minimum for untrained/elderly athletes
+        recreational_min: Minimum for recreational athletes (moderate activity)
+        recreational_max: Maximum for recreational athletes
+        elite_min: Minimum for elite athletes (competitive level)
+        elite_max: Maximum for elite athletes
+        absolute_max: Absolute maximum (error threshold, marks data corruption)
+        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