kinemotion 0.11.4__py3-none-any.whl → 0.11.6__py3-none-any.whl

kinemotion/cmj/cli.py

@@ -10,16 +10,15 @@ from typing import Any
 import click
 import numpy as np
 
-from ..core.auto_tuning import (
-    AnalysisParameters as AutoTunedParams,
-)
 from ..core.auto_tuning import (
     QualityPreset,
     analyze_video_sample,
     auto_tune_parameters,
 )
 from ..core.cli_utils import (
+    apply_expert_param_overrides,
     determine_initial_confidence,
+    print_auto_tuned_params,
     smooth_landmark_sequence,
     track_all_frames,
 )
@@ -299,50 +298,6 @@ def cmj_analyze(  # NOSONAR(S107) - Click CLI requires individual parameters for
             sys.exit(1)
 
 
-def _apply_expert_param_overrides(
-    params: AutoTunedParams, expert_params: AnalysisParameters
-) -> AutoTunedParams:
-    """Apply expert parameter overrides to auto-tuned parameters."""
-    if expert_params.smoothing_window is not None:
-        params.smoothing_window = expert_params.smoothing_window
-    if expert_params.velocity_threshold is not None:
-        params.velocity_threshold = expert_params.velocity_threshold
-    if expert_params.min_contact_frames is not None:
-        params.min_contact_frames = expert_params.min_contact_frames
-    if expert_params.visibility_threshold is not None:
-        params.visibility_threshold = expert_params.visibility_threshold
-    return params
-
-
-def _print_auto_tuned_params(
-    video: VideoProcessor,
-    quality_preset: QualityPreset,
-    params: AutoTunedParams,
-    countermovement_threshold: float,
-) -> None:
-    """Print auto-tuned parameters in verbose mode."""
-    click.echo("\n" + "=" * 60, err=True)
-    click.echo("AUTO-TUNED PARAMETERS", err=True)
-    click.echo("=" * 60, err=True)
-    click.echo(f"Video FPS: {video.fps:.2f}", err=True)
-    click.echo(f"Quality preset: {quality_preset.value}", err=True)
-    click.echo("\nSelected parameters:", err=True)
-    click.echo(f"  smoothing_window: {params.smoothing_window}", err=True)
-    click.echo(f"  polyorder: {params.polyorder}", err=True)
-    click.echo(f"  velocity_threshold: {params.velocity_threshold:.4f}", err=True)
-    click.echo(
-        f"  countermovement_threshold: {countermovement_threshold:.4f}", err=True
-    )
-    click.echo(f"  min_contact_frames: {params.min_contact_frames}", err=True)
-    click.echo(f"  visibility_threshold: {params.visibility_threshold}", err=True)
-    click.echo(f"  detection_confidence: {params.detection_confidence}", err=True)
-    click.echo(f"  tracking_confidence: {params.tracking_confidence}", err=True)
-    click.echo(f"  outlier_rejection: {params.outlier_rejection}", err=True)
-    click.echo(f"  bilateral_filter: {params.bilateral_filter}", err=True)
-    click.echo(f"  use_curvature: {params.use_curvature}", err=True)
-    click.echo("=" * 60 + "\n", err=True)
-
-
 def _get_foot_position(frame_landmarks: dict | None, last_position: float) -> float:
     """Extract average foot position from frame landmarks."""
     if not frame_landmarks:
@@ -419,7 +374,7 @@ def _process_single(
                 landmarks_sequence, video.fps, video.frame_count
             )
             params = auto_tune_parameters(characteristics, quality_preset)
-            params = _apply_expert_param_overrides(params, expert_params)
+            params = apply_expert_param_overrides(params, expert_params)
 
             # Calculate countermovement threshold (FPS-adjusted)
             # Base: +0.015 at 30fps (POSITIVE for downward motion in normalized coords)
@@ -429,8 +384,13 @@ def _process_single(
 
             # Show parameters if verbose
             if verbose:
-                _print_auto_tuned_params(
-                    video, quality_preset, params, countermovement_threshold
+                print_auto_tuned_params(
+                    video,
+                    quality_preset,
+                    params,
+                    extra_params={
+                        "countermovement_threshold": countermovement_threshold
+                    },
                 )
 
             # Apply smoothing

kinemotion/cmj/debug_overlay.py

@@ -3,6 +3,7 @@
 import cv2
 import numpy as np
 
+from ..core.debug_overlay_utils import BaseDebugOverlayRenderer
 from .joint_angles import calculate_triple_extension
 from .kinematics import CMJMetrics
 
@@ -18,54 +19,9 @@ class CMJPhaseState:
     LANDING = "landing"
 
 
-class CMJDebugOverlayRenderer:
+class CMJDebugOverlayRenderer(BaseDebugOverlayRenderer):
     """Renders debug information on CMJ video frames."""
 
-    def __init__(
-        self,
-        output_path: str,
-        width: int,
-        height: int,
-        display_width: int,
-        display_height: int,
-        fps: float,
-    ):
-        """
-        Initialize overlay renderer.
-
-        Args:
-            output_path: Path for output video
-            width: Encoded frame width (from source video)
-            height: Encoded frame height (from source video)
-            display_width: Display width (considering SAR)
-            display_height: Display height (considering SAR)
-            fps: Frames per second
-        """
-        self.width = width
-        self.height = height
-        self.display_width = display_width
-        self.display_height = display_height
-        self.needs_resize = (display_width != width) or (display_height != height)
-
-        # Try H.264 codec first (better quality/compatibility), fallback to mp4v
-        fourcc = cv2.VideoWriter_fourcc(*"avc1")
-        self.writer = cv2.VideoWriter(
-            output_path, fourcc, fps, (display_width, display_height)
-        )
-
-        # Check if writer opened successfully, fallback to mp4v if not
-        if not self.writer.isOpened():
-            fourcc = cv2.VideoWriter_fourcc(*"mp4v")
-            self.writer = cv2.VideoWriter(
-                output_path, fourcc, fps, (display_width, display_height)
-            )
-
-        if not self.writer.isOpened():
-            raise ValueError(
-                f"Failed to create video writer for {output_path} with dimensions "
-                f"{display_width}x{display_height}"
-            )
-
     def _determine_phase(self, frame_idx: int, metrics: CMJMetrics) -> str:
         """Determine which phase the current frame is in."""
         if metrics.standing_start_frame and frame_idx < metrics.standing_start_frame:
@@ -508,42 +464,3 @@ class CMJDebugOverlayRenderer:
             self._draw_metrics_summary(annotated, frame_idx, metrics)
 
         return annotated
-
-    def write_frame(self, frame: np.ndarray) -> None:
-        """
-        Write frame to output video.
-
-        Args:
-            frame: Video frame with shape (height, width, 3)
-
-        Raises:
-            ValueError: If frame dimensions don't match expected encoded dimensions
-        """
-        # Validate frame dimensions match expected encoded dimensions
-        frame_height, frame_width = frame.shape[:2]
-        if frame_height != self.height or frame_width != self.width:
-            raise ValueError(
-                f"Frame dimensions ({frame_width}x{frame_height}) don't match "
-                f"source dimensions ({self.width}x{self.height}). "
-                f"Aspect ratio must be preserved from source video."
-            )
-
-        # Resize to display dimensions if needed (to handle SAR)
-        if self.needs_resize:
-            frame = cv2.resize(
-                frame,
-                (self.display_width, self.display_height),
-                interpolation=cv2.INTER_LANCZOS4,
-            )
-
-        self.writer.write(frame)
-
-    def close(self) -> None:
-        """Release video writer."""
-        self.writer.release()
-
-    def __enter__(self) -> "CMJDebugOverlayRenderer":
-        return self
-
-    def __exit__(self, exc_type: type, exc_val: Exception, exc_tb: object) -> None:
-        self.close()

kinemotion/core/cli_utils.py

@@ -4,7 +4,7 @@ from typing import Any, Protocol
 
 import click
 
-from .auto_tuning import AutoTunedParams, QualityPreset
+from .auto_tuning import AutoTunedParams, QualityPreset, VideoCharacteristics
 from .pose import PoseTracker
 from .smoothing import smooth_landmarks, smooth_landmarks_advanced
 from .video_io import VideoProcessor
@@ -15,6 +15,10 @@ class ExpertParameters(Protocol):
 
     detection_confidence: float | None
     tracking_confidence: float | None
+    smoothing_window: int | None
+    velocity_threshold: float | None
+    min_contact_frames: int | None
+    visibility_threshold: float | None
 
 
 def determine_initial_confidence(
@@ -79,6 +83,81 @@ def track_all_frames(video: VideoProcessor, tracker: PoseTracker) -> tuple[list,
     return frames, landmarks_sequence
 
 
+def apply_expert_param_overrides(
+    params: AutoTunedParams, expert_params: ExpertParameters
+) -> AutoTunedParams:
+    """Apply expert parameter overrides to auto-tuned parameters.
+
+    Args:
+        params: Auto-tuned parameters
+        expert_params: Expert overrides
+
+    Returns:
+        Modified params object (mutated in place)
+    """
+    if expert_params.smoothing_window is not None:
+        params.smoothing_window = expert_params.smoothing_window
+    if expert_params.velocity_threshold is not None:
+        params.velocity_threshold = expert_params.velocity_threshold
+    if expert_params.min_contact_frames is not None:
+        params.min_contact_frames = expert_params.min_contact_frames
+    if expert_params.visibility_threshold is not None:
+        params.visibility_threshold = expert_params.visibility_threshold
+    return params
+
+
+def print_auto_tuned_params(
+    video: VideoProcessor,
+    quality_preset: QualityPreset,
+    params: AutoTunedParams,
+    characteristics: VideoCharacteristics | None = None,
+    extra_params: dict[str, Any] | None = None,
+) -> None:
+    """Print auto-tuned parameters in verbose mode.
+
+    Args:
+        video: Video processor
+        quality_preset: Quality preset
+        params: Auto-tuned parameters
+        characteristics: Optional video characteristics (for tracking quality display)
+        extra_params: Optional extra parameters to display (e.g., countermovement_threshold)
+    """
+    click.echo("\n" + "=" * 60, err=True)
+    click.echo("AUTO-TUNED PARAMETERS", err=True)
+    click.echo("=" * 60, err=True)
+    click.echo(f"Video FPS: {video.fps:.2f}", err=True)
+
+    if characteristics:
+        click.echo(
+            f"Tracking quality: {characteristics.tracking_quality} "
+            f"(avg visibility: {characteristics.avg_visibility:.2f})",
+            err=True,
+        )
+
+    click.echo(f"Quality preset: {quality_preset.value}", err=True)
+    click.echo("\nSelected parameters:", err=True)
+    click.echo(f"  smoothing_window: {params.smoothing_window}", err=True)
+    click.echo(f"  polyorder: {params.polyorder}", err=True)
+    click.echo(f"  velocity_threshold: {params.velocity_threshold:.4f}", err=True)
+
+    # Print extra parameters if provided
+    if extra_params:
+        for key, value in extra_params.items():
+            if isinstance(value, float):
+                click.echo(f"  {key}: {value:.4f}", err=True)
+            else:
+                click.echo(f"  {key}: {value}", err=True)
+
+    click.echo(f"  min_contact_frames: {params.min_contact_frames}", err=True)
+    click.echo(f"  visibility_threshold: {params.visibility_threshold}", err=True)
+    click.echo(f"  detection_confidence: {params.detection_confidence}", err=True)
+    click.echo(f"  tracking_confidence: {params.tracking_confidence}", err=True)
+    click.echo(f"  outlier_rejection: {params.outlier_rejection}", err=True)
+    click.echo(f"  bilateral_filter: {params.bilateral_filter}", err=True)
+    click.echo(f"  use_curvature: {params.use_curvature}", err=True)
+    click.echo("=" * 60 + "\n", err=True)
+
+
 def smooth_landmark_sequence(landmarks_sequence: list, params: AutoTunedParams) -> list:
     """Apply smoothing to landmark sequence.
 

kinemotion/core/debug_overlay_utils.py

@@ -0,0 +1,166 @@
+"""Shared debug overlay utilities for video rendering."""
+
+import cv2
+import numpy as np
+
+
+def create_video_writer(
+    output_path: str,
+    width: int,
+    height: int,
+    display_width: int,
+    display_height: int,
+    fps: float,
+) -> tuple[cv2.VideoWriter, bool]:
+    """
+    Create a video writer with fallback codec support.
+
+    Args:
+        output_path: Path for output video
+        width: Encoded frame width (from source video)
+        height: Encoded frame height (from source video)
+        display_width: Display width (considering SAR)
+        display_height: Display height (considering SAR)
+        fps: Frames per second
+
+    Returns:
+        Tuple of (video_writer, needs_resize)
+    """
+    needs_resize = (display_width != width) or (display_height != height)
+
+    # Try H.264 codec first (better quality/compatibility), fallback to mp4v
+    fourcc = cv2.VideoWriter_fourcc(*"avc1")
+    writer = cv2.VideoWriter(output_path, fourcc, fps, (display_width, display_height))
+
+    # Check if writer opened successfully, fallback to mp4v if not
+    if not writer.isOpened():
+        fourcc = cv2.VideoWriter_fourcc(*"mp4v")
+        writer = cv2.VideoWriter(
+            output_path, fourcc, fps, (display_width, display_height)
+        )
+
+    if not writer.isOpened():
+        raise ValueError(
+            f"Failed to create video writer for {output_path} with dimensions "
+            f"{display_width}x{display_height}"
+        )
+
+    return writer, needs_resize
+
+
+def prepare_frame_for_overlay(
+    frame: np.ndarray, needs_resize: bool, display_width: int, display_height: int
+) -> np.ndarray:
+    """
+    Prepare frame for overlay rendering by resizing if needed.
+
+    Args:
+        frame: Original video frame
+        needs_resize: Whether frame needs resizing
+        display_width: Target display width
+        display_height: Target display height
+
+    Returns:
+        Prepared frame ready for overlay
+    """
+    # Apply SAR correction if needed
+    if needs_resize:
+        frame = cv2.resize(
+            frame, (display_width, display_height), interpolation=cv2.INTER_LINEAR
+        )
+    return frame
+
+
+def write_overlay_frame(
+    writer: cv2.VideoWriter, frame: np.ndarray, width: int, height: int
+) -> None:
+    """
+    Write a frame to the video writer with dimension validation.
+
+    Args:
+        writer: Video writer instance
+        frame: Frame to write
+        width: Expected frame width
+        height: Expected frame height
+
+    Raises:
+        ValueError: If frame dimensions don't match expected dimensions
+    """
+    # Validate dimensions before writing
+    if frame.shape[0] != height or frame.shape[1] != width:
+        raise ValueError(
+            f"Frame dimensions {frame.shape[1]}x{frame.shape[0]} do not match "
+            f"expected dimensions {width}x{height}"
+        )
+    writer.write(frame)
+
+
+class BaseDebugOverlayRenderer:
+    """Base class for debug overlay renderers with common functionality."""
+
+    def __init__(
+        self,
+        output_path: str,
+        width: int,
+        height: int,
+        display_width: int,
+        display_height: int,
+        fps: float,
+    ):
+        """
+        Initialize overlay renderer.
+
+        Args:
+            output_path: Path for output video
+            width: Encoded frame width (from source video)
+            height: Encoded frame height (from source video)
+            display_width: Display width (considering SAR)
+            display_height: Display height (considering SAR)
+            fps: Frames per second
+        """
+        self.width = width
+        self.height = height
+        self.display_width = display_width
+        self.display_height = display_height
+        self.writer, self.needs_resize = create_video_writer(
+            output_path, width, height, display_width, display_height, fps
+        )
+
+    def write_frame(self, frame: np.ndarray) -> None:
+        """
+        Write frame to output video.
+
+        Args:
+            frame: Video frame with shape (height, width, 3)
+
+        Raises:
+            ValueError: If frame dimensions don't match expected encoded dimensions
+        """
+        # Validate frame dimensions match expected encoded dimensions
+        frame_height, frame_width = frame.shape[:2]
+        if frame_height != self.height or frame_width != self.width:
+            raise ValueError(
+                f"Frame dimensions ({frame_width}x{frame_height}) don't match "
+                f"source dimensions ({self.width}x{self.height}). "
+                f"Aspect ratio must be preserved from source video."
+            )
+
+        # Resize to display dimensions if needed (to handle SAR)
+        if self.needs_resize:
+            frame = cv2.resize(
+                frame,
+                (self.display_width, self.display_height),
+                interpolation=cv2.INTER_LANCZOS4,
+            )
+
+        write_overlay_frame(self.writer, frame, self.display_width, self.display_height)
+
+    def close(self) -> None:
+        """Release video writer."""
+        self.writer.release()
+
+    def __enter__(self) -> "BaseDebugOverlayRenderer":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:  # type: ignore[no-untyped-def]
+        self.close()

kinemotion/core/smoothing.py

@@ -9,97 +9,199 @@ from .filtering import (
 )
 
 
-def smooth_landmarks(
+def _extract_landmark_coordinates(
     landmark_sequence: list[dict[str, tuple[float, float, float]] | None],
-    window_length: int = 5,
-    polyorder: int = 2,
-) -> list[dict[str, tuple[float, float, float]] | None]:
+    landmark_name: str,
+) -> tuple[list[float], list[float], list[int]]:
     """
-    Smooth landmark trajectories using Savitzky-Golay filter.
+    Extract x, y coordinates and valid frame indices for a specific landmark.
 
     Args:
         landmark_sequence: List of landmark dictionaries from each frame
-        window_length: Length of filter window (must be odd, >= polyorder + 2)
-        polyorder: Order of polynomial used to fit samples
+        landmark_name: Name of the landmark to extract
 
     Returns:
-        Smoothed landmark sequence with same structure as input
+        Tuple of (x_coords, y_coords, valid_frames)
     """
-    if len(landmark_sequence) < window_length:
-        # Not enough frames to smooth effectively
-        return landmark_sequence
+    x_coords = []
+    y_coords = []
+    valid_frames = []
+
+    for i, frame_landmarks in enumerate(landmark_sequence):
+        if frame_landmarks is not None and landmark_name in frame_landmarks:
+            x, y, _ = frame_landmarks[landmark_name]  # vis not used
+            x_coords.append(x)
+            y_coords.append(y)
+            valid_frames.append(i)
+
+    return x_coords, y_coords, valid_frames
 
-    # Ensure window_length is odd
-    if window_length % 2 == 0:
-        window_length += 1
 
-    # Extract landmark names from first valid frame
-    landmark_names = None
+def _get_landmark_names(
+    landmark_sequence: list[dict[str, tuple[float, float, float]] | None],
+) -> list[str] | None:
+    """
+    Extract landmark names from first valid frame.
+
+    Args:
+        landmark_sequence: List of landmark dictionaries from each frame
+
+    Returns:
+        List of landmark names or None if no valid frame found
+    """
     for frame_landmarks in landmark_sequence:
         if frame_landmarks is not None:
-            landmark_names = list(frame_landmarks.keys())
-            break
+            return list(frame_landmarks.keys())
+    return None
+
+
+def _fill_missing_frames(
+    smoothed_sequence: list[dict[str, tuple[float, float, float]] | None],
+    landmark_sequence: list[dict[str, tuple[float, float, float]] | None],
+) -> None:
+    """
+    Fill in any missing frames in smoothed sequence with original data.
+
+    Args:
+        smoothed_sequence: Smoothed sequence (modified in place)
+        landmark_sequence: Original sequence
+    """
+    for i in range(len(landmark_sequence)):
+        if i >= len(smoothed_sequence) or not smoothed_sequence[i]:
+            if i < len(smoothed_sequence):
+                smoothed_sequence[i] = landmark_sequence[i]
+            else:
+                smoothed_sequence.append(landmark_sequence[i])
+
+
+def _store_smoothed_landmarks(
+    smoothed_sequence: list[dict[str, tuple[float, float, float]] | None],
+    landmark_sequence: list[dict[str, tuple[float, float, float]] | None],
+    landmark_name: str,
+    x_smooth: np.ndarray,
+    y_smooth: np.ndarray,
+    valid_frames: list[int],
+) -> None:
+    """
+    Store smoothed landmark values back into the sequence.
+
+    Args:
+        smoothed_sequence: Sequence to store smoothed values into (modified in place)
+        landmark_sequence: Original sequence (for visibility values)
+        landmark_name: Name of the landmark being smoothed
+        x_smooth: Smoothed x coordinates
+        y_smooth: Smoothed y coordinates
+        valid_frames: Frame indices corresponding to smoothed values
+    """
+    for idx, frame_idx in enumerate(valid_frames):
+        if frame_idx >= len(smoothed_sequence):
+            smoothed_sequence.extend([{}] * (frame_idx - len(smoothed_sequence) + 1))
+
+        # Ensure smoothed_sequence[frame_idx] is a dict, not None
+        if smoothed_sequence[frame_idx] is None:
+            smoothed_sequence[frame_idx] = {}
+
+        # Type narrowing: after the check above, we know it's a dict
+        frame_dict = smoothed_sequence[frame_idx]
+        assert frame_dict is not None  # for type checker
+
+        if landmark_name not in frame_dict and landmark_sequence[frame_idx] is not None:
+            # Keep original visibility
+            orig_landmarks = landmark_sequence[frame_idx]
+            assert orig_landmarks is not None  # for type checker
+            orig_vis = orig_landmarks[landmark_name][2]
+            frame_dict[landmark_name] = (
+                float(x_smooth[idx]),
+                float(y_smooth[idx]),
+                orig_vis,
+            )
 
+
+def _smooth_landmarks_core(
+    landmark_sequence: list[dict[str, tuple[float, float, float]] | None],
+    window_length: int,
+    polyorder: int,
+    smoother_fn,  # type: ignore[no-untyped-def]
+) -> list[dict[str, tuple[float, float, float]] | None]:
+    """
+    Core smoothing logic shared by both standard and advanced smoothing.
+
+    Args:
+        landmark_sequence: List of landmark dictionaries from each frame
+        window_length: Length of filter window (must be odd)
+        polyorder: Order of polynomial used to fit samples
+        smoother_fn: Function that takes (x_coords, y_coords, valid_frames)
+            and returns (x_smooth, y_smooth)
+
+    Returns:
+        Smoothed landmark sequence
+    """
+    landmark_names = _get_landmark_names(landmark_sequence)
     if landmark_names is None:
         return landmark_sequence
 
-    # Build arrays for each landmark coordinate
     smoothed_sequence: list[dict[str, tuple[float, float, float]] | None] = []
 
     for landmark_name in landmark_names:
-        # Extract x, y coordinates for this landmark across all frames
-        x_coords = []
-        y_coords = []
-        valid_frames = []
-
-        for i, frame_landmarks in enumerate(landmark_sequence):
-            if frame_landmarks is not None and landmark_name in frame_landmarks:
-                x, y, _ = frame_landmarks[landmark_name]  # vis not used
-                x_coords.append(x)
-                y_coords.append(y)
-                valid_frames.append(i)
+        x_coords, y_coords, valid_frames = _extract_landmark_coordinates(
+            landmark_sequence, landmark_name
+        )
 
         if len(x_coords) < window_length:
             continue
 
-        # Apply Savitzky-Golay filter
-        x_smooth = savgol_filter(x_coords, window_length, polyorder)
-        y_smooth = savgol_filter(y_coords, window_length, polyorder)
+        # Apply smoothing function
+        x_smooth, y_smooth = smoother_fn(x_coords, y_coords, valid_frames)
 
         # Store smoothed values back
-        for idx, frame_idx in enumerate(valid_frames):
-            if frame_idx >= len(smoothed_sequence):
-                smoothed_sequence.extend(
-                    [{}] * (frame_idx - len(smoothed_sequence) + 1)
-                )
-
-            # Ensure smoothed_sequence[frame_idx] is a dict, not None
-            if smoothed_sequence[frame_idx] is None:
-                smoothed_sequence[frame_idx] = {}
-
-            if (
-                landmark_name not in smoothed_sequence[frame_idx]
-                and landmark_sequence[frame_idx] is not None
-            ):
-                # Keep original visibility
-                orig_vis = landmark_sequence[frame_idx][landmark_name][2]
-                smoothed_sequence[frame_idx][landmark_name] = (
-                    float(x_smooth[idx]),
-                    float(y_smooth[idx]),
-                    orig_vis,
-                )
+        _store_smoothed_landmarks(
+            smoothed_sequence,
+            landmark_sequence,
+            landmark_name,
+            x_smooth,
+            y_smooth,
+            valid_frames,
+        )
 
     # Fill in any missing frames with original data
-    for i in range(len(landmark_sequence)):
-        if i >= len(smoothed_sequence) or not smoothed_sequence[i]:
-            if i < len(smoothed_sequence):
-                smoothed_sequence[i] = landmark_sequence[i]
-            else:
-                smoothed_sequence.append(landmark_sequence[i])
+    _fill_missing_frames(smoothed_sequence, landmark_sequence)
 
     return smoothed_sequence
 
 
+def smooth_landmarks(
+    landmark_sequence: list[dict[str, tuple[float, float, float]] | None],
+    window_length: int = 5,
+    polyorder: int = 2,
+) -> list[dict[str, tuple[float, float, float]] | None]:
+    """
+    Smooth landmark trajectories using Savitzky-Golay filter.
+
+    Args:
+        landmark_sequence: List of landmark dictionaries from each frame
+        window_length: Length of filter window (must be odd, >= polyorder + 2)
+        polyorder: Order of polynomial used to fit samples
+
+    Returns:
+        Smoothed landmark sequence with same structure as input
+    """
+    if len(landmark_sequence) < window_length:
+        return landmark_sequence
+
+    # Ensure window_length is odd
+    if window_length % 2 == 0:
+        window_length += 1
+
+    def savgol_smoother(x_coords, y_coords, _valid_frames):  # type: ignore[no-untyped-def]
+        x_smooth = savgol_filter(x_coords, window_length, polyorder)
+        y_smooth = savgol_filter(y_coords, window_length, polyorder)
+        return x_smooth, y_smooth
+
+    return _smooth_landmarks_core(
+        landmark_sequence, window_length, polyorder, savgol_smoother
+    )
+
+
 def compute_velocity(
     positions: np.ndarray, fps: float, smooth_window: int = 3
 ) -> np.ndarray:
@@ -259,42 +361,13 @@ def smooth_landmarks_advanced(
         Smoothed landmark sequence with same structure as input
     """
     if len(landmark_sequence) < window_length:
-        # Not enough frames to smooth effectively
         return landmark_sequence
 
     # Ensure window_length is odd
     if window_length % 2 == 0:
         window_length += 1
 
-    # Extract landmark names from first valid frame
-    landmark_names = None
-    for frame_landmarks in landmark_sequence:
-        if frame_landmarks is not None:
-            landmark_names = list(frame_landmarks.keys())
-            break
-
-    if landmark_names is None:
-        return landmark_sequence
-
-    # Build arrays for each landmark coordinate
-    smoothed_sequence: list[dict[str, tuple[float, float, float]] | None] = []
-
-    for landmark_name in landmark_names:
-        # Extract x, y coordinates for this landmark across all frames
-        x_coords = []
-        y_coords = []
-        valid_frames = []
-
-        for i, frame_landmarks in enumerate(landmark_sequence):
-            if frame_landmarks is not None and landmark_name in frame_landmarks:
-                x, y, _ = frame_landmarks[landmark_name]  # vis not used
-                x_coords.append(x)
-                y_coords.append(y)
-                valid_frames.append(i)
-
-        if len(x_coords) < window_length:
-            continue
-
+    def advanced_smoother(x_coords, y_coords, _valid_frames):  # type: ignore[no-untyped-def]
         x_array = np.array(x_coords)
         y_array = np.array(y_coords)
 
@@ -332,35 +405,8 @@ def smooth_landmarks_advanced(
             x_smooth = savgol_filter(x_array, window_length, polyorder)
             y_smooth = savgol_filter(y_array, window_length, polyorder)
 
-        # Store smoothed values back
-        for idx, frame_idx in enumerate(valid_frames):
-            if frame_idx >= len(smoothed_sequence):
-                smoothed_sequence.extend(
-                    [{}] * (frame_idx - len(smoothed_sequence) + 1)
-                )
-
-            # Ensure smoothed_sequence[frame_idx] is a dict, not None
-            if smoothed_sequence[frame_idx] is None:
-                smoothed_sequence[frame_idx] = {}
-
-            if (
-                landmark_name not in smoothed_sequence[frame_idx]
-                and landmark_sequence[frame_idx] is not None
-            ):
-                # Keep original visibility
-                orig_vis = landmark_sequence[frame_idx][landmark_name][2]
-                smoothed_sequence[frame_idx][landmark_name] = (
-                    float(x_smooth[idx]),
-                    float(y_smooth[idx]),
-                    orig_vis,
-                )
-
-    # Fill in any missing frames with original data
-    for i in range(len(landmark_sequence)):
-        if i >= len(smoothed_sequence) or not smoothed_sequence[i]:
-            if i < len(smoothed_sequence):
-                smoothed_sequence[i] = landmark_sequence[i]
-            else:
-                smoothed_sequence.append(landmark_sequence[i])
+        return x_smooth, y_smooth
 
-    return smoothed_sequence
+    return _smooth_landmarks_core(
+        landmark_sequence, window_length, polyorder, advanced_smoother
+    )

kinemotion/dropjump/cli.py

@@ -12,17 +12,15 @@ import click
 import numpy as np
 
 from ..api import VideoConfig, VideoResult, process_videos_bulk
-from ..core.auto_tuning import (
-    AnalysisParameters as AutoTunedParams,
-)
 from ..core.auto_tuning import (
     QualityPreset,
-    VideoCharacteristics,
     analyze_video_sample,
     auto_tune_parameters,
 )
 from ..core.cli_utils import (
+    apply_expert_param_overrides,
     determine_initial_confidence,
+    print_auto_tuned_params,
     smooth_landmark_sequence,
     track_all_frames,
 )
@@ -260,67 +258,6 @@ def dropjump_analyze(  # NOSONAR(S107) - Click CLI requires individual parameter
         )
 
 
-def _apply_expert_param_overrides(
-    params: AutoTunedParams, expert_params: AnalysisParameters
-) -> AutoTunedParams:
-    """Apply expert parameter overrides to auto-tuned parameters.
-
-    Args:
-        params: Auto-tuned parameters
-        expert_params: Expert overrides
-
-    Returns:
-        Modified params object (mutated in place)
-    """
-    if expert_params.smoothing_window is not None:
-        params.smoothing_window = expert_params.smoothing_window
-    if expert_params.velocity_threshold is not None:
-        params.velocity_threshold = expert_params.velocity_threshold
-    if expert_params.min_contact_frames is not None:
-        params.min_contact_frames = expert_params.min_contact_frames
-    if expert_params.visibility_threshold is not None:
-        params.visibility_threshold = expert_params.visibility_threshold
-    return params
-
-
-def _print_auto_tuned_params(
-    video: VideoProcessor,
-    characteristics: VideoCharacteristics,
-    quality_preset: QualityPreset,
-    params: AutoTunedParams,
-) -> None:
-    """Print auto-tuned parameters in verbose mode.
-
-    Args:
-        video: Video processor
-        characteristics: Video characteristics
-        quality_preset: Quality preset
-        params: Auto-tuned parameters
-    """
-    click.echo("\n" + "=" * 60, err=True)
-    click.echo("AUTO-TUNED PARAMETERS", err=True)
-    click.echo("=" * 60, err=True)
-    click.echo(f"Video FPS: {video.fps:.2f}", err=True)
-    click.echo(
-        f"Tracking quality: {characteristics.tracking_quality} "
-        f"(avg visibility: {characteristics.avg_visibility:.2f})",
-        err=True,
-    )
-    click.echo(f"Quality preset: {quality_preset.value}", err=True)
-    click.echo("\nSelected parameters:", err=True)
-    click.echo(f"  smoothing_window: {params.smoothing_window}", err=True)
-    click.echo(f"  polyorder: {params.polyorder}", err=True)
-    click.echo(f"  velocity_threshold: {params.velocity_threshold:.4f}", err=True)
-    click.echo(f"  min_contact_frames: {params.min_contact_frames}", err=True)
-    click.echo(f"  visibility_threshold: {params.visibility_threshold}", err=True)
-    click.echo(f"  detection_confidence: {params.detection_confidence}", err=True)
-    click.echo(f"  tracking_confidence: {params.tracking_confidence}", err=True)
-    click.echo(f"  outlier_rejection: {params.outlier_rejection}", err=True)
-    click.echo(f"  bilateral_filter: {params.bilateral_filter}", err=True)
-    click.echo(f"  use_curvature: {params.use_curvature}", err=True)
-    click.echo("=" * 60 + "\n", err=True)
-
-
 def _extract_positions_and_visibilities(
     smoothed_landmarks: list,
 ) -> tuple[np.ndarray, np.ndarray]:
@@ -458,11 +395,11 @@ def _process_single(
                 landmarks_sequence, video.fps, video.frame_count
             )
             params = auto_tune_parameters(characteristics, quality_preset)
-            params = _apply_expert_param_overrides(params, expert_params)
+            params = apply_expert_param_overrides(params, expert_params)
 
             # Show parameters if verbose
             if verbose:
-                _print_auto_tuned_params(video, characteristics, quality_preset, params)
+                print_auto_tuned_params(video, quality_preset, params, characteristics)
 
             # Apply smoothing
             smoothed_landmarks = smooth_landmark_sequence(landmarks_sequence, params)

kinemotion/dropjump/debug_overlay.py

@@ -3,61 +3,15 @@
 import cv2
 import numpy as np
 
+from ..core.debug_overlay_utils import BaseDebugOverlayRenderer
 from ..core.pose import compute_center_of_mass
 from .analysis import ContactState, compute_average_foot_position
 from .kinematics import DropJumpMetrics
 
 
-class DebugOverlayRenderer:
+class DebugOverlayRenderer(BaseDebugOverlayRenderer):
     """Renders debug information on video frames."""
 
-    def __init__(
-        self,
-        output_path: str,
-        width: int,
-        height: int,
-        display_width: int,
-        display_height: int,
-        fps: float,
-    ):
-        """
-        Initialize overlay renderer.
-
-        Args:
-            output_path: Path for output video
-            width: Encoded frame width (from source video)
-            height: Encoded frame height (from source video)
-            display_width: Display width (considering SAR)
-            display_height: Display height (considering SAR)
-            fps: Frames per second
-        """
-        self.width = width
-        self.height = height
-        self.display_width = display_width
-        self.display_height = display_height
-        self.needs_resize = (display_width != width) or (display_height != height)
-
-        # Try H.264 codec first (better quality/compatibility), fallback to mp4v
-        fourcc = cv2.VideoWriter_fourcc(*"avc1")
-        # IMPORTANT: cv2.VideoWriter expects (width, height) tuple - NOT (height, width)
-        # Write at display dimensions so video displays correctly without SAR metadata
-        self.writer = cv2.VideoWriter(
-            output_path, fourcc, fps, (display_width, display_height)
-        )
-
-        # Check if writer opened successfully, fallback to mp4v if not
-        if not self.writer.isOpened():
-            fourcc = cv2.VideoWriter_fourcc(*"mp4v")
-            self.writer = cv2.VideoWriter(
-                output_path, fourcc, fps, (display_width, display_height)
-            )
-
-        if not self.writer.isOpened():
-            raise ValueError(
-                f"Failed to create video writer for {output_path} with dimensions "
-                f"{display_width}x{display_height}"
-            )
-
     def render_frame(
         self,
         frame: np.ndarray,
@@ -211,42 +165,3 @@ class DebugOverlayRenderer:
                 )
 
         return annotated
-
-    def write_frame(self, frame: np.ndarray) -> None:
-        """
-        Write frame to output video.
-
-        Args:
-            frame: Video frame with shape (height, width, 3)
-
-        Raises:
-            ValueError: If frame dimensions don't match expected encoded dimensions
-        """
-        # Validate frame dimensions match expected encoded dimensions
-        frame_height, frame_width = frame.shape[:2]
-        if frame_height != self.height or frame_width != self.width:
-            raise ValueError(
-                f"Frame dimensions ({frame_width}x{frame_height}) don't match "
-                f"source dimensions ({self.width}x{self.height}). "
-                f"Aspect ratio must be preserved from source video."
-            )
-
-        # Resize to display dimensions if needed (to handle SAR)
-        if self.needs_resize:
-            frame = cv2.resize(
-                frame,
-                (self.display_width, self.display_height),
-                interpolation=cv2.INTER_LANCZOS4,
-            )
-
-        self.writer.write(frame)
-
-    def close(self) -> None:
-        """Release video writer."""
-        self.writer.release()
-
-    def __enter__(self) -> "DebugOverlayRenderer":
-        return self
-
-    def __exit__(self, exc_type, exc_val, exc_tb) -> None:  # type: ignore[no-untyped-def]
-        self.close()

{kinemotion-0.11.4.dist-info → kinemotion-0.11.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.11.4
+Version: 0.11.6
 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.11.4.dist-info → kinemotion-0.11.6.dist-info}/RECORD

@@ -3,25 +3,26 @@ kinemotion/api.py,sha256=M6KqzdspOvtJ9Wl555HGe3ITzvRFhPK4xeqcX7IA98s,31463
 kinemotion/cli.py,sha256=cqYV_7URH0JUDy1VQ_EDLv63FmNO4Ns20m6s1XAjiP4,464
 kinemotion/cmj/__init__.py,sha256=Ynv0-Oco4I3Y1Ubj25m3h9h2XFqeNwpAewXmAYOmwfU,127
 kinemotion/cmj/analysis.py,sha256=4HYGn4VDIB6oExAees-VcPfpNgWOltpgwjyNTU7YAb4,18263
-kinemotion/cmj/cli.py,sha256=lVVlh8teFHXbDzaFdDfq3xSwRf4kVwyYyd6FU8ta_Ec,19044
-kinemotion/cmj/debug_overlay.py,sha256=ELrSYQ9LmLV81bJS5w9i2c4VwRS0EYAUnMehMHU7VGc,18724
+kinemotion/cmj/cli.py,sha256=3CQPJOC3N00dFz_mrEgSHq9pIA-RyOynZoNUIk8RzD0,17040
+kinemotion/cmj/debug_overlay.py,sha256=5Uwtyx9FP-tKhQyUvFW2t_ULVBV7oMCvzcLzf4hFcUg,15910
 kinemotion/cmj/joint_angles.py,sha256=8ucpDGPvbt4iX3tx9eVxJEUv0laTm2Y58_--VzJCogE,9113
 kinemotion/cmj/kinematics.py,sha256=Xl_PlC2OqMoA-zOc3SRB_GqI0AgLlJol5FTPe5J_qLc,7573
 kinemotion/core/__init__.py,sha256=3yzDhb5PekDNjydqrs8aWGneUGJBt-lB0SoB_Y2FXqU,1010
 kinemotion/core/auto_tuning.py,sha256=cvmxUI-CbahpOJQtR2r5jOx4Q6yKPe3DO1o15hOQIdw,10508
-kinemotion/core/cli_utils.py,sha256=hNf2-_LIbi-ntXAkovjqcuWifYLazikqJBzeTN9YmZc,3492
+kinemotion/core/cli_utils.py,sha256=iI1bHZxgbzxW5-2X3tTHEy2mqR49o3oIlwFptZ6gCco,6726
+kinemotion/core/debug_overlay_utils.py,sha256=E3krJ0SeIhSl6AM5WYiGuaONKsLNKL93P3aHqMgStY8,5235
 kinemotion/core/filtering.py,sha256=f-m-aA59e4WqE6u-9MA51wssu7rI-Y_7n1cG8IWdeRQ,11241
 kinemotion/core/pose.py,sha256=Wfd1RR-2ZznYpWeQUbySwcV3mvReqn8n3XO6S7pGq4M,8390
-kinemotion/core/smoothing.py,sha256=FON4qKtsSp1-03GnJrDkEUAePaACn4QPMJF0eTIYqR0,12925
+kinemotion/core/smoothing.py,sha256=Zdhqw4NyCrZaEb-Jo3sASzP-QlEL5sVTgHoXU8zT_xU,14136
 kinemotion/core/video_io.py,sha256=z8Z0qbNaKbcdB40KnbNOBMzab3BbgnhBxp-mUBYeXgM,6577
 kinemotion/dropjump/__init__.py,sha256=yc1XiZ9vfo5h_n7PKVSiX2TTgaIfGL7Y7SkQtiDZj_E,838
 kinemotion/dropjump/analysis.py,sha256=HfJt2t9IsMBiBUz7apIzdxbRH9QqzlFnDVVWcKhU3ow,23291
-kinemotion/dropjump/cli.py,sha256=eXO-9H9z0g-EJUD1uIT37KIMgfyje4fPAO2FgZiEZzk,24985
-kinemotion/dropjump/debug_overlay.py,sha256=GMo-jCl5OPIv82uPxDbBVI7CsAMwATTvxZMeWfs8k8M,8701
+kinemotion/dropjump/cli.py,sha256=-iBgHNwW_dijHe6_JIEGSBUzvFb6tZV0aopbPd-9jC8,22402
+kinemotion/dropjump/debug_overlay.py,sha256=2L4VAZwWFnaOQ7LAF3ALXCjEaVNzkfpLT5-h0qKL_6g,5707
 kinemotion/dropjump/kinematics.py,sha256=RM_O8Kdc6aEiPIu_99N4cu-4EhYSQxtBGASJF_dmQaU,19081
 kinemotion/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kinemotion-0.11.4.dist-info/METADATA,sha256=0NPASGHoBcuSIKGlfsKsflT7j6o0DiHzMqhBm2-k2EM,18990
-kinemotion-0.11.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-kinemotion-0.11.4.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
-kinemotion-0.11.4.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
-kinemotion-0.11.4.dist-info/RECORD,,
+kinemotion-0.11.6.dist-info/METADATA,sha256=UsgmtoeTQaucbGCimul6F5wuGllK2cHFw-QUUo4WWUs,18990
+kinemotion-0.11.6.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+kinemotion-0.11.6.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
+kinemotion-0.11.6.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
+kinemotion-0.11.6.dist-info/RECORD,,