kinemotion 0.47.1__py3-none-any.whl → 0.47.3__py3-none-any.whl

kinemotion/cmj/kinematics.py

@@ -147,133 +147,219 @@ class CMJMetrics:
         return result
 
 
-def calculate_cmj_metrics(
+def _calculate_scale_factor(
     positions: NDArray[np.float64],
-    velocities: NDArray[np.float64],
-    standing_start_frame: float | None,
-    lowest_point_frame: float,
     takeoff_frame: float,
     landing_frame: float,
-    fps: float,
-    tracking_method: str = "foot",
-) -> CMJMetrics:
-    """Calculate all CMJ metrics from detected phases.
+    jump_height: float,
+) -> float:
+    """Calculate meters per normalized unit scaling factor from flight phase.
 
     Args:
-        positions: Array of vertical positions (normalized coordinates)
-        velocities: Array of vertical velocities
-        standing_start_frame: Frame where countermovement begins (fractional)
-        lowest_point_frame: Frame at lowest point (fractional)
-        takeoff_frame: Frame at takeoff (fractional)
-        landing_frame: Frame at landing (fractional)
-        fps: Video frames per second
-        tracking_method: Tracking method used ("foot" or "com")
+        positions: Array of vertical positions
+        takeoff_frame: Takeoff frame index
+        landing_frame: Landing frame index
+        jump_height: Calculated jump height in meters
 
     Returns:
-        CMJMetrics object with all calculated metrics.
+        Scale factor (meters per normalized unit)
     """
-    # Calculate flight time from takeoff to landing
-    flight_time = (landing_frame - takeoff_frame) / fps
-
-    # Calculate jump height from flight time using kinematic formula
-    # h = g * t^2 / 8 (where t is total flight time)
-    g = 9.81  # gravity in m/s^2
-    jump_height = (g * flight_time**2) / 8
-
-    # Determine scaling factor (meters per normalized unit)
-    # We use the flight phase displacement in normalized units compared to
-    # kinematic jump height
     flight_start_idx = int(takeoff_frame)
     flight_end_idx = int(landing_frame)
     flight_positions = positions[flight_start_idx:flight_end_idx]
 
-    scale_factor = 0.0
-    if len(flight_positions) > 0:
-        # Peak height is minimum y value (highest point in frame)
-        peak_flight_pos = np.min(flight_positions)
-        takeoff_pos = positions[flight_start_idx]
-        # Displacement is upward (takeoff_pos - peak_pos) because y decreases upward
-        flight_displacement = takeoff_pos - peak_flight_pos
+    if len(flight_positions) == 0:
+        return 0.0
 
-        if flight_displacement > 0.001:  # Avoid division by zero or noise
-            scale_factor = jump_height / flight_displacement
+    peak_flight_pos = np.min(flight_positions)
+    takeoff_pos = positions[flight_start_idx]
+    flight_displacement = takeoff_pos - peak_flight_pos
+
+    if flight_displacement > 0.001:
+        return jump_height / flight_displacement
+    return 0.0
 
-    # Calculate countermovement depth
-    if standing_start_frame is not None:
-        standing_position = positions[int(standing_start_frame)]
-    else:
-        # Use position at start of recording if standing not detected
-        standing_position = positions[0]
 
+def _calculate_countermovement_depth(
+    positions: NDArray[np.float64],
+    standing_start_frame: float | None,
+    lowest_point_frame: float,
+    scale_factor: float,
+) -> float:
+    """Calculate countermovement depth in meters.
+
+    Args:
+        positions: Array of vertical positions
+        standing_start_frame: Standing phase end frame (or None)
+        lowest_point_frame: Lowest point frame index
+        scale_factor: Meters per normalized unit
+
+    Returns:
+        Countermovement depth in meters
+    """
+    standing_position = (
+        positions[int(standing_start_frame)]
+        if standing_start_frame is not None
+        else positions[0]
+    )
     lowest_position = positions[int(lowest_point_frame)]
-    # Depth in normalized units
     depth_normalized = abs(standing_position - lowest_position)
-    # Convert to meters
-    countermovement_depth = depth_normalized * scale_factor
+    return depth_normalized * scale_factor
+
+
+def _calculate_phase_durations(
+    standing_start_frame: float | None,
+    lowest_point_frame: float,
+    takeoff_frame: float,
+    fps: float,
+) -> tuple[float, float, float]:
+    """Calculate phase durations in seconds.
+
+    Args:
+        standing_start_frame: Standing phase end frame (or None)
+        lowest_point_frame: Lowest point frame index
+        takeoff_frame: Takeoff frame index
+        fps: Frames per second
 
-    # Calculate phase durations
+    Returns:
+        Tuple of (eccentric_duration, concentric_duration, total_movement_time)
+    """
     if standing_start_frame is not None:
         eccentric_duration = (lowest_point_frame - standing_start_frame) / fps
         total_movement_time = (takeoff_frame - standing_start_frame) / fps
     else:
-        # If no standing phase detected, measure from start
         eccentric_duration = lowest_point_frame / fps
         total_movement_time = takeoff_frame / fps
 
     concentric_duration = (takeoff_frame - lowest_point_frame) / fps
+    return eccentric_duration, concentric_duration, total_movement_time
 
-    # Velocity scaling factor: units/frame -> meters/second
-    # v_m_s = v_units_frame * fps * scale_factor
-    velocity_scale = scale_factor * fps
 
-    # Calculate peak velocities
-    # Eccentric phase: Downward motion = Positive velocity in image coords
-    if standing_start_frame is not None:
-        eccentric_start_idx = int(standing_start_frame)
-    else:
-        eccentric_start_idx = 0
+def _calculate_peak_velocities(
+    velocities: NDArray[np.float64],
+    standing_start_frame: float | None,
+    lowest_point_frame: float,
+    takeoff_frame: float,
+    velocity_scale: float,
+) -> tuple[float, float]:
+    """Calculate peak eccentric and concentric velocities.
 
+    Args:
+        velocities: Array of velocities
+        standing_start_frame: Standing phase end frame (or None)
+        lowest_point_frame: Lowest point frame index
+        takeoff_frame: Takeoff frame index
+        velocity_scale: Velocity scaling factor
+
+    Returns:
+        Tuple of (peak_eccentric_velocity, peak_concentric_velocity)
+    """
+    eccentric_start_idx = int(standing_start_frame) if standing_start_frame else 0
     eccentric_end_idx = int(lowest_point_frame)
     eccentric_velocities = velocities[eccentric_start_idx:eccentric_end_idx]
 
+    peak_eccentric_velocity = 0.0
     if len(eccentric_velocities) > 0:
-        # Peak eccentric velocity is maximum positive value (fastest downward)
-        # We take max and ensure it's positive (it should be)
-        peak_eccentric_velocity = float(np.max(eccentric_velocities)) * velocity_scale
-        # If max is negative (weird), it means no downward motion detected
-        if peak_eccentric_velocity < 0:
-            peak_eccentric_velocity = 0.0
-    else:
-        peak_eccentric_velocity = 0.0
+        peak = float(np.max(eccentric_velocities)) * velocity_scale
+        peak_eccentric_velocity = max(0.0, peak)
 
-    # Concentric phase: Upward motion = Negative velocity in image coords
     concentric_start_idx = int(lowest_point_frame)
     concentric_end_idx = int(takeoff_frame)
     concentric_velocities = velocities[concentric_start_idx:concentric_end_idx]
 
+    peak_concentric_velocity = 0.0
     if len(concentric_velocities) > 0:
-        # Peak concentric velocity is minimum value (most negative = fastest upward)
-        # We take abs to report magnitude
         peak_concentric_velocity = (
             abs(float(np.min(concentric_velocities))) * velocity_scale
         )
-    else:
-        peak_concentric_velocity = 0.0
 
-    # Estimate transition time (amortization phase)
-    # Look for period around lowest point where velocity is near zero
-    transition_threshold = 0.005  # Very low velocity threshold
-    search_window = int(fps * 0.1)  # Search within ±100ms
+    return peak_eccentric_velocity, peak_concentric_velocity
+
+
+def _calculate_transition_time(
+    velocities: NDArray[np.float64],
+    lowest_point_frame: float,
+    fps: float,
+) -> float | None:
+    """Calculate transition/amortization time around lowest point.
+
+    Args:
+        velocities: Array of velocities
+        lowest_point_frame: Lowest point frame index
+        fps: Frames per second
+
+    Returns:
+        Transition time in seconds, or None if no transition detected
+    """
+    transition_threshold = 0.005
+    search_window = int(fps * 0.1)
 
     transition_start_idx = max(0, int(lowest_point_frame) - search_window)
     transition_end_idx = min(len(velocities), int(lowest_point_frame) + search_window)
 
-    transition_frames = 0
-    for i in range(transition_start_idx, transition_end_idx):
-        if abs(velocities[i]) < transition_threshold:
-            transition_frames += 1
+    transition_frames = sum(
+        1
+        for i in range(transition_start_idx, transition_end_idx)
+        if abs(velocities[i]) < transition_threshold
+    )
+
+    return transition_frames / fps if transition_frames > 0 else None
+
+
+def calculate_cmj_metrics(
+    positions: NDArray[np.float64],
+    velocities: NDArray[np.float64],
+    standing_start_frame: float | None,
+    lowest_point_frame: float,
+    takeoff_frame: float,
+    landing_frame: float,
+    fps: float,
+    tracking_method: str = "foot",
+) -> CMJMetrics:
+    """Calculate all CMJ metrics from detected phases.
+
+    Args:
+        positions: Array of vertical positions (normalized coordinates)
+        velocities: Array of vertical velocities
+        standing_start_frame: Frame where countermovement begins (fractional)
+        lowest_point_frame: Frame at lowest point (fractional)
+        takeoff_frame: Frame at takeoff (fractional)
+        landing_frame: Frame at landing (fractional)
+        fps: Video frames per second
+        tracking_method: Tracking method used ("foot" or "com")
+
+    Returns:
+        CMJMetrics object with all calculated metrics.
+    """
+    # Calculate jump height from flight time using kinematic formula: h = g*t²/8
+    g = 9.81
+    flight_time = (landing_frame - takeoff_frame) / fps
+    jump_height = (g * flight_time**2) / 8
+
+    # Calculate scaling factor and derived metrics
+    scale_factor = _calculate_scale_factor(
+        positions, takeoff_frame, landing_frame, jump_height
+    )
+    countermovement_depth = _calculate_countermovement_depth(
+        positions, standing_start_frame, lowest_point_frame, scale_factor
+    )
+
+    eccentric_duration, concentric_duration, total_movement_time = (
+        _calculate_phase_durations(
+            standing_start_frame, lowest_point_frame, takeoff_frame, fps
+        )
+    )
+
+    velocity_scale = scale_factor * fps
+    peak_eccentric_velocity, peak_concentric_velocity = _calculate_peak_velocities(
+        velocities,
+        standing_start_frame,
+        lowest_point_frame,
+        takeoff_frame,
+        velocity_scale,
+    )
 
-    transition_time = transition_frames / fps if transition_frames > 0 else None
+    transition_time = _calculate_transition_time(velocities, lowest_point_frame, fps)
 
     return CMJMetrics(
         jump_height=jump_height,

kinemotion/cmj/metrics_validator.py

@@ -449,7 +449,7 @@ class CMJMetricsValidator(MetricsValidator):
         # Convert ms to seconds
         flight_time = flight_time_ms / 1000.0
 
-        # h = g * t^2 / 8
+        # Calculate expected height using kinematic formula: h = g*t²/8
         g = 9.81
         expected_height = (g * flight_time**2) / 8
         error_pct = abs(jump_height - expected_height) / expected_height
@@ -483,7 +483,7 @@ class CMJMetricsValidator(MetricsValidator):
         if velocity is None or jump_height is None:
             return
 
-        # h = v^2 / (2*g)
+        # Calculate expected velocity using kinematic formula: v² = 2*g*h
         g = 9.81
         expected_velocity = (2 * g * jump_height) ** 0.5
         error_pct = abs(velocity - expected_velocity) / expected_velocity

kinemotion/core/__init__.py

@@ -24,9 +24,7 @@ from .smoothing import (
 )
 from .timing import (
     NULL_TIMER,
-    CompositeTimer,
     NullTimer,
-    OpenTelemetryTimer,
     PerformanceTimer,
     Timer,
 )
@@ -59,8 +57,6 @@ __all__ = [
     "Timer",
     "NullTimer",
     "NULL_TIMER",
-    "CompositeTimer",
-    "OpenTelemetryTimer",
     # Video I/O
     "VideoProcessor",
 ]

kinemotion/core/timing.py

@@ -26,43 +26,9 @@ Example:
 """
 
 import time
-from contextlib import AbstractContextManager, ExitStack, contextmanager
+from contextlib import AbstractContextManager
 from typing import Protocol, runtime_checkable
 
-# OpenTelemetry related imports, guarded by try-except for optional dependency
-_trace_module = None  # This will hold the actual 'trace' module if imported
-_otel_tracer_class = None  # This will hold the actual 'Tracer' class if imported
-
-try:
-    import opentelemetry.trace as _trace_module_import  # Import the module directly
-
-    _otel_tracer_class = (
-        _trace_module_import.Tracer
-    )  # Get the Tracer class from the module
-    _trace_module = (
-        _trace_module_import  # Expose the trace module globally after successful import
-    )
-except ImportError:
-    pass  # No OTel, so these remain None
-
-# Now define the global/module-level variables used elsewhere
-# Conditionally expose 'trace' and 'Tracer' aliases
-trace = _trace_module  # This will be the actual module or None
-
-
-class Tracer:  # Dummy for type hints if actual Tracer is not available
-    pass
-
-
-if _otel_tracer_class:
-    Tracer = _otel_tracer_class  # type: ignore # Override dummy if actual Tracer is available
-
-# This _OPENTELEMETRY_AVAILABLE variable is assigned only once,
-# after the try-except block
-_OPENTELEMETRY_AVAILABLE = bool(
-    _otel_tracer_class
-)  # True if Tracer class was successfully loaded
-
 
 @runtime_checkable
 class Timer(Protocol):
@@ -152,11 +118,12 @@ class NullTimer:
         The context manager protocol (__enter__/__exit__) has minimal overhead.
 
         Args:
-            name: Ignored - kept for protocol compatibility
+            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]:
@@ -278,105 +245,3 @@ class PerformanceTimer:
             A copy of the metrics dictionary to prevent external modification.
         """
         return self.metrics.copy()
-
-
-@contextmanager
-def _composite_context_manager(contexts: list[AbstractContextManager[None]]):
-    """Helper to combine multiple context managers into one.
-
-    Uses ExitStack to manage entering and exiting multiple contexts transparently.
-    """
-    with ExitStack() as stack:
-        for ctx in contexts:
-            stack.enter_context(ctx)
-        yield
-
-
-class CompositeTimer:
-    """Timer that delegates measurements to multiple underlying timers.
-
-    Useful for enabling both local performance timing (for JSON output)
-    and distributed tracing (OpenTelemetry) simultaneously.
-    """
-
-    __slots__ = ("timers",)
-
-    def __init__(self, timers: list[Timer]) -> None:
-        """Initialize composite timer.
-
-        Args:
-            timers: List of timer instances to delegate to
-        """
-        self.timers = timers
-
-    def measure(self, name: str) -> AbstractContextManager[None]:
-        """Measure using all underlying timers.
-
-        Args:
-            name: Name of the operation
-
-        Returns:
-            Context manager that manages all underlying timers
-        """
-        contexts = [timer.measure(name) for timer in self.timers]
-        return _composite_context_manager(contexts)
-
-    def get_metrics(self) -> dict[str, float]:
-        """Get combined metrics from all timers.
-
-        Returns:
-            Merged dictionary of metrics
-        """
-        metrics = {}
-        for timer in self.timers:
-            metrics.update(timer.get_metrics())
-        return metrics
-
-
-class OpenTelemetryTimer:
-    """Timer implementation that creates OpenTelemetry spans.
-
-    Maps 'measure' calls to OTel spans. Requires opentelemetry-api installed.
-    """
-
-    __slots__ = ("tracer",)
-
-    def __init__(self, tracer: Tracer | None = None) -> None:
-        """Initialize OTel timer.
-
-        Args:
-            tracer: Optional OTel tracer. If None, gets tracer for module name.
-        """
-        if not _OPENTELEMETRY_AVAILABLE:
-            self.tracer = None  # Always initialize self.tracer for __slots__
-            return
-
-        if trace is not None:
-            self.tracer = tracer or trace.get_tracer(__name__)
-        else:
-            # This branch should ideally not be reached if _OPENTELEMETRY_AVAILABLE
-            # is True but trace is None (meaning import succeeded but trace was not what
-            # expected). Defensive programming: ensure self.tracer is set.
-            self.tracer = None
-
-    def measure(self, name: str) -> AbstractContextManager[None]:
-        """Start an OpenTelemetry span.
-
-        Args:
-            name: Name of the span
-
-        Returns:
-            Span context manager (compatible with AbstractContextManager)
-        """
-        if not _OPENTELEMETRY_AVAILABLE or self.tracer is None:
-            return _NULL_CONTEXT  # Return the no-op context
-
-        return self.tracer.start_as_current_span(name)
-
-    def get_metrics(self) -> dict[str, float]:
-        """Return empty metrics (OTel handles export asynchronously).
-
-        Returns:
-            Empty dictionary
-        """
-        return {}