kinemotion 0.43.0__py3-none-any.whl → 0.45.0__py3-none-any.whl

kinemotion/core/pipeline_utils.py

@@ -0,0 +1,429 @@
+"""Shared pipeline utilities for kinematic analysis."""
+
+from collections.abc import Callable
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from typing import TypeVar
+
+import cv2
+import numpy as np
+
+from ..cmj.analysis import compute_average_hip_position
+from ..dropjump.analysis import compute_average_foot_position
+from .auto_tuning import AnalysisParameters, QualityPreset, VideoCharacteristics
+from .pose import PoseTracker
+from .smoothing import smooth_landmarks, smooth_landmarks_advanced
+from .timing import PerformanceTimer
+from .video_io import VideoProcessor
+
+TResult = TypeVar("TResult")
+TConfig = TypeVar("TConfig")
+
+
+def parse_quality_preset(quality: str) -> QualityPreset:
+    """Parse and validate quality preset string.
+
+    Args:
+        quality: Quality preset string ('fast', 'balanced', or 'accurate')
+
+    Returns:
+        QualityPreset enum value
+
+    Raises:
+        ValueError: If quality preset is invalid
+    """
+    try:
+        return QualityPreset(quality.lower())
+    except ValueError as e:
+        raise ValueError(
+            f"Invalid quality preset: {quality}. "
+            "Must be 'fast', 'balanced', or 'accurate'"
+        ) from e
+
+
+def determine_confidence_levels(
+    quality_preset: QualityPreset,
+    detection_confidence: float | None,
+    tracking_confidence: float | None,
+) -> tuple[float, float]:
+    """Determine detection and tracking confidence levels.
+
+    Args:
+        quality_preset: Quality preset enum
+        detection_confidence: Optional expert override for detection confidence
+        tracking_confidence: Optional expert override for tracking confidence
+
+    Returns:
+        Tuple of (detection_confidence, tracking_confidence)
+    """
+    initial_detection_conf = 0.5
+    initial_tracking_conf = 0.5
+
+    if quality_preset == QualityPreset.FAST:
+        initial_detection_conf = 0.3
+        initial_tracking_conf = 0.3
+    elif quality_preset == QualityPreset.ACCURATE:
+        initial_detection_conf = 0.6
+        initial_tracking_conf = 0.6
+
+    if detection_confidence is not None:
+        initial_detection_conf = detection_confidence
+    if tracking_confidence is not None:
+        initial_tracking_conf = tracking_confidence
+
+    return initial_detection_conf, initial_tracking_conf
+
+
+def apply_expert_overrides(
+    params: AnalysisParameters,
+    smoothing_window: int | None,
+    velocity_threshold: float | None,
+    min_contact_frames: int | None,
+    visibility_threshold: float | None,
+) -> AnalysisParameters:
+    """Apply expert parameter overrides to auto-tuned parameters.
+
+    Args:
+        params: Auto-tuned parameters object
+        smoothing_window: Optional override for smoothing window
+        velocity_threshold: Optional override for velocity threshold
+        min_contact_frames: Optional override for minimum contact frames
+        visibility_threshold: Optional override for visibility threshold
+
+    Returns:
+        Modified params object (mutated in place)
+    """
+    if smoothing_window is not None:
+        params.smoothing_window = smoothing_window
+    if velocity_threshold is not None:
+        params.velocity_threshold = velocity_threshold
+    if min_contact_frames is not None:
+        params.min_contact_frames = min_contact_frames
+    if visibility_threshold is not None:
+        params.visibility_threshold = visibility_threshold
+    return params
+
+
+def print_verbose_parameters(
+    video: VideoProcessor,
+    characteristics: VideoCharacteristics,
+    quality_preset: QualityPreset,
+    params: AnalysisParameters,
+) -> None:
+    """Print auto-tuned parameters in verbose mode.
+
+    Args:
+        video: Video processor with fps and dimensions
+        characteristics: Video analysis characteristics
+        quality_preset: Selected quality preset
+        params: Auto-tuned parameters
+    """
+    print("\n" + "=" * 60)
+    print("AUTO-TUNED PARAMETERS")
+    print("=" * 60)
+    print(f"Video FPS: {video.fps:.2f}")
+    print(
+        f"Tracking quality: {characteristics.tracking_quality} "
+        f"(avg visibility: {characteristics.avg_visibility:.2f})"
+    )
+    print(f"Quality preset: {quality_preset.value}")
+    print("\nSelected parameters:")
+    print(f"  smoothing_window: {params.smoothing_window}")
+    print(f"  polyorder: {params.polyorder}")
+    print(f"  velocity_threshold: {params.velocity_threshold:.4f}")
+    print(f"  min_contact_frames: {params.min_contact_frames}")
+    print(f"  visibility_threshold: {params.visibility_threshold}")
+    print(f"  detection_confidence: {params.detection_confidence}")
+    print(f"  tracking_confidence: {params.tracking_confidence}")
+    print(f"  outlier_rejection: {params.outlier_rejection}")
+    print(f"  bilateral_filter: {params.bilateral_filter}")
+    print(f"  use_curvature: {params.use_curvature}")
+    print("=" * 60 + "\n")
+
+
+def process_all_frames(
+    video: VideoProcessor,
+    tracker: PoseTracker,
+    verbose: bool,
+    timer: PerformanceTimer | None = None,
+    close_tracker: bool = True,
+    target_debug_fps: float = 30.0,
+    max_debug_dim: int = 720,
+) -> tuple[list, list, list]:
+    """Process all frames from video and extract pose landmarks.
+
+    Args:
+        video: Video processor to read frames from
+        tracker: Pose tracker for landmark detection
+        verbose: Print progress messages
+        timer: Optional PerformanceTimer for measuring operations
+        close_tracker: Whether to close the tracker after processing (default: True)
+        target_debug_fps: Target FPS for debug video (default: 30.0)
+        max_debug_dim: Max dimension for debug video frames (default: 720)
+
+    Returns:
+        Tuple of (debug_frames, landmarks_sequence, frame_indices)
+
+    Raises:
+        ValueError: If no frames could be processed
+    """
+    if verbose:
+        print("Tracking pose landmarks...")
+
+    landmarks_sequence = []
+    debug_frames = []
+    frame_indices = []
+
+    step = max(1, int(video.fps / target_debug_fps))
+
+    w, h = video.display_width, video.display_height
+    scale = 1.0
+    if max(w, h) > max_debug_dim:
+        scale = max_debug_dim / max(w, h)
+
+    debug_w = int(w * scale) // 2 * 2
+    debug_h = int(h * scale) // 2 * 2
+    should_resize = (debug_w != video.width) or (debug_h != video.height)
+
+    frame_idx = 0
+
+    if timer:
+        with timer.measure("pose_tracking"):
+            while True:
+                frame = video.read_frame()
+                if frame is None:
+                    break
+
+                landmarks = tracker.process_frame(frame)
+                landmarks_sequence.append(landmarks)
+
+                if frame_idx % step == 0:
+                    if should_resize:
+                        processed_frame = cv2.resize(
+                            frame, (debug_w, debug_h), interpolation=cv2.INTER_LINEAR
+                        )
+                    else:
+                        processed_frame = frame
+
+                    debug_frames.append(processed_frame)
+                    frame_indices.append(frame_idx)
+
+                frame_idx += 1
+    else:
+        while True:
+            frame = video.read_frame()
+            if frame is None:
+                break
+
+            landmarks = tracker.process_frame(frame)
+            landmarks_sequence.append(landmarks)
+
+            if frame_idx % step == 0:
+                if should_resize:
+                    processed_frame = cv2.resize(
+                        frame, (debug_w, debug_h), interpolation=cv2.INTER_LINEAR
+                    )
+                else:
+                    processed_frame = frame
+
+                debug_frames.append(processed_frame)
+                frame_indices.append(frame_idx)
+
+            frame_idx += 1
+
+    if close_tracker:
+        tracker.close()
+
+    if not landmarks_sequence:
+        raise ValueError("No frames could be processed from video")
+
+    return debug_frames, landmarks_sequence, frame_indices
+
+
+def apply_smoothing(
+    landmarks_sequence: list,
+    params: AnalysisParameters,
+    verbose: bool,
+    timer: PerformanceTimer | None = None,
+) -> list:
+    """Apply smoothing to landmark sequence with auto-tuned parameters.
+
+    Args:
+        landmarks_sequence: Sequence of landmarks from all frames
+        params: Auto-tuned parameters containing smoothing settings
+        verbose: Print progress messages
+        timer: Optional PerformanceTimer for measuring operations
+
+    Returns:
+        Smoothed landmarks sequence
+    """
+    if params.outlier_rejection or params.bilateral_filter:
+        if verbose:
+            if params.outlier_rejection:
+                print("Smoothing landmarks with outlier rejection...")
+            if params.bilateral_filter:
+                print("Using bilateral temporal filter...")
+        if timer:
+            with timer.measure("smoothing"):
+                return smooth_landmarks_advanced(
+                    landmarks_sequence,
+                    window_length=params.smoothing_window,
+                    polyorder=params.polyorder,
+                    use_outlier_rejection=params.outlier_rejection,
+                    use_bilateral=params.bilateral_filter,
+                )
+        else:
+            return smooth_landmarks_advanced(
+                landmarks_sequence,
+                window_length=params.smoothing_window,
+                polyorder=params.polyorder,
+                use_outlier_rejection=params.outlier_rejection,
+                use_bilateral=params.bilateral_filter,
+            )
+    else:
+        if verbose:
+            print("Smoothing landmarks...")
+        if timer:
+            with timer.measure("smoothing"):
+                return smooth_landmarks(
+                    landmarks_sequence,
+                    window_length=params.smoothing_window,
+                    polyorder=params.polyorder,
+                )
+        else:
+            return smooth_landmarks(
+                landmarks_sequence,
+                window_length=params.smoothing_window,
+                polyorder=params.polyorder,
+            )
+
+
+def calculate_foot_visibility(frame_landmarks: dict) -> float:
+    """Calculate average visibility of foot landmarks.
+
+    Args:
+        frame_landmarks: Dictionary of landmarks for a frame
+
+    Returns:
+        Average visibility value (0-1)
+    """
+    foot_keys = ["left_ankle", "right_ankle", "left_heel", "right_heel"]
+    foot_vis = [frame_landmarks[key][2] for key in foot_keys if key in frame_landmarks]
+    return float(np.mean(foot_vis)) if foot_vis else 0.0
+
+
+def extract_vertical_positions(
+    smoothed_landmarks: list,
+    target: str = "foot",
+) -> tuple[np.ndarray, np.ndarray]:
+    """Extract vertical positions and visibilities from smoothed landmarks.
+
+    Args:
+        smoothed_landmarks: Smoothed landmark sequence
+        target: Tracking target "foot" or "hip" (default: "foot")
+
+    Returns:
+        Tuple of (vertical_positions, visibilities) as numpy arrays
+    """
+    position_list: list[float] = []
+    visibilities_list: list[float] = []
+
+    for frame_landmarks in smoothed_landmarks:
+        if frame_landmarks:
+            if target == "hip":
+                _, y = compute_average_hip_position(frame_landmarks)
+                vis = calculate_foot_visibility(frame_landmarks)
+            else:
+                _, y = compute_average_foot_position(frame_landmarks)
+                vis = calculate_foot_visibility(frame_landmarks)
+
+            position_list.append(y)
+            visibilities_list.append(vis)
+        else:
+            position_list.append(position_list[-1] if position_list else 0.5)
+            visibilities_list.append(0.0)
+
+    return np.array(position_list), np.array(visibilities_list)
+
+
+def convert_timer_to_stage_names(
+    timer_metrics: dict[str, float],
+) -> dict[str, float]:
+    """Convert timer metric names to human-readable stage names.
+
+    Args:
+        timer_metrics: Dictionary from PerformanceTimer.get_metrics()
+
+    Returns:
+        Dictionary with human-readable stage names as keys
+    """
+    mapping = {
+        "video_initialization": "Video initialization",
+        "pose_tracking": "Pose tracking",
+        "parameter_auto_tuning": "Parameter auto-tuning",
+        "smoothing": "Smoothing",
+        "vertical_position_extraction": "Vertical position extraction",
+        "ground_contact_detection": "Ground contact detection",
+        "metrics_calculation": "Metrics calculation",
+        "quality_assessment": "Quality assessment",
+        "metadata_building": "Metadata building",
+        "metrics_validation": "Metrics validation",
+        "phase_detection": "Phase detection",
+        "json_serialization": "JSON serialization",
+        "debug_video_generation": "Debug video generation",
+        "debug_video_reencode": "Debug video re-encoding",
+        "frame_rotation": "Frame rotation",
+        "debug_video_resize": "Debug video resizing",
+        "debug_video_copy": "Debug video frame copy",
+        "debug_video_draw": "Debug video drawing",
+        "debug_video_write": "Debug video encoding",
+    }
+    return {mapping.get(k, k): v for k, v in timer_metrics.items()}
+
+
+def process_videos_bulk_generic(
+    configs: list[TConfig],
+    processor_func: Callable[[TConfig], TResult],
+    error_factory: Callable[[str, str], TResult],
+    max_workers: int = 4,
+    progress_callback: Callable[[TResult], None] | None = None,
+) -> list[TResult]:
+    """
+    Generic function to process multiple videos in parallel.
+
+    Args:
+        configs: List of configuration objects
+        processor_func: Function to process a single config (must be picklable)
+        error_factory: Function that takes (video_path, error_msg) and returns a
+            result object
+        max_workers: Maximum number of parallel workers
+        progress_callback: Optional callback for progress updates
+
+    Returns:
+        List of result objects
+    """
+    results: list[TResult] = []
+
+    with ProcessPoolExecutor(max_workers=max_workers) as executor:
+        future_to_config = {
+            executor.submit(processor_func, config): config for config in configs
+        }
+
+        for future in as_completed(future_to_config):
+            config = future_to_config[future]
+            # Assume config has video_path - this is a constraint on TConfig
+            # but we can't easily enforce it with TypeVar in generic way
+            # without Protocol
+            # For now we assume dynamic access is okay or TConfig is duck-typed
+            video_path = getattr(config, "video_path", "unknown")
+
+            try:
+                result = future.result()
+            except Exception as exc:
+                result = error_factory(video_path, f"Unexpected error: {str(exc)}")
+
+            results.append(result)
+
+            if progress_callback:
+                progress_callback(result)
+
+    return results

kinemotion/dropjump/cli.py

@@ -1,7 +1,6 @@
 """Command-line interface for drop jump analysis."""
 
 import csv
-import glob
 import json
 import sys
 from dataclasses import dataclass
@@ -15,6 +14,10 @@ from ..api import (
     process_dropjump_video,
     process_dropjump_videos_bulk,
 )
+from ..core.cli_utils import (
+    collect_video_files,
+    generate_batch_output_paths,
+)
 
 
 @dataclass
@@ -176,20 +179,11 @@ def dropjump_analyze(  # NOSONAR(S107) - Click CLI requires individual
 
     \b
     # Batch with output directories
-    kinemotion dropjump-analyze videos/*.mp4 --batch \\
+    kinemotion dropjump-analyze videos/*.mp4 --batch \
         --json-output-dir results/ --csv-summary summary.csv
     """
     # Expand glob patterns and collect all video files
-    video_files: list[str] = []
-    for pattern in video_path:
-        expanded = glob.glob(pattern)
-        if expanded:
-            video_files.extend(expanded)
-        elif Path(pattern).exists():
-            # Direct path (not a glob pattern)
-            video_files.append(pattern)
-        else:
-            click.echo(f"Warning: No files found for pattern: {pattern}", err=True)
+    video_files = collect_video_files(video_path)
 
     if not video_files:
         click.echo("Error: No video files found", err=True)
@@ -275,7 +269,8 @@ def _process_single(
 
 
 def _setup_batch_output_dirs(
-    output_dir: str | None, json_output_dir: str | None
+    output_dir: str | None,
+    json_output_dir: str | None,
 ) -> None:
     """Create output directories for batch processing.
 
@@ -313,15 +308,9 @@ def _create_video_configs(
     """
     configs: list[DropJumpVideoConfig] = []
     for video_file in video_files:
-        video_name = Path(video_file).stem
-
-        debug_video = None
-        if output_dir:
-            debug_video = str(Path(output_dir) / f"{video_name}_debug.mp4")
-
-        json_file = None
-        if json_output_dir:
-            json_file = str(Path(json_output_dir) / f"{video_name}.json")
+        debug_video, json_file = generate_batch_output_paths(
+            video_file, output_dir, json_output_dir
+        )
 
         config = DropJumpVideoConfig(
             video_path=video_file,

{kinemotion-0.43.0.dist-info → kinemotion-0.45.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.43.0
+Version: 0.45.0
 Summary: Video-based kinematic analysis for athletic performance
 Project-URL: Homepage, https://github.com/feniix/kinemotion
 Project-URL: Repository, https://github.com/feniix/kinemotion

{kinemotion-0.43.0.dist-info → kinemotion-0.45.0.dist-info}/RECORD

@@ -1,9 +1,9 @@
 kinemotion/__init__.py,sha256=wPItmyGJUOFM6GPRVhAEvRz0-ErI7e2qiUREYJ9EfPQ,943
-kinemotion/api.py,sha256=oSCc3GNJcIBhjHyCoHbWRur8q3IzMP5y43ngwjyLwkg,52174
+kinemotion/api.py,sha256=ltOsxG9QGFqkBW15czaQ0Rn_Ed9Nh_qKYXBTiSBopXU,33181
 kinemotion/cli.py,sha256=cqYV_7URH0JUDy1VQ_EDLv63FmNO4Ns20m6s1XAjiP4,464
 kinemotion/cmj/__init__.py,sha256=Ynv0-Oco4I3Y1Ubj25m3h9h2XFqeNwpAewXmAYOmwfU,127
 kinemotion/cmj/analysis.py,sha256=qtULzp9uYzm5M0_Qu5YGJpuwjg9fz1VKAg6xg4NJxvM,21639
-kinemotion/cmj/cli.py,sha256=Mj2h9It1jVjAauvtCxfLWTRijj7zbYhxZuebhw2Zz6w,10828
+kinemotion/cmj/cli.py,sha256=d3_lX-zstch52BxDZUQJyTBpkr2YKwkOE0gUW6nAUb0,9908
 kinemotion/cmj/debug_overlay.py,sha256=fXmWoHhqMLGo4vTtB6Ezs3yLUDOLw63zLIgU2gFlJQU,15892
 kinemotion/cmj/joint_angles.py,sha256=HmheIEiKcQz39cRezk4h-htorOhGNPsqKIR9RsAEKts,9960
 kinemotion/cmj/kinematics.py,sha256=Lq9m9MNQxnXv31VhKmXVrlM7rRkhi8PxW50N_CC8_8Y,11860
@@ -11,13 +11,14 @@ kinemotion/cmj/metrics_validator.py,sha256=V_fmlczYH06SBtwqESv-IfGi3wDsIy3RQbd7V
 kinemotion/cmj/validation_bounds.py,sha256=9ZTo68fl3ooyWjXXyTMRLpK9tFANa_rQf3oHhq7iQGE,11995
 kinemotion/core/__init__.py,sha256=GTLnE_gGIk7HC51epWUXVuNxcvS5lf7UL6qeWRlgMV0,1352
 kinemotion/core/auto_tuning.py,sha256=wtCUMOhBChVJNXfEeku3GCMW4qED6MF-O_mv2sPTiVQ,11324
-kinemotion/core/cli_utils.py,sha256=zbnifPhD-OYofJioeYfJtshuWcl8OAEWtqCGVF4ctAI,7966
+kinemotion/core/cli_utils.py,sha256=sQPbT6XWWau-sm9yuN5c3eS5xNzoQGGXwSz6hQXtRvM,1859
 kinemotion/core/debug_overlay_utils.py,sha256=vOoWv3vlNdNgPI2R-UwAZKtSpugUUsiokR_kvaz1UWg,9025
 kinemotion/core/determinism.py,sha256=NwVrHqJiVxxFHTBPVy8aDBJH2SLIcYIpdGFp7glblB8,2515
 kinemotion/core/experimental.py,sha256=IK05AF4aZS15ke85hF3TWCqRIXU1AlD_XKzFz735Ua8,3640
 kinemotion/core/filtering.py,sha256=GsC9BB71V07LJJHgS2lsaxUAtJsupcUiwtZFDgODh8c,11417
 kinemotion/core/formatting.py,sha256=G_3eqgOtym9RFOZVEwCxye4A2cyrmgvtQ214vIshowU,2480
 kinemotion/core/metadata.py,sha256=bJAVa4nym__zx1hNowSZduMGKBSGOPxTbBQkjm6N0D0,7207
+kinemotion/core/pipeline_utils.py,sha256=s-2AJEt_beugjbCsiNyKVSc7YBdlgc9aocR_ZSX9PfQ,14783
 kinemotion/core/pose.py,sha256=Tq4VS0YmMzrprVUsELm6FQczyLhP8UKurM9ccYn1LLU,8959
 kinemotion/core/quality.py,sha256=dPGQp08y8DdEUbUdjTThnUOUsALgF0D2sdz50cm6wLI,13098
 kinemotion/core/smoothing.py,sha256=GAfC-jxu1eqNyDjsUXqUBicKx9um5hrk49wz1FxfRNM,15219
@@ -26,14 +27,14 @@ kinemotion/core/validation.py,sha256=LmKfSl4Ayw3DgwKD9IrhsPdzp5ia4drLsHA2UuU1SCM
 kinemotion/core/video_io.py,sha256=HyLwn22fKe37j18853YYYrQi0JQWAwxpepPLNkuZKnQ,8586
 kinemotion/dropjump/__init__.py,sha256=tC3H3BrCg8Oj-db-Vrtx4PH_llR1Ppkd5jwaOjhQcLg,862
 kinemotion/dropjump/analysis.py,sha256=MjxO-vps0nz_hXlnGk7cgq3jFenJYzsM0VVpHwnHXsM,27935
-kinemotion/dropjump/cli.py,sha256=n_Wfv3AC6YIgRPYhO3F2nTSai0NR7fh95nAoWjryQeY,16250
+kinemotion/dropjump/cli.py,sha256=eLIA0rnx60vqD__PinB1-5nQ8_xQUhCGplwsB0u9MgU,15824
 kinemotion/dropjump/debug_overlay.py,sha256=9nlnDYB_ZJO4dC1uMhDa4UOYGMBsDpyPQD3WbJjbwpM,6130
 kinemotion/dropjump/kinematics.py,sha256=kH-XM66wlOCYMpjvyb6_Qh5ZebyOfFZ47rmhgE1Tww4,19404
 kinemotion/dropjump/metrics_validator.py,sha256=CrTlGup8q2kyPXtA6HNwm7_yq0AsBaDllG7RVZdXmYA,9342
 kinemotion/dropjump/validation_bounds.py,sha256=5b4I3CKPybuvrbn-nP5yCcGF_sH4Vtyw3a5AWWvWnBk,4645
 kinemotion/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kinemotion-0.43.0.dist-info/METADATA,sha256=BTxQ2TBeVYsVzux_OTmoE-tOu8gbEBv2oxe7j-3nyDM,26020
-kinemotion-0.43.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-kinemotion-0.43.0.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
-kinemotion-0.43.0.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
-kinemotion-0.43.0.dist-info/RECORD,,
+kinemotion-0.45.0.dist-info/METADATA,sha256=pzhaPBL4rK6K3JJvLgFSQDL4rzS0cDRY77yke4iV7b4,26020
+kinemotion-0.45.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+kinemotion-0.45.0.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
+kinemotion-0.45.0.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
+kinemotion-0.45.0.dist-info/RECORD,,