kinemotion 0.24.0__py3-none-any.whl → 0.25.0__py3-none-any.whl

kinemotion/api.py

@@ -18,13 +18,27 @@ from .core.auto_tuning import (
     analyze_video_sample,
     auto_tune_parameters,
 )
+from .core.filtering import reject_outliers
+from .core.metadata import (
+    AlgorithmConfig,
+    DetectionConfig,
+    DropDetectionConfig,
+    ProcessingInfo,
+    ResultMetadata,
+    SmoothingConfig,
+    VideoInfo,
+    create_timestamp,
+    get_kinemotion_version,
+)
 from .core.pose import PoseTracker
+from .core.quality import assess_jump_quality
 from .core.smoothing import smooth_landmarks, smooth_landmarks_advanced
 from .core.video_io import VideoProcessor
 from .dropjump.analysis import (
     ContactState,
     compute_average_foot_position,
     detect_ground_contact,
+    find_contact_phases,
 )
 from .dropjump.debug_overlay import DebugOverlayRenderer
 from .dropjump.kinematics import DropJumpMetrics, calculate_drop_jump_metrics
@@ -392,6 +406,9 @@ def process_dropjump_video(
     if not Path(video_path).exists():
         raise FileNotFoundError(f"Video file not found: {video_path}")
 
+    # Start timing
+    start_time = time.time()
+
     # Convert quality string to enum
     quality_preset = _parse_quality_preset(quality)
 
@@ -470,6 +487,98 @@ def process_dropjump_video(
             use_curvature=params.use_curvature,
         )
 
+        # Assess quality and add confidence scores
+        if verbose:
+            print("Assessing tracking quality...")
+
+        # Detect outliers for quality scoring (doesn't affect results, just for assessment)
+        _, outlier_mask = reject_outliers(
+            vertical_positions,
+            use_ransac=True,
+            use_median=True,
+            interpolate=False,  # Don't modify, just detect
+        )
+
+        # Count phases for quality assessment
+        phases = find_contact_phases(contact_states)
+        phases_detected = len(phases) > 0
+        phase_count = len(phases)
+
+        # Perform quality assessment
+        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,
+        )
+
+        # Build complete metadata
+        processing_time = time.time() - start_time
+
+        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=None,
+        )
+
+        processing_info = ProcessingInfo(
+            version=get_kinemotion_version(),
+            timestamp=create_timestamp(),
+            quality_preset=quality_preset.value,
+            processing_time_s=processing_time,
+        )
+
+        # Check if drop start was auto-detected
+        drop_frame = None
+        if drop_start_frame is None and metrics.contact_start_frame is not None:
+            # Auto-detected
+            drop_frame = metrics.contact_start_frame
+
+        algorithm_config = AlgorithmConfig(
+            detection_method="forward_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=DropDetectionConfig(
+                auto_detect_drop_start=(drop_start_frame is None),
+                detected_drop_frame=drop_frame,
+                min_stationary_duration_s=0.5,
+            ),
+        )
+
+        result_metadata = ResultMetadata(
+            quality=quality_result,
+            video=video_info,
+            processing=processing_info,
+            algorithm=algorithm_config,
+        )
+
+        # Attach complete metadata to metrics
+        metrics.result_metadata = result_metadata
+
+        if verbose and quality_result.warnings:
+            print("\n⚠️  Quality Warnings:")
+            for warning in quality_result.warnings:
+                print(f"  - {warning}")
+            print()
+
         # Generate outputs (JSON and debug video)
         _generate_outputs(
             metrics,
@@ -726,6 +835,9 @@ def process_cmj_video(
     if not Path(video_path).exists():
         raise FileNotFoundError(f"Video file not found: {video_path}")
 
+    # Start timing
+    start_time = time.time()
+
     # Convert quality string to enum
     quality_preset = _parse_quality_preset(quality)
 
@@ -772,7 +884,9 @@ def process_cmj_video(
         # Extract foot positions
         if verbose:
             print("Extracting foot positions...")
-        vertical_positions, _ = _extract_vertical_positions(smoothed_landmarks)
+        vertical_positions, visibilities = _extract_vertical_positions(
+            smoothed_landmarks
+        )
         tracking_method = "foot"
 
         # Detect CMJ phases
@@ -815,6 +929,87 @@ def process_cmj_video(
             tracking_method=tracking_method,
         )
 
+        # Assess quality and add confidence scores
+        if verbose:
+            print("Assessing tracking quality...")
+
+        # Detect outliers for quality scoring (doesn't affect results, just for assessment)
+        _, outlier_mask = reject_outliers(
+            vertical_positions,
+            use_ransac=True,
+            use_median=True,
+            interpolate=False,  # Don't modify, just detect
+        )
+
+        # Phases detected successfully if we got here
+        phases_detected = True
+        phase_count = 4  # standing, eccentric, concentric, flight
+
+        # Perform quality assessment
+        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,
+        )
+
+        # Build complete metadata
+        processing_time = time.time() - start_time
+
+        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=None,  # TODO: Extract from video metadata if available
+        )
+
+        processing_info = ProcessingInfo(
+            version=get_kinemotion_version(),
+            timestamp=create_timestamp(),
+            quality_preset=quality_preset.value,
+            processing_time_s=processing_time,
+        )
+
+        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,  # CMJ doesn't have drop detection
+        )
+
+        result_metadata = ResultMetadata(
+            quality=quality_result,
+            video=video_info,
+            processing=processing_info,
+            algorithm=algorithm_config,
+        )
+
+        # Attach complete metadata to metrics
+        metrics.result_metadata = result_metadata
+
+        if verbose and quality_result.warnings:
+            print("\n⚠️  Quality Warnings:")
+            for warning in quality_result.warnings:
+                print(f"  - {warning}")
+            print()
+
         # Generate outputs if requested
         _generate_cmj_outputs(
             output_video,

kinemotion/cmj/cli.py

@@ -8,26 +8,10 @@ from pathlib import Path
 from typing import Any
 
 import click
-import numpy as np
 
-from ..core.auto_tuning import (
-    QualityPreset,
-    analyze_video_sample,
-    auto_tune_parameters,
-)
-from ..core.cli_utils import (
-    apply_expert_param_overrides,
-    common_output_options,
-    determine_initial_confidence,
-    print_auto_tuned_params,
-    smooth_landmark_sequence,
-    track_all_frames,
-)
-from ..core.pose import PoseTracker
-from ..core.video_io import VideoProcessor
-from .analysis import detect_cmj_phases
-from .debug_overlay import CMJDebugOverlayRenderer
-from .kinematics import CMJMetrics, calculate_cmj_metrics
+from ..api import process_cmj_video
+from ..core.auto_tuning import QualityPreset
+from ..core.cli_utils import common_output_options
 
 
 @dataclass
@@ -288,44 +272,6 @@ def cmj_analyze(  # NOSONAR(S107) - Click CLI requires individual parameters for
             sys.exit(1)
 
 
-def _get_foot_position(frame_landmarks: dict | None, last_position: float) -> float:
-    """Extract average foot position from frame landmarks."""
-    if not frame_landmarks:
-        return last_position
-
-    # Average foot position (ankles and heels)
-    foot_y_values = []
-    for key in ["left_ankle", "right_ankle", "left_heel", "right_heel"]:
-        if key in frame_landmarks:
-            foot_y_values.append(frame_landmarks[key][1])
-
-    if foot_y_values:
-        return float(np.mean(foot_y_values))
-    return last_position
-
-
-def _extract_positions_from_landmarks(
-    smoothed_landmarks: list,
-) -> tuple[np.ndarray, str]:
-    """Extract vertical foot positions from landmarks.
-
-    Args:
-        smoothed_landmarks: Smoothed landmark sequence
-
-    Returns:
-        Tuple of (positions array, tracking method name)
-    """
-    click.echo("Extracting foot positions...", err=True)
-    position_list: list[float] = []
-
-    for frame_landmarks in smoothed_landmarks:
-        last_pos = position_list[-1] if position_list else 0.5
-        position = _get_foot_position(frame_landmarks, last_pos)
-        position_list.append(position)
-
-    return np.array(position_list), "foot"
-
-
 def _process_single(
     video_path: str,
     output: str | None,
@@ -334,169 +280,35 @@ def _process_single(
     verbose: bool,
     expert_params: AnalysisParameters,
 ) -> None:
-    """Process a single CMJ video."""
+    """Process a single CMJ video by calling the API."""
     try:
-        with VideoProcessor(video_path) as video:
-            click.echo(
-                f"Video: {video.width}x{video.height} @ {video.fps:.2f} fps, "
-                f"{video.frame_count} frames",
-                err=True,
-            )
-
-            # Determine confidence levels
-            detection_conf, tracking_conf = determine_initial_confidence(
-                quality_preset, expert_params
-            )
-
-            # Track all frames
-            tracker = PoseTracker(
-                min_detection_confidence=detection_conf,
-                min_tracking_confidence=tracking_conf,
-            )
-            frames, landmarks_sequence = track_all_frames(video, tracker)
-
-            if not landmarks_sequence:
-                click.echo("Error: No frames processed", err=True)
-                sys.exit(1)
-
-            # Auto-tune parameters
-            characteristics = analyze_video_sample(
-                landmarks_sequence, video.fps, video.frame_count
-            )
-            params = auto_tune_parameters(characteristics, quality_preset)
-            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)
-            countermovement_threshold = 0.015 * (30.0 / video.fps)
-            if expert_params.countermovement_threshold is not None:
-                countermovement_threshold = expert_params.countermovement_threshold
-
-            # Show parameters if verbose
-            if verbose:
-                print_auto_tuned_params(
-                    video,
-                    quality_preset,
-                    params,
-                    extra_params={
-                        "countermovement_threshold": countermovement_threshold
-                    },
-                )
-
-            # Apply smoothing
-            smoothed_landmarks = smooth_landmark_sequence(landmarks_sequence, params)
-
-            # Extract foot positions
-            vertical_positions, tracking_method = _extract_positions_from_landmarks(
-                smoothed_landmarks
-            )
-
-            # Detect CMJ phases
-            click.echo("Detecting CMJ phases...", err=True)
-            phases = detect_cmj_phases(
-                vertical_positions,
-                video.fps,
-                window_length=params.smoothing_window,
-                polyorder=params.polyorder,
-            )
-
-            if phases is None:
-                click.echo("Error: Could not detect CMJ phases", err=True)
-                sys.exit(1)
-
-            standing_end, lowest_point, takeoff_frame, landing_frame = phases
-
-            # Calculate metrics
-            click.echo("Calculating metrics...", err=True)
-
-            # Compute SIGNED velocities for CMJ metrics (need direction info)
-            from .analysis import compute_signed_velocity
-
-            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=tracking_method,
-            )
-
-            # Output results
-            _output_results(metrics, json_output)
+        # 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,
+            detection_confidence=expert_params.detection_confidence,
+            tracking_confidence=expert_params.tracking_confidence,
+            verbose=verbose,
+        )
 
-            # Generate debug video if requested
-            if output:
-                _create_debug_video(output, video, frames, smoothed_landmarks, metrics)
+        # Print formatted summary to stdout
+        _output_results(metrics, json_output=None)  # Don't write JSON (API already did)
 
     except Exception as e:
         click.echo(f"Error processing video: {e}", err=True)
-        import traceback
+        if verbose:
+            import traceback
 
-        traceback.print_exc()
+            traceback.print_exc()
         sys.exit(1)
 
 
-def _create_debug_video(
-    output: str,
-    video: VideoProcessor,
-    frames: list,
-    smoothed_landmarks: list,
-    metrics: CMJMetrics,
-) -> None:
-    """Generate debug video with overlays.
-
-    Args:
-        output: Output video path
-        video: Video processor
-        frames: Video frames
-        smoothed_landmarks: Smoothed landmarks
-        metrics: Calculated metrics
-    """
-    click.echo(f"Generating debug video: {output}", err=True)
-    if video.display_width != video.width or video.display_height != video.height:
-        click.echo(f"Source video encoded: {video.width}x{video.height}", err=True)
-        click.echo(
-            f"Output dimensions: {video.display_width}x{video.display_height} "
-            f"(respecting display aspect ratio)",
-            err=True,
-        )
-    else:
-        click.echo(
-            f"Output dimensions: {video.width}x{video.height} "
-            f"(matching source video aspect ratio)",
-            err=True,
-        )
-
-    with CMJDebugOverlayRenderer(
-        output,
-        video.width,
-        video.height,
-        video.display_width,
-        video.display_height,
-        video.fps,
-    ) as renderer:
-        render_bar: Any
-        with click.progressbar(
-            length=len(frames), label="Rendering frames"
-        ) as render_bar:
-            for i, frame in enumerate(frames):
-                annotated = renderer.render_frame(
-                    frame, smoothed_landmarks[i], i, metrics
-                )
-                renderer.write_frame(annotated)
-                render_bar.update(1)
-
-    click.echo(f"Debug video saved: {output}", err=True)
-
-
 def _output_results(metrics: Any, json_output: str | None) -> None:
     """Output analysis results."""
     results = metrics.to_dict()

kinemotion/cmj/kinematics.py

@@ -1,14 +1,18 @@
 """Counter Movement Jump (CMJ) metrics calculation."""
 
 from dataclasses import dataclass
-from typing import TypedDict
+from typing import TYPE_CHECKING, TypedDict
 
 import numpy as np
 from numpy.typing import NDArray
 
+if TYPE_CHECKING:
+    from ..core.metadata import ResultMetadata
+    from ..core.quality import QualityAssessment
 
-class CMJMetricsDict(TypedDict, total=False):
-    """Type-safe dictionary for CMJ metrics JSON output."""
+
+class CMJDataDict(TypedDict, total=False):
+    """Type-safe dictionary for CMJ measurement data."""
 
     jump_height_m: float
     flight_time_s: float
@@ -23,10 +27,16 @@ class CMJMetricsDict(TypedDict, total=False):
     lowest_point_frame: float
     takeoff_frame: float
     landing_frame: float
-    video_fps: float
     tracking_method: str
 
 
+class CMJResultDict(TypedDict):
+    """Type-safe dictionary for complete CMJ result with data and metadata."""
+
+    data: CMJDataDict
+    metadata: dict  # ResultMetadata.to_dict()
+
+
 @dataclass
 class CMJMetrics:
     """Metrics for a counter movement jump analysis.
@@ -47,6 +57,7 @@ class CMJMetrics:
         landing_frame: Frame where athlete lands
         video_fps: Frames per second of the analyzed video
         tracking_method: Method used for tracking ("foot" or "com")
+        quality_assessment: Optional quality assessment with confidence and warnings
     """
 
     jump_height: float
@@ -64,14 +75,16 @@ class CMJMetrics:
     landing_frame: float
     video_fps: float
     tracking_method: str
+    quality_assessment: "QualityAssessment | None" = None
+    result_metadata: "ResultMetadata | None" = None
 
-    def to_dict(self) -> CMJMetricsDict:
-        """Convert metrics to JSON-serializable dictionary.
+    def to_dict(self) -> CMJResultDict:
+        """Convert metrics to JSON-serializable dictionary with data/metadata structure.
 
         Returns:
-            Dictionary with all metrics, converting NumPy types to Python types.
+            Dictionary with nested data and metadata structure.
         """
-        return {
+        data: CMJDataDict = {
             "jump_height_m": float(self.jump_height),
             "flight_time_s": float(self.flight_time),
             "countermovement_depth_m": float(self.countermovement_depth),
@@ -93,10 +106,21 @@ class CMJMetrics:
             "lowest_point_frame": float(self.lowest_point_frame),
             "takeoff_frame": float(self.takeoff_frame),
             "landing_frame": float(self.landing_frame),
-            "video_fps": float(self.video_fps),
             "tracking_method": self.tracking_method,
         }
 
+        # Build metadata from ResultMetadata if available, otherwise use legacy quality
+        if self.result_metadata is not None:
+            metadata = self.result_metadata.to_dict()
+        elif self.quality_assessment is not None:
+            # Fallback for backwards compatibility during transition
+            metadata = {"quality": self.quality_assessment.to_dict()}
+        else:
+            # No metadata available
+            metadata = {}
+
+        return {"data": data, "metadata": metadata}
+
 
 def calculate_cmj_metrics(
     positions: NDArray[np.float64],

kinemotion/core/__init__.py

@@ -9,6 +9,12 @@ from .filtering import (
     remove_outliers,
 )
 from .pose import PoseTracker, compute_center_of_mass
+from .quality import (
+    QualityAssessment,
+    QualityIndicators,
+    assess_jump_quality,
+    calculate_position_stability,
+)
 from .smoothing import (
     compute_acceleration_from_derivative,
     compute_velocity,
@@ -35,6 +41,11 @@ __all__ = [
     "reject_outliers",
     "adaptive_smooth_window",
     "bilateral_temporal_filter",
+    # Quality Assessment
+    "QualityAssessment",
+    "QualityIndicators",
+    "assess_jump_quality",
+    "calculate_position_stability",
     # Video I/O
     "VideoProcessor",
 ]