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

kinemotion/api.py

@@ -7,6 +7,9 @@ The actual implementations have been moved to their respective submodules:
 """
 
 # CMJ API
+from .cmj.api import (
+    AnalysisOverrides as CMJAnalysisOverrides,
+)
 from .cmj.api import (
     CMJVideoConfig,
     CMJVideoResult,
@@ -17,6 +20,7 @@ from .cmj.kinematics import CMJMetrics
 
 # Drop jump API
 from .dropjump.api import (
+    AnalysisOverrides,
     DropJumpVideoConfig,
     DropJumpVideoResult,
     process_dropjump_video,
@@ -25,11 +29,13 @@ from .dropjump.api import (
 
 __all__ = [
     # Drop jump
+    "AnalysisOverrides",
     "DropJumpVideoConfig",
     "DropJumpVideoResult",
     "process_dropjump_video",
     "process_dropjump_videos_bulk",
     # CMJ
+    "CMJAnalysisOverrides",
     "CMJMetrics",
     "CMJVideoConfig",
     "CMJVideoResult",

kinemotion/cmj/api.py

@@ -5,12 +5,13 @@ import time
 from collections.abc import Callable
 from dataclasses import dataclass
 from pathlib import Path
-from typing import TYPE_CHECKING
 
-if TYPE_CHECKING:
-    pass
+import numpy as np
+from numpy.typing import NDArray
 
 from ..core.auto_tuning import (
+    AnalysisParameters,
+    QualityPreset,
     analyze_video_sample,
     auto_tune_parameters,
 )
@@ -37,8 +38,9 @@ from ..core.pipeline_utils import (
     process_videos_bulk_generic,
 )
 from ..core.pose import PoseTracker
-from ..core.quality import assess_jump_quality
+from ..core.quality import QualityAssessment, assess_jump_quality
 from ..core.timing import PerformanceTimer, Timer
+from ..core.validation import ValidationResult
 from ..core.video_io import VideoProcessor
 from .analysis import compute_signed_velocity, detect_cmj_phases
 from .debug_overlay import CMJDebugOverlayRenderer
@@ -46,6 +48,176 @@ from .kinematics import CMJMetrics, calculate_cmj_metrics
 from .metrics_validator import CMJMetricsValidator
 
 
+@dataclass
+class AnalysisOverrides:
+    """Optional overrides for analysis parameters.
+
+    Allows fine-tuning of specific analysis parameters beyond quality presets.
+    If None, values will be determined by the quality preset.
+    """
+
+    smoothing_window: int | None = None
+    velocity_threshold: float | None = None
+    min_contact_frames: int | None = None
+    visibility_threshold: float | None = None
+
+
+def _generate_debug_video(
+    output_video: str,
+    frames: list[NDArray[np.uint8]],
+    frame_indices: list[int],
+    smoothed_landmarks: list,
+    metrics: CMJMetrics,
+    video_fps: float,
+    timer: Timer,
+    verbose: bool,
+) -> None:
+    """Generate debug video with CMJ analysis overlay."""
+    if verbose:
+        print(f"Generating debug video: {output_video}")
+
+    debug_h, debug_w = frames[0].shape[:2]
+    step = max(1, int(video_fps / 30.0))
+    debug_fps = video_fps / step
+
+    with timer.measure("debug_video_generation"):
+        with CMJDebugOverlayRenderer(
+            output_video,
+            debug_w,
+            debug_h,
+            debug_w,
+            debug_h,
+            debug_fps,
+            timer=timer,
+        ) as renderer:
+            for frame, idx in zip(frames, frame_indices, strict=True):
+                annotated = renderer.render_frame(
+                    frame, smoothed_landmarks[idx], idx, metrics
+                )
+                renderer.write_frame(annotated)
+
+    if verbose:
+        print(f"Debug video saved: {output_video}")
+
+
+def _save_metrics_to_json(
+    metrics: CMJMetrics, json_output: str, timer: Timer, verbose: bool
+) -> None:
+    """Save metrics to JSON file."""
+    with timer.measure("json_serialization"):
+        output_path = Path(json_output)
+        metrics_dict = metrics.to_dict()
+        json_str = json.dumps(metrics_dict, indent=2)
+        output_path.write_text(json_str)
+
+    if verbose:
+        print(f"Metrics written to: {json_output}")
+
+
+def _print_timing_summary(start_time: float, timer: Timer, metrics: CMJMetrics) -> None:
+    """Print verbose timing summary and metrics."""
+    total_time = time.time() - start_time
+    stage_times = convert_timer_to_stage_names(timer.get_metrics())
+
+    print("\n=== Timing Summary ===")
+    for stage, duration in stage_times.items():
+        percentage = (duration / total_time) * 100
+        dur_ms = duration * 1000
+        print(f"{stage:.<40} {dur_ms:>6.0f}ms ({percentage:>5.1f}%)")
+    total_ms = total_time * 1000
+    print(f"{'Total':.<40} {total_ms:>6.0f}ms (100.0%)")
+    print()
+
+    print(f"\nJump height: {metrics.jump_height:.3f}m")
+    print(f"Flight time: {metrics.flight_time * 1000:.1f}ms")
+    print(f"Countermovement depth: {metrics.countermovement_depth:.3f}m")
+
+
+def _print_quality_warnings(quality_result: QualityAssessment, verbose: bool) -> None:
+    """Print quality warnings if present."""
+    if verbose and quality_result.warnings:
+        print("\n⚠️  Quality Warnings:")
+        for warning in quality_result.warnings:
+            print(f"  - {warning}")
+        print()
+
+
+def _print_validation_results(
+    validation_result: ValidationResult, verbose: bool
+) -> None:
+    """Print validation issues if present."""
+    if verbose and validation_result.issues:
+        print("\n⚠️  Validation Results:")
+        for issue in validation_result.issues:
+            print(f"  [{issue.severity.value}] {issue.metric}: {issue.message}")
+
+
+def _create_algorithm_config(params: AnalysisParameters) -> AlgorithmConfig:
+    """Create algorithm configuration from parameters."""
+    return AlgorithmConfig(
+        detection_method="backward_search",
+        tracking_method="mediapipe_pose",
+        model_complexity=1,
+        smoothing=SmoothingConfig(
+            window_size=params.smoothing_window,
+            polynomial_order=params.polyorder,
+            use_bilateral_filter=params.bilateral_filter,
+            use_outlier_rejection=params.outlier_rejection,
+        ),
+        detection=DetectionConfig(
+            velocity_threshold=params.velocity_threshold,
+            min_contact_frames=params.min_contact_frames,
+            visibility_threshold=params.visibility_threshold,
+            use_curvature_refinement=params.use_curvature,
+        ),
+        drop_detection=None,
+    )
+
+
+def _create_video_info(video_path: str, video: VideoProcessor) -> VideoInfo:
+    """Create video information metadata."""
+    return VideoInfo(
+        source_path=video_path,
+        fps=video.fps,
+        width=video.width,
+        height=video.height,
+        duration_s=video.frame_count / video.fps,
+        frame_count=video.frame_count,
+        codec=video.codec,
+    )
+
+
+def _create_processing_info(
+    start_time: float, quality_preset: QualityPreset, timer: Timer
+) -> ProcessingInfo:
+    """Create processing information metadata."""
+    processing_time = time.time() - start_time
+    stage_times = convert_timer_to_stage_names(timer.get_metrics())
+
+    return ProcessingInfo(
+        version=get_kinemotion_version(),
+        timestamp=create_timestamp(),
+        quality_preset=quality_preset.value,
+        processing_time_s=processing_time,
+        timing_breakdown=stage_times,
+    )
+
+
+def _create_result_metadata(
+    quality_result: QualityAssessment,
+    video_info: VideoInfo,
+    processing_info: ProcessingInfo,
+    algorithm_config: AlgorithmConfig,
+) -> ResultMetadata:
+    """Create result metadata from components."""
+    return ResultMetadata(
+        quality=quality_result,
+        video=video_info,
+        processing=processing_info,
+        algorithm=algorithm_config,
+    )
+
+
 @dataclass
 class CMJVideoConfig:
     """Configuration for processing a single CMJ video."""
@@ -54,10 +226,7 @@ class CMJVideoConfig:
     quality: str = "balanced"
     output_video: str | None = None
     json_output: str | None = None
-    smoothing_window: int | None = None
-    velocity_threshold: float | None = None
-    min_contact_frames: int | None = None
-    visibility_threshold: float | None = None
+    overrides: AnalysisOverrides | None = None
     detection_confidence: float | None = None
     tracking_confidence: float | None = None
 
@@ -78,15 +247,12 @@ def process_cmj_video(
     quality: str = "balanced",
     output_video: str | None = None,
     json_output: str | None = None,
-    smoothing_window: int | None = None,
-    velocity_threshold: float | None = None,
-    min_contact_frames: int | None = None,
-    visibility_threshold: float | None = None,
+    overrides: AnalysisOverrides | None = None,
     detection_confidence: float | None = None,
     tracking_confidence: float | None = None,
     verbose: bool = False,
     timer: Timer | None = None,
-    pose_tracker: "PoseTracker | None" = None,
+    pose_tracker: PoseTracker | None = None,
 ) -> CMJMetrics:
     """
     Process a single CMJ video and return metrics.
@@ -100,10 +266,7 @@ def process_cmj_video(
         quality: Analysis quality preset ("fast", "balanced", or "accurate")
         output_video: Optional path for debug video output
         json_output: Optional path for JSON metrics output
-        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
+        overrides: Optional AnalysisOverrides with parameter fine-tuning
         detection_confidence: Optional override for pose detection confidence
         tracking_confidence: Optional override for pose tracking confidence
         verbose: Print processing details
@@ -121,9 +284,7 @@ def process_cmj_video(
         raise FileNotFoundError(f"Video file not found: {video_path}")
 
     start_time = time.time()
-    if timer is None:
-        timer = PerformanceTimer()
-
+    timer = timer or PerformanceTimer()
     quality_preset = parse_quality_preset(quality)
 
     with timer.measure("video_initialization"):
@@ -141,16 +302,12 @@ def process_cmj_video(
             if verbose:
                 print("Processing all frames with MediaPipe pose tracking...")
 
-            tracker = pose_tracker
-            should_close_tracker = False
-
-            if tracker is None:
-                tracker = PoseTracker(
-                    min_detection_confidence=det_conf,
-                    min_tracking_confidence=track_conf,
-                    timer=timer,
-                )
-                should_close_tracker = True
+            tracker = pose_tracker or PoseTracker(
+                min_detection_confidence=det_conf,
+                min_tracking_confidence=track_conf,
+                timer=timer,
+            )
+            should_close_tracker = pose_tracker is None
 
             frames, landmarks_sequence, frame_indices = process_all_frames(
                 video, tracker, verbose, timer, close_tracker=should_close_tracker
@@ -161,13 +318,12 @@ def process_cmj_video(
                     landmarks_sequence, video.fps, video.frame_count
                 )
                 params = auto_tune_parameters(characteristics, quality_preset)
-
                 params = apply_expert_overrides(
                     params,
-                    smoothing_window,
-                    velocity_threshold,
-                    min_contact_frames,
-                    visibility_threshold,
+                    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:
@@ -185,13 +341,10 @@ def process_cmj_video(
                 vertical_positions, visibilities = extract_vertical_positions(
                     smoothed_landmarks, target="hip"
                 )
-
                 foot_positions, _ = extract_vertical_positions(
                     smoothed_landmarks, target="foot"
                 )
 
-            tracking_method = "hip_hybrid"
-
             if verbose:
                 print("Detecting CMJ phases...")
             with timer.measure("phase_detection"):
@@ -217,7 +370,6 @@ def process_cmj_video(
                     window_length=params.smoothing_window,
                     polyorder=params.polyorder,
                 )
-
                 metrics = calculate_cmj_metrics(
                     vertical_positions,
                     velocities,
@@ -226,7 +378,7 @@ def process_cmj_video(
                     takeoff_frame,
                     landing_frame,
                     video.fps,
-                    tracking_method=tracking_method,
+                    tracking_method="hip_hybrid",
                 )
 
             if verbose:
@@ -238,137 +390,49 @@ def process_cmj_video(
                     use_median=True,
                     interpolate=False,
                 )
-
-                phases_detected = True
-                phase_count = 4
-
                 quality_result = assess_jump_quality(
                     visibilities=visibilities,
                     positions=vertical_positions,
                     outlier_mask=outlier_mask,
                     fps=video.fps,
-                    phases_detected=phases_detected,
-                    phase_count=phase_count,
+                    phases_detected=True,
+                    phase_count=4,
                 )
 
-            algorithm_config = AlgorithmConfig(
-                detection_method="backward_search",
-                tracking_method="mediapipe_pose",
-                model_complexity=1,
-                smoothing=SmoothingConfig(
-                    window_size=params.smoothing_window,
-                    polynomial_order=params.polyorder,
-                    use_bilateral_filter=params.bilateral_filter,
-                    use_outlier_rejection=params.outlier_rejection,
-                ),
-                detection=DetectionConfig(
-                    velocity_threshold=params.velocity_threshold,
-                    min_contact_frames=params.min_contact_frames,
-                    visibility_threshold=params.visibility_threshold,
-                    use_curvature_refinement=params.use_curvature,
-                ),
-                drop_detection=None,
-            )
-
-            video_info = VideoInfo(
-                source_path=video_path,
-                fps=video.fps,
-                width=video.width,
-                height=video.height,
-                duration_s=video.frame_count / video.fps,
-                frame_count=video.frame_count,
-                codec=video.codec,
-            )
-
-            if verbose and quality_result.warnings:
-                print("\n⚠️  Quality Warnings:")
-                for warning in quality_result.warnings:
-                    print(f"  - {warning}")
-                print()
+            _print_quality_warnings(quality_result, verbose)
 
             if output_video:
-                if verbose:
-                    print(f"Generating debug video: {output_video}")
-
-                debug_h, debug_w = frames[0].shape[:2]
-                step = max(1, int(video.fps / 30.0))
-                debug_fps = video.fps / step
-
-                with timer.measure("debug_video_generation"):
-                    with CMJDebugOverlayRenderer(
-                        output_video,
-                        debug_w,
-                        debug_h,
-                        debug_w,
-                        debug_h,
-                        debug_fps,
-                        timer=timer,
-                    ) as renderer:
-                        for frame, idx in zip(frames, frame_indices, strict=True):
-                            annotated = renderer.render_frame(
-                                frame, smoothed_landmarks[idx], idx, metrics
-                            )
-                            renderer.write_frame(annotated)
-
-                if verbose:
-                    print(f"Debug video saved: {output_video}")
+                _generate_debug_video(
+                    output_video,
+                    frames,
+                    frame_indices,
+                    smoothed_landmarks,
+                    metrics,
+                    video.fps,
+                    timer,
+                    verbose,
+                )
 
             with timer.measure("metrics_validation"):
                 validator = CMJMetricsValidator()
                 validation_result = validator.validate(metrics.to_dict())  # type: ignore[arg-type]
                 metrics.validation_result = validation_result
 
-            processing_time = time.time() - start_time
-            stage_times = convert_timer_to_stage_names(timer.get_metrics())
-
-            processing_info = ProcessingInfo(
-                version=get_kinemotion_version(),
-                timestamp=create_timestamp(),
-                quality_preset=quality_preset.value,
-                processing_time_s=processing_time,
-                timing_breakdown=stage_times,
-            )
-
-            result_metadata = ResultMetadata(
-                quality=quality_result,
-                video=video_info,
-                processing=processing_info,
-                algorithm=algorithm_config,
+            algorithm_config = _create_algorithm_config(params)
+            video_info = _create_video_info(video_path, video)
+            processing_info = _create_processing_info(start_time, quality_preset, timer)
+            result_metadata = _create_result_metadata(
+                quality_result, video_info, processing_info, algorithm_config
             )
-
             metrics.result_metadata = result_metadata
 
             if json_output:
-                with timer.measure("json_serialization"):
-                    output_path = Path(json_output)
-                    metrics_dict = metrics.to_dict()
-                    json_str = json.dumps(metrics_dict, indent=2)
-                    output_path.write_text(json_str)
-
-                if verbose:
-                    print(f"Metrics written to: {json_output}")
+                _save_metrics_to_json(metrics, json_output, timer, verbose)
 
-            if verbose and validation_result.issues:
-                print("\n⚠️  Validation Results:")
-                for issue in validation_result.issues:
-                    print(f"  [{issue.severity.value}] {issue.metric}: {issue.message}")
+            _print_validation_results(validation_result, verbose)
 
             if verbose:
-                total_time = time.time() - start_time
-                stage_times = convert_timer_to_stage_names(timer.get_metrics())
-
-                print("\n=== Timing Summary ===")
-                for stage, duration in stage_times.items():
-                    percentage = (duration / total_time) * 100
-                    dur_ms = duration * 1000
-                    print(f"{stage:. <40} {dur_ms:>6.0f}ms ({percentage:>5.1f}%)")
-                total_ms = total_time * 1000
-                print(f"{('Total'):.>40} {total_ms:>6.0f}ms (100.0%)")
-                print()
-
-                print(f"\nJump height: {metrics.jump_height:.3f}m")
-                print(f"Flight time: {metrics.flight_time * 1000:.1f}ms")
-                print(f"Countermovement depth: {metrics.countermovement_depth:.3f}m")
+                _print_timing_summary(start_time, timer, metrics)
 
             return metrics
 
@@ -404,10 +468,7 @@ def _process_cmj_video_wrapper(config: CMJVideoConfig) -> CMJVideoResult:
             quality=config.quality,
             output_video=config.output_video,
             json_output=config.json_output,
-            smoothing_window=config.smoothing_window,
-            velocity_threshold=config.velocity_threshold,
-            min_contact_frames=config.min_contact_frames,
-            visibility_threshold=config.visibility_threshold,
+            overrides=config.overrides,
             detection_confidence=config.detection_confidence,
             tracking_confidence=config.tracking_confidence,
             verbose=False,

kinemotion/cmj/cli.py

@@ -12,7 +12,7 @@ from ..core.cli_utils import (
     common_output_options,
     generate_batch_output_paths,
 )
-from .api import process_cmj_video
+from .api import AnalysisOverrides, process_cmj_video
 from .kinematics import CMJMetrics
 
 
@@ -260,16 +260,21 @@ def _process_single(
 ) -> None:
     """Process a single CMJ video by calling the API."""
     try:
+        # Create overrides from expert parameters
+        overrides = AnalysisOverrides(
+            smoothing_window=expert_params.smoothing_window,
+            velocity_threshold=expert_params.velocity_threshold,
+            min_contact_frames=expert_params.min_contact_frames,
+            visibility_threshold=expert_params.visibility_threshold,
+        )
+
         # Call the API function (handles all processing logic)
         metrics = process_cmj_video(
             video_path=video_path,
             quality=quality_preset.value,
             output_video=output,
             json_output=json_output,
-            smoothing_window=expert_params.smoothing_window,
-            velocity_threshold=expert_params.velocity_threshold,
-            min_contact_frames=expert_params.min_contact_frames,
-            visibility_threshold=expert_params.visibility_threshold,
+            overrides=overrides,
             detection_confidence=expert_params.detection_confidence,
             tracking_confidence=expert_params.tracking_confidence,
             verbose=verbose,

kinemotion/dropjump/api.py

@@ -13,6 +13,7 @@ if TYPE_CHECKING:
 from ..core.auto_tuning import (
     AnalysisParameters,
     QualityPreset,
+    VideoCharacteristics,
     analyze_video_sample,
     auto_tune_parameters,
 )
@@ -52,6 +53,20 @@ from .kinematics import DropJumpMetrics, calculate_drop_jump_metrics
 from .metrics_validator import DropJumpMetricsValidator
 
 
+@dataclass
+class AnalysisOverrides:
+    """Optional overrides for analysis parameters.
+
+    Allows fine-tuning of specific analysis parameters beyond quality presets.
+    If None, values will be determined by the quality preset.
+    """
+
+    smoothing_window: int | None = None
+    velocity_threshold: float | None = None
+    min_contact_frames: int | None = None
+    visibility_threshold: float | None = None
+
+
 @dataclass
 class DropJumpVideoResult:
     """Result of processing a single drop jump video."""
@@ -72,10 +87,7 @@ class DropJumpVideoConfig:
     output_video: str | None = None
     json_output: str | None = None
     drop_start_frame: int | None = None
-    smoothing_window: int | None = None
-    velocity_threshold: float | None = None
-    min_contact_frames: int | None = None
-    visibility_threshold: float | None = None
+    overrides: AnalysisOverrides | None = None
     detection_confidence: float | None = None
     tracking_confidence: float | None = None
 
@@ -219,6 +231,195 @@ def _print_dropjump_summary(
     print("Analysis complete!")
 
 
+def _setup_pose_tracker(
+    quality_preset: QualityPreset,
+    detection_confidence: float | None,
+    tracking_confidence: float | None,
+    pose_tracker: "PoseTracker | None",
+    timer: Timer,
+) -> tuple["PoseTracker", bool]:
+    """Set up pose tracker and determine if it should be closed."""
+    detection_conf, tracking_conf = determine_confidence_levels(
+        quality_preset, detection_confidence, tracking_confidence
+    )
+
+    tracker = pose_tracker
+    should_close_tracker = False
+
+    if tracker is None:
+        tracker = PoseTracker(
+            min_detection_confidence=detection_conf,
+            min_tracking_confidence=tracking_conf,
+            timer=timer,
+        )
+        should_close_tracker = True
+
+    return tracker, should_close_tracker
+
+
+def _process_frames_and_landmarks(
+    video: "VideoProcessor",
+    tracker: "PoseTracker",
+    should_close_tracker: bool,
+    verbose: bool,
+    timer: Timer,
+) -> tuple[list, list, list[int]]:
+    """Process all video frames and extract landmarks."""
+    if verbose:
+        print("Processing all frames with MediaPipe pose tracking...")
+
+    frames, landmarks_sequence, frame_indices = process_all_frames(
+        video, tracker, verbose, timer, close_tracker=should_close_tracker
+    )
+
+    return frames, landmarks_sequence, frame_indices
+
+
+def _tune_and_smooth(
+    landmarks_sequence: list,
+    video_fps: float,
+    frame_count: int,
+    quality_preset: QualityPreset,
+    overrides: AnalysisOverrides | None,
+    timer: Timer,
+    verbose: bool,
+) -> tuple[list, AnalysisParameters, VideoCharacteristics]:
+    """Tune parameters and apply smoothing to landmarks.
+
+    Args:
+        landmarks_sequence: Sequence of pose landmarks
+        video_fps: Video frame rate
+        frame_count: Total number of frames
+        quality_preset: Quality preset for analysis
+        overrides: Optional parameter overrides
+        timer: Performance timer
+        verbose: Verbose output flag
+
+    Returns:
+        Tuple of (smoothed_landmarks, params, characteristics)
+    """
+    with timer.measure("parameter_auto_tuning"):
+        characteristics = analyze_video_sample(
+            landmarks_sequence, video_fps, frame_count
+        )
+        params = auto_tune_parameters(characteristics, quality_preset)
+
+        # Apply overrides if provided
+        if overrides:
+            params = apply_expert_overrides(
+                params,
+                overrides.smoothing_window,
+                overrides.velocity_threshold,
+                overrides.min_contact_frames,
+                overrides.visibility_threshold,
+            )
+        else:
+            params = apply_expert_overrides(
+                params,
+                None,
+                None,
+                None,
+                None,
+            )
+
+    smoothed_landmarks = apply_smoothing(landmarks_sequence, params, verbose, timer)
+
+    return smoothed_landmarks, params, characteristics
+
+
+def _extract_positions_and_detect_contact(
+    smoothed_landmarks: list,
+    params: AnalysisParameters,
+    timer: Timer,
+    verbose: bool,
+) -> tuple["NDArray", "NDArray", list]:
+    """Extract vertical positions and detect ground contact."""
+    if verbose:
+        print("Extracting foot positions...")
+    with timer.measure("vertical_position_extraction"):
+        vertical_positions, visibilities = extract_vertical_positions(
+            smoothed_landmarks
+        )
+
+    if verbose:
+        print("Detecting ground contact...")
+    with timer.measure("ground_contact_detection"):
+        contact_states = detect_ground_contact(
+            vertical_positions,
+            velocity_threshold=params.velocity_threshold,
+            min_contact_frames=params.min_contact_frames,
+            visibility_threshold=params.visibility_threshold,
+            visibilities=visibilities,
+            window_length=params.smoothing_window,
+            polyorder=params.polyorder,
+            timer=timer,
+        )
+
+    return vertical_positions, visibilities, contact_states
+
+
+def _calculate_metrics_and_assess_quality(
+    contact_states: list,
+    vertical_positions: "NDArray",
+    visibilities: "NDArray",
+    video_fps: float,
+    drop_start_frame: int | None,
+    params: AnalysisParameters,
+    timer: Timer,
+    verbose: bool,
+) -> tuple[DropJumpMetrics, QualityAssessment]:
+    """Calculate metrics and assess quality."""
+    if verbose:
+        print("Calculating metrics...")
+    with timer.measure("metrics_calculation"):
+        metrics = calculate_drop_jump_metrics(
+            contact_states,
+            vertical_positions,
+            video_fps,
+            drop_start_frame=drop_start_frame,
+            velocity_threshold=params.velocity_threshold,
+            smoothing_window=params.smoothing_window,
+            polyorder=params.polyorder,
+            use_curvature=params.use_curvature,
+            timer=timer,
+        )
+
+    if verbose:
+        print("Assessing tracking quality...")
+    with timer.measure("quality_assessment"):
+        quality_result, _, _, _ = _assess_dropjump_quality(
+            vertical_positions, visibilities, contact_states, video_fps
+        )
+
+    return metrics, quality_result
+
+
+def _print_quality_warnings(quality_result: QualityAssessment, verbose: bool) -> None:
+    """Print quality warnings if present."""
+    if verbose and quality_result.warnings:
+        print("\n⚠️  Quality Warnings:")
+        for warning in quality_result.warnings:
+            print(f"  - {warning}")
+        print()
+
+
+def _validate_metrics_and_print_results(
+    metrics: DropJumpMetrics,
+    timer: Timer,
+    verbose: bool,
+) -> None:
+    """Validate metrics and print validation results if verbose."""
+    with timer.measure("metrics_validation"):
+        validator = DropJumpMetricsValidator()
+        validation_result = validator.validate(metrics.to_dict())  # type: ignore[arg-type]
+        metrics.validation_result = validation_result
+
+    if verbose and validation_result.issues:
+        print("\n⚠️  Validation Results:")
+        for issue in validation_result.issues:
+            print(f"  [{issue.severity.value}] {issue.metric}: {issue.message}")
+
+
 def _generate_debug_video(
     output_video: str,
     frames: list,
@@ -285,10 +486,7 @@ def process_dropjump_video(
     output_video: str | None = None,
     json_output: str | None = None,
     drop_start_frame: int | None = None,
-    smoothing_window: int | None = None,
-    velocity_threshold: float | None = None,
-    min_contact_frames: int | None = None,
-    visibility_threshold: float | None = None,
+    overrides: AnalysisOverrides | None = None,
     detection_confidence: float | None = None,
     tracking_confidence: float | None = None,
     verbose: bool = False,
@@ -306,10 +504,7 @@ def process_dropjump_video(
         output_video: Optional path for debug video output
         json_output: Optional path for JSON metrics output
         drop_start_frame: Optional manual drop start frame
-        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
+        overrides: Optional AnalysisOverrides for fine-tuning parameters
         detection_confidence: Optional override for pose detection confidence
         tracking_confidence: Optional override for pose tracking confidence
         verbose: Print processing details
@@ -331,106 +526,54 @@ def process_dropjump_video(
     set_deterministic_mode(seed=42)
 
     start_time = time.time()
-    if timer is None:
-        timer = PerformanceTimer()
-
+    timer = timer or PerformanceTimer()
     quality_preset = parse_quality_preset(quality)
 
     with timer.measure("video_initialization"):
         with VideoProcessor(video_path, timer=timer) as video:
-            detection_conf, tracking_conf = determine_confidence_levels(
-                quality_preset, detection_confidence, tracking_confidence
+            tracker, should_close_tracker = _setup_pose_tracker(
+                quality_preset,
+                detection_confidence,
+                tracking_confidence,
+                pose_tracker,
+                timer,
             )
 
-            if verbose:
-                print("Processing all frames with MediaPipe pose tracking...")
-
-            tracker = pose_tracker
-            should_close_tracker = False
-
-            if tracker is None:
-                tracker = PoseTracker(
-                    min_detection_confidence=detection_conf,
-                    min_tracking_confidence=tracking_conf,
-                    timer=timer,
-                )
-                should_close_tracker = True
-
-            frames, landmarks_sequence, frame_indices = process_all_frames(
-                video, tracker, verbose, timer, close_tracker=should_close_tracker
+            frames, landmarks_sequence, frame_indices = _process_frames_and_landmarks(
+                video, tracker, should_close_tracker, verbose, timer
             )
 
-            with timer.measure("parameter_auto_tuning"):
-                characteristics = analyze_video_sample(
-                    landmarks_sequence, video.fps, video.frame_count
-                )
-                params = auto_tune_parameters(characteristics, quality_preset)
-
-                params = apply_expert_overrides(
-                    params,
-                    smoothing_window,
-                    velocity_threshold,
-                    min_contact_frames,
-                    visibility_threshold,
-                )
-
-                if verbose:
-                    print_verbose_parameters(
-                        video, characteristics, quality_preset, params
-                    )
-
-            smoothed_landmarks = apply_smoothing(
-                landmarks_sequence, params, verbose, timer
+            smoothed_landmarks, params, characteristics = _tune_and_smooth(
+                landmarks_sequence,
+                video.fps,
+                video.frame_count,
+                quality_preset,
+                overrides,
+                timer,
+                verbose,
             )
 
             if verbose:
-                print("Extracting foot positions...")
-            with timer.measure("vertical_position_extraction"):
-                vertical_positions, visibilities = extract_vertical_positions(
-                    smoothed_landmarks
-                )
+                print_verbose_parameters(video, characteristics, quality_preset, params)
 
-            if verbose:
-                print("Detecting ground contact...")
-            with timer.measure("ground_contact_detection"):
-                contact_states = detect_ground_contact(
-                    vertical_positions,
-                    velocity_threshold=params.velocity_threshold,
-                    min_contact_frames=params.min_contact_frames,
-                    visibility_threshold=params.visibility_threshold,
-                    visibilities=visibilities,
-                    window_length=params.smoothing_window,
-                    polyorder=params.polyorder,
-                    timer=timer,
-                )
-
-            if verbose:
-                print("Calculating metrics...")
-            with timer.measure("metrics_calculation"):
-                metrics = calculate_drop_jump_metrics(
-                    contact_states,
-                    vertical_positions,
-                    video.fps,
-                    drop_start_frame=drop_start_frame,
-                    velocity_threshold=params.velocity_threshold,
-                    smoothing_window=params.smoothing_window,
-                    polyorder=params.polyorder,
-                    use_curvature=params.use_curvature,
-                    timer=timer,
+            vertical_positions, visibilities, contact_states = (
+                _extract_positions_and_detect_contact(
+                    smoothed_landmarks, params, timer, verbose
                 )
+            )
 
-            if verbose:
-                print("Assessing tracking quality...")
-            with timer.measure("quality_assessment"):
-                quality_result, _, _, _ = _assess_dropjump_quality(
-                    vertical_positions, visibilities, contact_states, video.fps
-                )
+            metrics, quality_result = _calculate_metrics_and_assess_quality(
+                contact_states,
+                vertical_positions,
+                visibilities,
+                video.fps,
+                drop_start_frame,
+                params,
+                timer,
+                verbose,
+            )
 
-            if verbose and quality_result.warnings:
-                print("\n⚠️  Quality Warnings:")
-                for warning in quality_result.warnings:
-                    print(f"  - {warning}")
-                print()
+            _print_quality_warnings(quality_result, verbose)
 
             if output_video:
                 _generate_debug_video(
@@ -445,15 +588,7 @@ def process_dropjump_video(
                     verbose,
                 )
 
-            with timer.measure("metrics_validation"):
-                validator = DropJumpMetricsValidator()
-                validation_result = validator.validate(metrics.to_dict())  # type: ignore[arg-type]
-                metrics.validation_result = validation_result
-
-            if verbose and validation_result.issues:
-                print("\n⚠️  Validation Results:")
-                for issue in validation_result.issues:
-                    print(f"  [{issue.severity.value}] {issue.metric}: {issue.message}")
+            _validate_metrics_and_print_results(metrics, timer, verbose)
 
             processing_time = time.time() - start_time
             result_metadata = _build_dropjump_metadata(
@@ -512,10 +647,7 @@ def _process_dropjump_video_wrapper(config: DropJumpVideoConfig) -> DropJumpVide
             output_video=config.output_video,
             json_output=config.json_output,
             drop_start_frame=config.drop_start_frame,
-            smoothing_window=config.smoothing_window,
-            velocity_threshold=config.velocity_threshold,
-            min_contact_frames=config.min_contact_frames,
-            visibility_threshold=config.visibility_threshold,
+            overrides=config.overrides,
             detection_confidence=config.detection_confidence,
             tracking_confidence=config.tracking_confidence,
             verbose=False,

kinemotion/dropjump/cli.py

@@ -237,6 +237,25 @@ def _process_single(
     click.echo(f"Analyzing video: {video_path}", err=True)
 
     try:
+        # Create AnalysisOverrides if any expert parameters are set
+        from .api import AnalysisOverrides
+
+        overrides = None
+        if any(
+            [
+                expert_params.smoothing_window is not None,
+                expert_params.velocity_threshold is not None,
+                expert_params.min_contact_frames is not None,
+                expert_params.visibility_threshold is not None,
+            ]
+        ):
+            overrides = AnalysisOverrides(
+                smoothing_window=expert_params.smoothing_window,
+                velocity_threshold=expert_params.velocity_threshold,
+                min_contact_frames=expert_params.min_contact_frames,
+                visibility_threshold=expert_params.visibility_threshold,
+            )
+
         # Call the API function (handles all processing logic)
         metrics = process_dropjump_video(
             video_path=video_path,
@@ -244,10 +263,7 @@ def _process_single(
             output_video=output,
             json_output=json_output,
             drop_start_frame=expert_params.drop_start_frame,
-            smoothing_window=expert_params.smoothing_window,
-            velocity_threshold=expert_params.velocity_threshold,
-            min_contact_frames=expert_params.min_contact_frames,
-            visibility_threshold=expert_params.visibility_threshold,
+            overrides=overrides,
             detection_confidence=expert_params.detection_confidence,
             tracking_confidence=expert_params.tracking_confidence,
             verbose=verbose,
@@ -312,16 +328,32 @@ def _create_video_configs(
             video_file, output_dir, json_output_dir
         )
 
+        # Create AnalysisOverrides if any expert parameters are set
+        from .api import AnalysisOverrides
+
+        overrides = None
+        if any(
+            [
+                expert_params.smoothing_window is not None,
+                expert_params.velocity_threshold is not None,
+                expert_params.min_contact_frames is not None,
+                expert_params.visibility_threshold is not None,
+            ]
+        ):
+            overrides = AnalysisOverrides(
+                smoothing_window=expert_params.smoothing_window,
+                velocity_threshold=expert_params.velocity_threshold,
+                min_contact_frames=expert_params.min_contact_frames,
+                visibility_threshold=expert_params.visibility_threshold,
+            )
+
         config = DropJumpVideoConfig(
             video_path=video_file,
             quality=quality,
             output_video=debug_video,
             json_output=json_file,
             drop_start_frame=expert_params.drop_start_frame,
-            smoothing_window=expert_params.smoothing_window,
-            velocity_threshold=expert_params.velocity_threshold,
-            min_contact_frames=expert_params.min_contact_frames,
-            visibility_threshold=expert_params.visibility_threshold,
+            overrides=overrides,
             detection_confidence=expert_params.detection_confidence,
             tracking_confidence=expert_params.tracking_confidence,
         )

{kinemotion-0.47.3.dist-info → kinemotion-0.48.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.47.3
+Version: 0.48.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.47.3.dist-info → kinemotion-0.48.0.dist-info}/RECORD

@@ -1,10 +1,10 @@
 kinemotion/__init__.py,sha256=wPItmyGJUOFM6GPRVhAEvRz0-ErI7e2qiUREYJ9EfPQ,943
-kinemotion/api.py,sha256=uj3py8jXuG3mYnmsZQnzuCQtWrO4O6gvZzGAMfZne4o,891
+kinemotion/api.py,sha256=q33-C6xlZKzXthjii1FKnschFU_WT60EHabRgczy3ic,1039
 kinemotion/cli.py,sha256=cqYV_7URH0JUDy1VQ_EDLv63FmNO4Ns20m6s1XAjiP4,464
 kinemotion/cmj/__init__.py,sha256=SkAw9ka8Yd1Qfv9hcvk22m3EfucROzYrSNGNF5kDzho,113
 kinemotion/cmj/analysis.py,sha256=3l0vYQB9tN4HtEO2MPFHVtrdzSmXgwpCm03qzYLCF0c,22196
-kinemotion/cmj/api.py,sha256=jFHBYgk05pZUG3FKAeMu-40DGROfRzXOeLQMrG4KUJk,15527
-kinemotion/cmj/cli.py,sha256=S4-3YmaCjtGutDwjG475h8nIiw5utiLg5L6hCGfLOHY,9926
+kinemotion/cmj/api.py,sha256=TYWja-Ellfyq_R2ixfvQyCWnPON7CG7IZk8odlLVM8E,16784
+kinemotion/cmj/cli.py,sha256=r3k5LDRXob12PV_6f6XnXOzKXoGn5WfeCMXkxiJ_CYE,10078
 kinemotion/cmj/debug_overlay.py,sha256=fXmWoHhqMLGo4vTtB6Ezs3yLUDOLw63zLIgU2gFlJQU,15892
 kinemotion/cmj/joint_angles.py,sha256=HmheIEiKcQz39cRezk4h-htorOhGNPsqKIR9RsAEKts,9960
 kinemotion/cmj/kinematics.py,sha256=Q-L8M7wG-MJ6EJTq6GO17c8sD5cb0Jg6Hc5vUZr14bA,13673
@@ -28,15 +28,15 @@ kinemotion/core/validation.py,sha256=LmKfSl4Ayw3DgwKD9IrhsPdzp5ia4drLsHA2UuU1SCM
 kinemotion/core/video_io.py,sha256=vCwpWnlW2y29l48dFXokdehQn42w_IQvayxbVTjpXqQ,7863
 kinemotion/dropjump/__init__.py,sha256=tC3H3BrCg8Oj-db-Vrtx4PH_llR1Ppkd5jwaOjhQcLg,862
 kinemotion/dropjump/analysis.py,sha256=p7nnCe7V6vnhQKZVYk--_nhsTvVa_WY-A3zXmyplsew,28211
-kinemotion/dropjump/api.py,sha256=9tetwjoFdY7Z8PqXpNfaS96L9YVqEkJl7jejGnewhbE,17517
-kinemotion/dropjump/cli.py,sha256=pPQkjpuPUUefGcsRuMvRTtjsxpPSqSgQ9K49rsN_X_o,15823
+kinemotion/dropjump/api.py,sha256=O8DSTLankRibFH8pf1A9idK0x9-khKpG1h2X5nlg5Ms,20688
+kinemotion/dropjump/cli.py,sha256=Ho80fSOgH8zo2e8dGQA90VXL-mZPVvnpc1ZKtl51vB0,16917
 kinemotion/dropjump/debug_overlay.py,sha256=8XVuDyZ3nuNoCYkxcUWC7wyEoHyBxx77Sb--B1KiYWw,5974
 kinemotion/dropjump/kinematics.py,sha256=PATlGaClutGKJslL-LRIXHmTsvb-xEB8PUIMScU_K4c,19849
 kinemotion/dropjump/metrics_validator.py,sha256=CrTlGup8q2kyPXtA6HNwm7_yq0AsBaDllG7RVZdXmYA,9342
 kinemotion/dropjump/validation_bounds.py,sha256=fyl04ZV7nfvHkL5eob6oEpV9Hxce6aiOWQ9pclLp7AQ,5077
 kinemotion/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kinemotion-0.47.3.dist-info/METADATA,sha256=LNbw4aGD3V6P3wkgH_Puury1B9D4kmwOOqKmkiCTo0Y,26020
-kinemotion-0.47.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-kinemotion-0.47.3.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
-kinemotion-0.47.3.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
-kinemotion-0.47.3.dist-info/RECORD,,
+kinemotion-0.48.0.dist-info/METADATA,sha256=xLTdYPgI6XtwGbaxYOnwpA0IZKfZkMF0ld48pP-rp7c,26020
+kinemotion-0.48.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+kinemotion-0.48.0.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
+kinemotion-0.48.0.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
+kinemotion-0.48.0.dist-info/RECORD,,