kinemotion 0.76.3__py3-none-any.whl → 1.0.0__py3-none-any.whl

kinemotion/__init__.py

@@ -1,26 +1,17 @@
-"""Kinemotion: Video-based kinematic analysis for athletic performance.
-
-Supports Counter Movement Jump (CMJ), Drop Jump, and Squat Jump (SJ) analysis
-using MediaPipe pose estimation.
-"""
+"""Kinemotion: Video-based kinematic analysis for athletic performance."""
 
 from .api import (
     CMJVideoConfig,
     CMJVideoResult,
     DropJumpVideoConfig,
     DropJumpVideoResult,
-    SJVideoConfig,
-    SJVideoResult,
     process_cmj_video,
     process_cmj_videos_bulk,
     process_dropjump_video,
     process_dropjump_videos_bulk,
-    process_sj_video,
-    process_sj_videos_bulk,
 )
-from .countermovement_jump.kinematics import CMJMetrics
-from .drop_jump.kinematics import DropJumpMetrics
-from .squat_jump.kinematics import SJMetrics
+from .cmj.kinematics import CMJMetrics
+from .dropjump.kinematics import DropJumpMetrics
 
 # Get version from package metadata (set in pyproject.toml)
 try:
@@ -44,11 +35,5 @@ __all__ = [
     "CMJVideoConfig",
     "CMJVideoResult",
     "CMJMetrics",
-    # Squat Jump API
-    "process_sj_video",
-    "process_sj_videos_bulk",
-    "SJVideoConfig",
-    "SJVideoResult",
-    "SJMetrics",
     "__version__",
 ]

kinemotion/api.py

@@ -1,27 +1,26 @@
 """Public API for programmatic use of kinemotion analysis.
 
-This module provides a unified interface for drop jump, CMJ, and Squat Jump analysis.
+This module provides a unified interface for both drop jump and CMJ video analysis.
 The actual implementations have been moved to their respective submodules:
-- Drop jump: kinemotion.drop_jump.api
-- CMJ: kinemotion.countermovement_jump.api
-- Squat Jump: kinemotion.squat_jump.api
+- Drop jump: kinemotion.dropjump.api
+- CMJ: kinemotion.cmj.api
 
 """
 
 # CMJ API
-from .countermovement_jump.api import (
+from .cmj.api import (
     AnalysisOverrides as CMJAnalysisOverrides,
 )
-from .countermovement_jump.api import (
+from .cmj.api import (
     CMJVideoConfig,
     CMJVideoResult,
     process_cmj_video,
     process_cmj_videos_bulk,
 )
-from .countermovement_jump.kinematics import CMJMetrics
+from .cmj.kinematics import CMJMetrics
 
 # Drop jump API
-from .drop_jump.api import (
+from .dropjump.api import (
     AnalysisOverrides,
     DropJumpVideoConfig,
     DropJumpVideoResult,
@@ -29,18 +28,6 @@ from .drop_jump.api import (
     process_dropjump_videos_bulk,
 )
 
-# Squat Jump API
-from .squat_jump.api import (
-    AnalysisOverrides as SJAnalysisOverrides,
-)
-from .squat_jump.api import (
-    SJVideoConfig,
-    SJVideoResult,
-    process_sj_video,
-    process_sj_videos_bulk,
-)
-from .squat_jump.kinematics import SJMetrics
-
 __all__ = [
     # Drop jump
     "AnalysisOverrides",
@@ -55,11 +42,4 @@ __all__ = [
     "CMJVideoResult",
     "process_cmj_video",
     "process_cmj_videos_bulk",
-    # Squat Jump
-    "SJAnalysisOverrides",
-    "SJMetrics",
-    "SJVideoConfig",
-    "SJVideoResult",
-    "process_sj_video",
-    "process_sj_videos_bulk",
 ]

kinemotion/cli.py

@@ -2,9 +2,8 @@
 
 import click
 
-from .countermovement_jump.cli import cmj_analyze
-from .drop_jump.cli import dropjump_analyze
-from .squat_jump.cli import sj_analyze
+from .cmj.cli import cmj_analyze
+from .dropjump.cli import dropjump_analyze
 
 
 @click.group()
@@ -18,7 +17,6 @@ def cli() -> None:  # type: ignore[return]
 # Type ignore needed because @click.group() transforms cli into a click.Group
 cli.add_command(dropjump_analyze)  # type: ignore[attr-defined]
 cli.add_command(cmj_analyze)  # type: ignore[attr-defined]
-cli.add_command(sj_analyze)  # type: ignore[attr-defined]
 
 
 if __name__ == "__main__":

kinemotion/{countermovement_jump → cmj}/analysis.py

@@ -8,7 +8,7 @@ from scipy.signal import savgol_filter
 from ..core.experimental import unused
 from ..core.smoothing import compute_acceleration_from_derivative
 from ..core.timing import NULL_TIMER, Timer
-from ..core.types import HIP_KEYS, FloatArray
+from ..core.types import FloatArray
 
 
 def compute_signed_velocity(
@@ -55,7 +55,147 @@ class CMJPhase(Enum):
     UNKNOWN = "unknown"
 
 
-def _find_cmj_takeoff_from_velocity_peak(
+@unused(
+    reason="Alternative implementation not called by pipeline",
+    since="0.34.0",
+)
+def find_standing_phase(
+    positions: FloatArray,
+    velocities: FloatArray,
+    fps: float,
+    min_standing_duration: float = 0.5,
+    velocity_threshold: float = 0.01,
+) -> int | None:
+    """
+    Find the end of standing phase (start of countermovement).
+
+    Looks for a period of low velocity (standing) followed by consistent
+    downward motion.
+
+    Args:
+        positions: Array of vertical positions (normalized 0-1)
+        velocities: Array of vertical velocities
+        fps: Video frame rate
+        min_standing_duration: Minimum standing duration in seconds (default: 0.5s)
+        velocity_threshold: Velocity threshold for standing detection
+
+    Returns:
+        Frame index where countermovement begins, or None if not detected.
+    """
+    min_standing_frames = int(fps * min_standing_duration)
+
+    if len(positions) < min_standing_frames:
+        return None
+
+    # Find periods of low velocity (standing)
+    is_standing = np.abs(velocities) < velocity_threshold
+
+    # Look for first sustained standing period
+    standing_count = 0
+    standing_end = None
+
+    for i in range(len(is_standing)):
+        if is_standing[i]:
+            standing_count += 1
+            if standing_count >= min_standing_frames:
+                standing_end = i
+        else:
+            if standing_end is not None:
+                # Found end of standing phase
+                return standing_end
+            standing_count = 0
+
+    return None
+
+
+@unused(
+    reason="Alternative implementation not called by pipeline",
+    since="0.34.0",
+)
+def find_countermovement_start(
+    velocities: FloatArray,
+    countermovement_threshold: float = 0.015,
+    min_eccentric_frames: int = 3,
+    standing_start: int | None = None,
+) -> int | None:
+    """
+    Find the start of countermovement (eccentric phase).
+
+    Detects when velocity becomes consistently positive (downward motion in
+    normalized coords).
+
+    Args:
+        velocities: Array of SIGNED vertical velocities
+        countermovement_threshold: Velocity threshold for detecting downward
+            motion (POSITIVE)
+        min_eccentric_frames: Minimum consecutive frames of downward motion
+        standing_start: Optional frame where standing phase ended
+
+    Returns:
+        Frame index where countermovement begins, or None if not detected.
+    """
+    start_frame = standing_start if standing_start is not None else 0
+
+    # Look for sustained downward velocity (POSITIVE in normalized coords)
+    is_downward = velocities[start_frame:] > countermovement_threshold
+    consecutive_count = 0
+
+    for i in range(len(is_downward)):
+        if is_downward[i]:
+            consecutive_count += 1
+            if consecutive_count >= min_eccentric_frames:
+                # Found start of eccentric phase
+                return start_frame + i - consecutive_count + 1
+        else:
+            consecutive_count = 0
+
+    return None
+
+
+def find_lowest_point(
+    positions: FloatArray,
+    velocities: FloatArray,
+    min_search_frame: int = 80,
+) -> int:
+    """
+    Find the lowest point of countermovement (transition from eccentric to concentric).
+
+    The lowest point occurs BEFORE the peak height (the jump apex). It's where
+    velocity crosses from positive (downward/squatting) to negative (upward/jumping).
+
+    Args:
+        positions: Array of vertical positions (higher value = lower in video)
+        velocities: Array of SIGNED vertical velocities (positive=down, negative=up)
+        min_search_frame: Minimum frame to start searching (default: frame 80)
+
+    Returns:
+        Frame index of lowest point.
+    """
+    # First, find the peak height (minimum y value = highest jump point)
+    peak_height_frame = int(np.argmin(positions))
+
+    # Lowest point MUST be before peak height
+    # Search from min_search_frame to peak_height_frame
+    start_frame = min_search_frame
+    end_frame = peak_height_frame
+
+    if end_frame <= start_frame:
+        start_frame = int(len(positions) * 0.3)
+        end_frame = int(len(positions) * 0.7)
+
+    search_positions = positions[start_frame:end_frame]
+
+    if len(search_positions) == 0:
+        return start_frame
+
+    # Find maximum position value in this range (lowest point in video)
+    lowest_idx = int(np.argmax(search_positions))
+    lowest_frame = start_frame + lowest_idx
+
+    return lowest_frame
+
+
+def find_cmj_takeoff_from_velocity_peak(
     positions: FloatArray,
     velocities: FloatArray,
     lowest_point_frame: int,
@@ -92,7 +232,7 @@ def _find_cmj_takeoff_from_velocity_peak(
     return float(takeoff_frame)
 
 
-def _find_cmj_landing_from_position_peak(
+def find_cmj_landing_from_position_peak(
     positions: FloatArray,
     velocities: FloatArray,
     accelerations: FloatArray,
@@ -150,7 +290,7 @@ def _find_cmj_landing_from_position_peak(
     reason="Experimental alternative superseded by backward search algorithm",
     since="0.34.0",
 )
-def _find_interpolated_takeoff_landing(
+def find_interpolated_takeoff_landing(
     positions: FloatArray,
     velocities: FloatArray,
     lowest_point_frame: int,
@@ -183,19 +323,19 @@ def _find_interpolated_takeoff_landing(
     )
 
     # Find takeoff using peak velocity method (CMJ-specific)
-    takeoff_frame = _find_cmj_takeoff_from_velocity_peak(
+    takeoff_frame = find_cmj_takeoff_from_velocity_peak(
         positions, velocities, lowest_point_frame, fps
     )
 
     # Find landing using position peak and impact detection
-    landing_frame = _find_cmj_landing_from_position_peak(
+    landing_frame = find_cmj_landing_from_position_peak(
         positions, velocities, accelerations, int(takeoff_frame), fps
     )
 
     return (takeoff_frame, landing_frame)
 
 
-def _find_takeoff_frame(
+def find_takeoff_frame(
     velocities: FloatArray,
     peak_height_frame: int,
     fps: float,
@@ -258,7 +398,7 @@ def _find_takeoff_frame(
     return float(peak_vel_frame)
 
 
-def _find_lowest_frame(
+def find_lowest_frame(
     velocities: FloatArray, positions: FloatArray, takeoff_frame: float, fps: float
 ) -> float:
     """Find lowest point frame before takeoff."""
@@ -327,7 +467,7 @@ def _find_landing_impact(
     return float(landing_frame)
 
 
-def _find_landing_frame(
+def find_landing_frame(
     accelerations: FloatArray,
     velocities: FloatArray,
     peak_height_frame: int,
@@ -363,10 +503,12 @@ def compute_average_hip_position(
     Returns:
         (x, y) average hip position in normalized coordinates
     """
+    hip_keys = ["left_hip", "right_hip"]
+
     x_positions: list[float] = []
     y_positions: list[float] = []
 
-    for key in HIP_KEYS:
+    for key in hip_keys:
         if key in landmarks:
             x, y, visibility = landmarks[key]
             if visibility > 0.5:  # Only use visible landmarks
@@ -379,7 +521,7 @@ def compute_average_hip_position(
     return (float(np.mean(x_positions)), float(np.mean(y_positions)))
 
 
-def _find_standing_end(
+def find_standing_end(
     velocities: FloatArray,
     lowest_point: float,
     _positions: FloatArray | None = None,
@@ -490,12 +632,12 @@ def detect_cmj_phases(
 
     # Step 2-4: Find all phases using helper functions
     with timer.measure("cmj_find_takeoff"):
-        takeoff_frame = _find_takeoff_frame(
+        takeoff_frame = find_takeoff_frame(
             velocities, peak_height_frame, fps, accelerations=accelerations
         )
 
     with timer.measure("cmj_find_lowest_point"):
-        lowest_point = _find_lowest_frame(velocities, positions, takeoff_frame, fps)
+        lowest_point = find_lowest_frame(velocities, positions, takeoff_frame, fps)
 
     # Determine landing frame
     with timer.measure("cmj_find_landing"):
@@ -509,7 +651,7 @@ def detect_cmj_phases(
             )
             # We still reference peak_height_frame from Hips, as Feet peak
             # might be different/noisy but generally they align in time.
-            landing_frame = _find_landing_frame(
+            landing_frame = find_landing_frame(
                 landing_accelerations,
                 landing_velocities,
                 peak_height_frame,
@@ -517,7 +659,7 @@ def detect_cmj_phases(
             )
         else:
             # Use primary signal (Hips)
-            landing_frame = _find_landing_frame(
+            landing_frame = find_landing_frame(
                 accelerations,
                 velocities,
                 peak_height_frame,
@@ -525,6 +667,6 @@ def detect_cmj_phases(
             )
 
     with timer.measure("cmj_find_standing_end"):
-        standing_end = _find_standing_end(velocities, lowest_point, positions, accelerations)
+        standing_end = find_standing_end(velocities, lowest_point, positions, accelerations)
 
     return (standing_end, lowest_point, takeoff_frame, landing_frame)

kinemotion/{countermovement_jump → cmj}/api.py

@@ -262,15 +262,13 @@ def _get_tuned_parameters(
     with timer.measure("parameter_auto_tuning"):
         characteristics = analyze_video_sample(landmarks_sequence, video.fps, video.frame_count)
         params = auto_tune_parameters(characteristics, quality_preset)
-
-        if overrides:
-            params = apply_expert_overrides(
-                params,
-                overrides.smoothing_window,
-                overrides.velocity_threshold,
-                overrides.min_contact_frames,
-                overrides.visibility_threshold,
-            )
+        params = apply_expert_overrides(
+            params,
+            overrides.smoothing_window if overrides else None,
+            overrides.velocity_threshold if overrides else None,
+            overrides.min_contact_frames if overrides else None,
+            overrides.visibility_threshold if overrides else None,
+        )
 
         if verbose:
             print_verbose_parameters(video, characteristics, quality_preset, params)
@@ -393,24 +391,6 @@ class CMJVideoConfig:
     overrides: AnalysisOverrides | None = None
     detection_confidence: float | None = None
     tracking_confidence: float | None = None
-    verbose: bool = False
-    timer: Timer | None = None
-    pose_tracker: "MediaPipePoseTracker | None" = None
-
-    def to_kwargs(self) -> dict:
-        """Convert config to kwargs dict for process_cmj_video."""
-        return {
-            "video_path": self.video_path,
-            "quality": self.quality,
-            "output_video": self.output_video,
-            "json_output": self.json_output,
-            "overrides": self.overrides,
-            "detection_confidence": self.detection_confidence,
-            "tracking_confidence": self.tracking_confidence,
-            "verbose": self.verbose,
-            "timer": self.timer,
-            "pose_tracker": self.pose_tracker,
-        }
 
 
 @dataclass
@@ -529,23 +509,6 @@ def process_cmj_video(
             return metrics
 
 
-def process_cmj_video_from_config(
-    config: CMJVideoConfig,
-) -> CMJMetrics:
-    """Process a CMJ video using a configuration object.
-
-    This is a convenience wrapper around process_cmj_video that
-    accepts a CMJVideoConfig instead of individual parameters.
-
-    Args:
-        config: Configuration object containing all analysis parameters
-
-    Returns:
-        CMJMetrics object containing analysis results
-    """
-    return process_cmj_video(**config.to_kwargs())
-
-
 def process_cmj_videos_bulk(
     configs: list[CMJVideoConfig],
     max_workers: int = 4,
@@ -572,8 +535,17 @@ def _process_cmj_video_wrapper(config: CMJVideoConfig) -> CMJVideoResult:
     start_time = time.perf_counter()
 
     try:
-        # Use convenience wrapper to avoid parameter unpacking
-        metrics = process_cmj_video_from_config(config)
+        metrics = process_cmj_video(
+            video_path=config.video_path,
+            quality=config.quality,
+            output_video=config.output_video,
+            json_output=config.json_output,
+            overrides=config.overrides,
+            detection_confidence=config.detection_confidence,
+            tracking_confidence=config.tracking_confidence,
+            verbose=False,
+        )
+
         processing_time = time.perf_counter() - start_time
 
         return CMJVideoResult(

kinemotion/{countermovement_jump → cmj}/cli.py

@@ -8,12 +8,9 @@ import click
 
 from ..core.auto_tuning import QualityPreset
 from ..core.cli_utils import (
-    batch_processing_options,
     collect_video_files,
     common_output_options,
     generate_batch_output_paths,
-    quality_option,
-    verbose_option,
 )
 from .api import AnalysisOverrides, process_cmj_video
 from .kinematics import CMJMetrics
@@ -62,9 +59,52 @@ def _process_batch_videos(
 @click.command(name="cmj-analyze")
 @click.argument("video_path", nargs=-1, type=click.Path(exists=False), required=True)
 @common_output_options
-@quality_option
-@verbose_option
-@batch_processing_options
+@click.option(
+    "--quality",
+    type=click.Choice(["fast", "balanced", "accurate"], case_sensitive=False),
+    default="balanced",
+    help=(
+        "Analysis quality preset: "
+        "fast (quick, less precise), "
+        "balanced (default, good for most cases), "
+        "accurate (research-grade, slower)"
+    ),
+    show_default=True,
+)
+@click.option(
+    "--verbose",
+    "-v",
+    is_flag=True,
+    help="Show auto-selected parameters and analysis details",
+)
+# Batch processing options
+@click.option(
+    "--batch",
+    is_flag=True,
+    help="Enable batch processing mode for multiple videos",
+)
+@click.option(
+    "--workers",
+    type=int,
+    default=4,
+    help="Number of parallel workers for batch processing (default: 4)",
+    show_default=True,
+)
+@click.option(
+    "--output-dir",
+    type=click.Path(),
+    help="Directory for debug video outputs (batch mode only)",
+)
+@click.option(
+    "--json-output-dir",
+    type=click.Path(),
+    help="Directory for JSON metrics outputs (batch mode only)",
+)
+@click.option(
+    "--csv-summary",
+    type=click.Path(),
+    help="Path for CSV summary export (batch mode only)",
+)
 # Expert parameters (hidden in help, but always available for advanced users)
 @click.option(
     "--smoothing-window",