kinemotion 0.66.2__tar.gz → 0.66.4__tar.gz

{kinemotion-0.66.2 → kinemotion-0.66.4}/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## kinemotion-v0.66.4 (2025-12-19)
+
+### Refactor
+
+- reduce cognitive complexity in debug_overlay_utils and cmj api
+
+## kinemotion-v0.66.3 (2025-12-19)
+
+### Fix
+
+- remove duplicate 'message' parameter in _log call
+
 ## kinemotion-v0.66.2 (2025-12-19)
 
 ### Fix

{kinemotion-0.66.2 → kinemotion-0.66.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.66.2
+Version: 0.66.4
 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.66.2 → kinemotion-0.66.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kinemotion"
-version = "0.66.2"
+version = "0.66.4"
 description = "Video-based kinematic analysis for athletic performance"
 readme = "README.md"
 requires-python = ">=3.10,<3.13"

{kinemotion-0.66.2 → kinemotion-0.66.4}/src/kinemotion/cmj/api.py

@@ -214,6 +214,169 @@ def _create_result_metadata(
     )
 
 
+def _run_pose_tracking(
+    video: VideoProcessor,
+    quality_preset: QualityPreset,
+    detection_confidence: float | None,
+    tracking_confidence: float | None,
+    pose_tracker: PoseTracker | None,
+    verbose: bool,
+    timer: Timer,
+) -> tuple[list[NDArray[np.uint8]], list, list[int]]:
+    """Initialize tracker and process all frames."""
+    if verbose:
+        print(
+            f"Video: {video.width}x{video.height} @ {video.fps:.2f} fps, "
+            f"{video.frame_count} frames"
+        )
+
+    det_conf, track_conf = determine_confidence_levels(
+        quality_preset, detection_confidence, tracking_confidence
+    )
+
+    if verbose:
+        print("Processing all frames with MediaPipe pose tracking...")
+
+    tracker = pose_tracker or PoseTracker(
+        min_detection_confidence=det_conf,
+        min_tracking_confidence=track_conf,
+        timer=timer,
+    )
+    should_close_tracker = pose_tracker is None
+
+    return process_all_frames(video, tracker, verbose, timer, close_tracker=should_close_tracker)
+
+
+def _get_tuned_parameters(
+    video: VideoProcessor,
+    landmarks_sequence: list,
+    quality_preset: QualityPreset,
+    overrides: AnalysisOverrides | None,
+    verbose: bool,
+    timer: Timer,
+) -> AnalysisParameters:
+    """Analyze sample and tune parameters with expert overrides."""
+    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,
+            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)
+
+    return params
+
+
+def _run_kinematic_analysis(
+    video: VideoProcessor,
+    smoothed_landmarks: list,
+    params: AnalysisParameters,
+    verbose: bool,
+    timer: Timer,
+) -> tuple[CMJMetrics, NDArray[np.float64], NDArray[np.float64]]:
+    """Extract positions, detect phases, and calculate metrics."""
+    if verbose:
+        print("Extracting vertical positions (Hip and Foot)...")
+    with timer.measure("vertical_position_extraction"):
+        vertical_positions, visibilities = extract_vertical_positions(
+            smoothed_landmarks, target="hip"
+        )
+        foot_positions, _ = extract_vertical_positions(smoothed_landmarks, target="foot")
+
+    if verbose:
+        print("Detecting CMJ phases...")
+    with timer.measure("phase_detection"):
+        phases = detect_cmj_phases(
+            vertical_positions,
+            video.fps,
+            window_length=params.smoothing_window,
+            polyorder=params.polyorder,
+            landing_positions=foot_positions,
+            timer=timer,
+        )
+
+    if phases is None:
+        raise ValueError("Could not detect CMJ phases in video")
+
+    standing_end, lowest_point, takeoff_frame, landing_frame = phases
+
+    if verbose:
+        print("Calculating metrics...")
+    with timer.measure("metrics_calculation"):
+        velocities = compute_signed_velocity(
+            vertical_positions,
+            window_length=params.smoothing_window,
+            polyorder=params.polyorder,
+        )
+        metrics = calculate_cmj_metrics(
+            vertical_positions,
+            velocities,
+            standing_end,
+            lowest_point,
+            takeoff_frame,
+            landing_frame,
+            video.fps,
+            tracking_method="hip_hybrid",
+        )
+
+    return metrics, vertical_positions, visibilities
+
+
+def _finalize_analysis_results(
+    metrics: CMJMetrics,
+    video: VideoProcessor,
+    video_path: str,
+    vertical_positions: NDArray[np.float64],
+    visibilities: NDArray[np.float64],
+    params: AnalysisParameters,
+    quality_preset: QualityPreset,
+    start_time: float,
+    timer: Timer,
+    verbose: bool,
+) -> None:
+    """Assess quality, validate metrics, and attach metadata."""
+    if verbose:
+        print("Assessing tracking quality...")
+    with timer.measure("quality_assessment"):
+        _, outlier_mask = reject_outliers(
+            vertical_positions,
+            use_ransac=True,
+            use_median=True,
+            interpolate=False,
+        )
+        quality_result = assess_jump_quality(
+            visibilities=visibilities,
+            positions=vertical_positions,
+            outlier_mask=outlier_mask,
+            fps=video.fps,
+            phases_detected=True,
+            phase_count=4,
+        )
+
+    _print_quality_warnings(quality_result, verbose)
+
+    with timer.measure("metrics_validation"):
+        validator = CMJMetricsValidator()
+        validation_result = validator.validate(metrics.to_dict())  # type: ignore[arg-type]
+        metrics.validation_result = validation_result
+
+    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
+
+    _print_validation_results(validation_result, verbose)
+
+
 @dataclass
 class CMJVideoConfig:
     """Configuration for processing a single CMJ video."""
@@ -285,112 +448,29 @@ def process_cmj_video(
 
     with timer.measure("video_initialization"):
         with VideoProcessor(video_path, timer=timer) as video:
-            if verbose:
-                print(
-                    f"Video: {video.width}x{video.height} @ {video.fps:.2f} fps, "
-                    f"{video.frame_count} frames"
-                )
-
-            det_conf, track_conf = determine_confidence_levels(
-                quality_preset, detection_confidence, tracking_confidence
-            )
-
-            if verbose:
-                print("Processing all frames with MediaPipe pose tracking...")
-
-            tracker = pose_tracker or PoseTracker(
-                min_detection_confidence=det_conf,
-                min_tracking_confidence=track_conf,
-                timer=timer,
+            # 1. Pose Tracking
+            frames, landmarks_sequence, frame_indices = _run_pose_tracking(
+                video,
+                quality_preset,
+                detection_confidence,
+                tracking_confidence,
+                pose_tracker,
+                verbose,
+                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
+            # 2. Parameters & Smoothing
+            params = _get_tuned_parameters(
+                video, landmarks_sequence, quality_preset, overrides, 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,
-                    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)
-
             smoothed_landmarks = apply_smoothing(landmarks_sequence, params, verbose, timer)
 
-            if verbose:
-                print("Extracting vertical positions (Hip and Foot)...")
-            with timer.measure("vertical_position_extraction"):
-                vertical_positions, visibilities = extract_vertical_positions(
-                    smoothed_landmarks, target="hip"
-                )
-                foot_positions, _ = extract_vertical_positions(smoothed_landmarks, target="foot")
-
-            if verbose:
-                print("Detecting CMJ phases...")
-            with timer.measure("phase_detection"):
-                phases = detect_cmj_phases(
-                    vertical_positions,
-                    video.fps,
-                    window_length=params.smoothing_window,
-                    polyorder=params.polyorder,
-                    landing_positions=foot_positions,
-                    timer=timer,
-                )
-
-            if phases is None:
-                raise ValueError("Could not detect CMJ phases in video")
-
-            standing_end, lowest_point, takeoff_frame, landing_frame = phases
-
-            if verbose:
-                print("Calculating metrics...")
-            with timer.measure("metrics_calculation"):
-                velocities = compute_signed_velocity(
-                    vertical_positions,
-                    window_length=params.smoothing_window,
-                    polyorder=params.polyorder,
-                )
-                metrics = calculate_cmj_metrics(
-                    vertical_positions,
-                    velocities,
-                    standing_end,
-                    lowest_point,
-                    takeoff_frame,
-                    landing_frame,
-                    video.fps,
-                    tracking_method="hip_hybrid",
-                )
-
-            if verbose:
-                print("Assessing tracking quality...")
-            with timer.measure("quality_assessment"):
-                _, outlier_mask = reject_outliers(
-                    vertical_positions,
-                    use_ransac=True,
-                    use_median=True,
-                    interpolate=False,
-                )
-                quality_result = assess_jump_quality(
-                    visibilities=visibilities,
-                    positions=vertical_positions,
-                    outlier_mask=outlier_mask,
-                    fps=video.fps,
-                    phases_detected=True,
-                    phase_count=4,
-                )
-
-            _print_quality_warnings(quality_result, verbose)
+            # 3. Kinematic Analysis
+            metrics, vertical_positions, visibilities = _run_kinematic_analysis(
+                video, smoothed_landmarks, params, verbose, timer
+            )
 
+            # 4. Debug Video Generation (Optional)
             if output_video:
                 _generate_debug_video(
                     output_video,
@@ -403,24 +483,23 @@ def process_cmj_video(
                     verbose,
                 )
 
-            with timer.measure("metrics_validation"):
-                validator = CMJMetricsValidator()
-                validation_result = validator.validate(metrics.to_dict())  # type: ignore[arg-type]
-                metrics.validation_result = validation_result
-
-            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
+            # 5. Finalization (Quality, Metadata, Validation)
+            _finalize_analysis_results(
+                metrics,
+                video,
+                video_path,
+                vertical_positions,
+                visibilities,
+                params,
+                quality_preset,
+                start_time,
+                timer,
+                verbose,
             )
-            metrics.result_metadata = result_metadata
 
             if json_output:
                 _save_metrics_to_json(metrics, json_output, timer, verbose)
 
-            _print_validation_results(validation_result, verbose)
-
             if verbose:
                 _print_timing_summary(start_time, timer, metrics)
 

{kinemotion-0.66.2 → kinemotion-0.66.4}/src/kinemotion/core/debug_overlay_utils.py

@@ -6,6 +6,7 @@ import shutil
 import subprocess
 import time
 from pathlib import Path
+from typing import Any
 
 import cv2
 import numpy as np
@@ -73,53 +74,67 @@ def create_video_writer(
     # ⚠️  CRITICAL: VP9 (vp09) is EXCLUDED - not supported on iOS/iPhone/iPad browsers!
     #     Adding VP9 will break debug video playback on all iOS devices.
     codecs_to_try = ["avc1", "mp4v"]
-
-    writer = None
-    used_codec = "mp4v"  # Default fallback
-    codec_attempt_log = []
+    codec_attempt_log: list[dict[str, Any]] = []
 
     for codec in codecs_to_try:
-        try:
-            fourcc = cv2.VideoWriter_fourcc(*codec)  # type: ignore[attr-defined]
-            writer = cv2.VideoWriter(output_path, fourcc, fps, (display_width, display_height))
-            if writer.isOpened():
-                used_codec = codec
-                codec_attempt_log.append({"codec": codec, "status": "success"})
-                _log(
-                    "info",
-                    "debug_video_codec_selected",
-                    codec=codec,
-                    width=display_width,
-                    height=display_height,
-                    fps=fps,
-                )
-                if codec == "mp4v":
-                    msg = (
-                        "Using fallback MPEG-4 codec; will re-encode with ffmpeg for "
-                        "browser compatibility"
-                    )
-                    _log("warning", "debug_video_fallback_codec", codec="mp4v", message=msg)
-                break
-        except Exception as e:
-            codec_attempt_log.append({"codec": codec, "status": "failed", "error": str(e)})
-            _log("info", "debug_video_codec_attempt_failed", codec=codec, error=str(e))
-            continue
-
-    if writer is None or not writer.isOpened():
-        _log(
-            "error",
-            "debug_video_writer_creation_failed",
-            output_path=output_path,
-            dimensions=f"{display_width}x{display_height}",
-            fps=fps,
-            codec_attempts=codec_attempt_log,
+        writer = _try_open_video_writer(
+            output_path, codec, fps, display_width, display_height, codec_attempt_log
         )
-        raise ValueError(
-            f"Failed to create video writer for {output_path} with dimensions "
-            f"{display_width}x{display_height}"
+        if writer:
+            return writer, needs_resize, codec
+
+    _log(
+        "error",
+        "debug_video_writer_creation_failed",
+        output_path=output_path,
+        dimensions=f"{display_width}x{display_height}",
+        fps=fps,
+        codec_attempts=codec_attempt_log,
+    )
+    raise ValueError(
+        f"Failed to create video writer for {output_path} with dimensions "
+        f"{display_width}x{display_height}"
+    )
+
+
+def _try_open_video_writer(
+    output_path: str,
+    codec: str,
+    fps: float,
+    width: int,
+    height: int,
+    attempt_log: list[dict[str, Any]],
+) -> cv2.VideoWriter | None:
+    """Attempt to open a video writer with a specific codec."""
+    try:
+        fourcc = cv2.VideoWriter_fourcc(*codec)  # type: ignore[attr-defined]
+        writer = cv2.VideoWriter(output_path, fourcc, fps, (width, height))
+        if writer.isOpened():
+            attempt_log.append({"codec": codec, "status": "success"})
+            _log(
+                "info",
+                "debug_video_codec_selected",
+                codec=codec,
+                width=width,
+                height=height,
+                fps=fps,
+            )
+            if codec == "mp4v":
+                msg = (
+                    "Using fallback MPEG-4 codec; will re-encode with ffmpeg for "
+                    "browser compatibility"
+                )
+                _log("warning", "debug_video_fallback_codec", codec="mp4v", warning=msg)
+            return writer
+
+        attempt_log.append(
+            {"codec": codec, "status": "failed", "error": "isOpened() returned False"}
         )
+    except Exception as e:
+        attempt_log.append({"codec": codec, "status": "failed", "error": str(e)})
+        _log("info", "debug_video_codec_attempt_failed", codec=codec, error=str(e))
 
-    return writer, needs_resize, used_codec
+    return None
 
 
 def write_overlay_frame(
@@ -262,92 +277,17 @@ class BaseDebugOverlayRenderer:
             codec=self.used_codec,
         )
 
-        # Post-process with ffmpeg ONLY if we fell back to the incompatible mp4v codec
-        if self.used_codec == "mp4v" and shutil.which("ffmpeg"):
-            temp_path = None
-            try:
-                temp_path = str(
-                    Path(self.output_path).with_suffix(".temp" + Path(self.output_path).suffix)
-                )
-
-                # Convert to H.264 with yuv420p pixel format for browser compatibility
-                # -y: Overwrite output file
-                # -vcodec libx264: Use H.264 codec
-                # -pix_fmt yuv420p: Required for wide browser support (Chrome,
-                #                   Safari, Firefox, iOS)
-                # -preset fast: Reasonable speed/compression tradeoff
-                # -crf 23: Standard quality
-                # -an: Remove audio (debug video has no audio)
-                cmd = [
-                    "ffmpeg",
-                    "-y",
-                    "-i",
-                    self.output_path,
-                    "-vcodec",
-                    "libx264",
-                    "-pix_fmt",
-                    "yuv420p",
-                    "-preset",
-                    "fast",
-                    "-crf",
-                    "23",
-                    "-an",
-                    temp_path,
-                ]
-
-                _log(
-                    "info",
-                    "debug_video_ffmpeg_reencoding_start",
-                    input_file=self.output_path,
-                    output_file=temp_path,
-                    output_codec="libx264",
-                    pixel_format="yuv420p",
-                    reason="iOS_compatibility",
-                )
-
-                # Suppress output unless error
-                reencode_start = time.time()
-                subprocess.run(
-                    cmd,
-                    check=True,
-                    stdout=subprocess.DEVNULL,
-                    stderr=subprocess.PIPE,
-                )
-                self.reencode_duration_s = time.time() - reencode_start
-
-                _log(
-                    "info",
-                    "debug_video_ffmpeg_reencoding_complete",
-                    duration_ms=round(self.reencode_duration_s * 1000, 1),
-                )
-
-                # Overwrite original file
-                os.replace(temp_path, self.output_path)
-                _log(
-                    "info",
-                    "debug_video_reencoded_file_replaced",
-                    output_path=self.output_path,
-                    final_codec="libx264",
-                    pixel_format="yuv420p",
-                )
+        if self.used_codec != "mp4v":
+            _log(
+                "info",
+                "debug_video_ready_for_playback",
+                codec=self.used_codec,
+                path=self.output_path,
+            )
+            return
 
-            except subprocess.CalledProcessError as e:
-                stderr_msg = e.stderr.decode("utf-8", errors="ignore") if e.stderr else "N/A"
-                _log(
-                    "warning",
-                    "debug_video_ffmpeg_reencoding_failed",
-                    error=str(e),
-                    stderr=stderr_msg,
-                )
-                if temp_path and os.path.exists(temp_path):
-                    os.remove(temp_path)
-                    _log("info", "debug_video_temp_file_cleaned_up", temp_file=temp_path)
-            except Exception as e:
-                _log("warning", "debug_video_post_processing_error", error=str(e))
-                if temp_path and os.path.exists(temp_path):
-                    os.remove(temp_path)
-                    _log("info", "debug_video_temp_file_cleaned_up", temp_file=temp_path)
-        elif self.used_codec == "mp4v" and not shutil.which("ffmpeg"):
+        ffmpeg_path = shutil.which("ffmpeg")
+        if not ffmpeg_path:
             _log(
                 "warning",
                 "debug_video_ffmpeg_not_available",
@@ -355,13 +295,88 @@ class BaseDebugOverlayRenderer:
                 output_path=self.output_path,
                 warning="Video may not play in all browsers",
             )
-        else:
+            return
+
+        self._reencode_to_h264()
+
+    def _reencode_to_h264(self) -> None:
+        """Re-encode video to H.264 for browser compatibility using ffmpeg."""
+        temp_path = str(
+            Path(self.output_path).with_suffix(".temp" + Path(self.output_path).suffix)
+        )
+
+        # Convert to H.264 with yuv420p pixel format for browser compatibility
+        # -y: Overwrite output file
+        # -vcodec libx264: Use H.264 codec
+        # -pix_fmt yuv420p: Required for wide browser support (Chrome, Safari, Firefox, iOS)
+        # -preset fast: Reasonable speed/compression tradeoff
+        # -crf 23: Standard quality
+        # -an: Remove audio (debug video has no audio)
+        cmd = [
+            "ffmpeg",
+            "-y",
+            "-i",
+            self.output_path,
+            "-vcodec",
+            "libx264",
+            "-pix_fmt",
+            "yuv420p",
+            "-preset",
+            "fast",
+            "-crf",
+            "23",
+            "-an",
+            temp_path,
+        ]
+
+        _log(
+            "info",
+            "debug_video_ffmpeg_reencoding_start",
+            input_file=self.output_path,
+            output_file=temp_path,
+            output_codec="libx264",
+            pixel_format="yuv420p",
+            reason="iOS_compatibility",
+        )
+
+        try:
+            reencode_start = time.time()
+            subprocess.run(cmd, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)
+            self.reencode_duration_s = time.time() - reencode_start
+
             _log(
                 "info",
-                "debug_video_ready_for_playback",
-                codec=self.used_codec,
-                path=self.output_path,
+                "debug_video_ffmpeg_reencoding_complete",
+                duration_ms=round(self.reencode_duration_s * 1000, 1),
+            )
+
+            os.replace(temp_path, self.output_path)
+            _log(
+                "info",
+                "debug_video_reencoded_file_replaced",
+                output_path=self.output_path,
+                final_codec="libx264",
+                pixel_format="yuv420p",
             )
+        except (subprocess.CalledProcessError, Exception) as e:
+            self._handle_reencode_error(e, temp_path)
+
+    def _handle_reencode_error(self, e: Exception, temp_path: str) -> None:
+        """Handle errors during ffmpeg re-encoding."""
+        if isinstance(e, subprocess.CalledProcessError):
+            stderr_msg = e.stderr.decode("utf-8", errors="ignore") if e.stderr else "N/A"
+            _log(
+                "warning",
+                "debug_video_ffmpeg_reencoding_failed",
+                error=str(e),
+                stderr=stderr_msg,
+            )
+        else:
+            _log("warning", "debug_video_post_processing_error", error=str(e))
+
+        if os.path.exists(temp_path):
+            os.remove(temp_path)
+            _log("info", "debug_video_temp_file_cleaned_up", temp_file=temp_path)
 
     def __enter__(self) -> Self:
         return self