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

kinemotion/core/metadata.py

@@ -0,0 +1,222 @@
+"""Metadata structures for analysis results."""
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from .quality import QualityAssessment
+
+
+@dataclass
+class VideoInfo:
+    """Information about the source video.
+
+    Attributes:
+        source_path: Path to the source video file
+        fps: Actual frames per second (measured from video)
+        width: Video width in pixels
+        height: Video height in pixels
+        duration_s: Total video duration in seconds
+        frame_count: Total number of frames
+        codec: Video codec (e.g., "h264", "hevc") or None if unknown
+    """
+
+    source_path: str
+    fps: float
+    width: int
+    height: int
+    duration_s: float
+    frame_count: int
+    codec: str | None = None
+
+    def to_dict(self) -> dict:
+        """Convert to JSON-serializable dictionary."""
+        return {
+            "source_path": self.source_path,
+            "fps": round(self.fps, 2),
+            "resolution": {"width": self.width, "height": self.height},
+            "duration_s": round(self.duration_s, 2),
+            "frame_count": self.frame_count,
+            "codec": self.codec,
+        }
+
+
+@dataclass
+class ProcessingInfo:
+    """Information about processing context.
+
+    Attributes:
+        version: Kinemotion version string (e.g., "0.26.0")
+        timestamp: ISO 8601 timestamp of when analysis was performed
+        quality_preset: Quality preset used ("fast", "balanced", "accurate")
+        processing_time_s: Time taken to process video in seconds
+    """
+
+    version: str
+    timestamp: str
+    quality_preset: str
+    processing_time_s: float
+
+    def to_dict(self) -> dict:
+        """Convert to JSON-serializable dictionary."""
+        return {
+            "version": self.version,
+            "timestamp": self.timestamp,
+            "quality_preset": self.quality_preset,
+            "processing_time_s": round(self.processing_time_s, 3),
+        }
+
+
+@dataclass
+class SmoothingConfig:
+    """Smoothing algorithm configuration.
+
+    Attributes:
+        window_size: Savitzky-Golay window size
+        polynomial_order: Polynomial degree for SG filter
+        use_bilateral_filter: Whether bilateral temporal filtering was used
+        use_outlier_rejection: Whether RANSAC/median outlier rejection was used
+    """
+
+    window_size: int
+    polynomial_order: int
+    use_bilateral_filter: bool
+    use_outlier_rejection: bool
+
+    def to_dict(self) -> dict:
+        """Convert to JSON-serializable dictionary."""
+        return {
+            "window_size": self.window_size,
+            "polynomial_order": self.polynomial_order,
+            "use_bilateral_filter": self.use_bilateral_filter,
+            "use_outlier_rejection": self.use_outlier_rejection,
+        }
+
+
+@dataclass
+class DetectionConfig:
+    """Detection algorithm configuration.
+
+    Attributes:
+        velocity_threshold: Velocity threshold for contact/flight detection
+        min_contact_frames: Minimum consecutive frames to confirm contact
+        visibility_threshold: Minimum landmark visibility to trust
+        use_curvature_refinement: Whether acceleration-based refinement was used
+    """
+
+    velocity_threshold: float
+    min_contact_frames: int
+    visibility_threshold: float
+    use_curvature_refinement: bool
+
+    def to_dict(self) -> dict:
+        """Convert to JSON-serializable dictionary."""
+        return {
+            "velocity_threshold": round(self.velocity_threshold, 4),
+            "min_contact_frames": self.min_contact_frames,
+            "visibility_threshold": round(self.visibility_threshold, 2),
+            "use_curvature_refinement": self.use_curvature_refinement,
+        }
+
+
+@dataclass
+class DropDetectionConfig:
+    """Drop jump-specific detection configuration.
+
+    Attributes:
+        auto_detect_drop_start: Whether automatic drop start detection was used
+        detected_drop_frame: Frame where drop was detected (None if manual)
+        min_stationary_duration_s: Minimum standing time before drop
+    """
+
+    auto_detect_drop_start: bool
+    detected_drop_frame: int | None
+    min_stationary_duration_s: float
+
+    def to_dict(self) -> dict:
+        """Convert to JSON-serializable dictionary."""
+        return {
+            "auto_detect_drop_start": self.auto_detect_drop_start,
+            "detected_drop_frame": self.detected_drop_frame,
+            "min_stationary_duration_s": round(self.min_stationary_duration_s, 2),
+        }
+
+
+@dataclass
+class AlgorithmConfig:
+    """Complete algorithm configuration for reproducibility.
+
+    Attributes:
+        detection_method: Algorithm used ("backward_search" for CMJ, "forward_search" for drop)
+        tracking_method: Pose tracking method ("mediapipe_pose")
+        model_complexity: MediaPipe model complexity (0, 1, or 2)
+        smoothing: Smoothing configuration
+        detection: Detection configuration
+        drop_detection: Drop detection config (drop jump only, None for CMJ)
+    """
+
+    detection_method: str
+    tracking_method: str
+    model_complexity: int
+    smoothing: SmoothingConfig
+    detection: DetectionConfig
+    drop_detection: DropDetectionConfig | None = None
+
+    def to_dict(self) -> dict:
+        """Convert to JSON-serializable dictionary."""
+        result = {
+            "detection_method": self.detection_method,
+            "tracking_method": self.tracking_method,
+            "model_complexity": self.model_complexity,
+            "smoothing": self.smoothing.to_dict(),
+            "detection": self.detection.to_dict(),
+        }
+
+        if self.drop_detection is not None:
+            result["drop_detection"] = self.drop_detection.to_dict()
+
+        return result
+
+
+@dataclass
+class ResultMetadata:
+    """Complete metadata for analysis results.
+
+    Attributes:
+        quality: Quality assessment with confidence and warnings
+        video: Source video information
+        processing: Processing context and timing
+        algorithm: Algorithm configuration used
+    """
+
+    quality: QualityAssessment
+    video: VideoInfo
+    processing: ProcessingInfo
+    algorithm: AlgorithmConfig
+
+    def to_dict(self) -> dict:
+        """Convert to JSON-serializable dictionary."""
+        return {
+            "quality": self.quality.to_dict(),
+            "video": self.video.to_dict(),
+            "processing": self.processing.to_dict(),
+            "algorithm": self.algorithm.to_dict(),
+        }
+
+
+def create_timestamp() -> str:
+    """Create ISO 8601 timestamp for current time in UTC."""
+    return datetime.now(timezone.utc).isoformat()
+
+
+def get_kinemotion_version() -> str:
+    """Get current kinemotion version.
+
+    Returns:
+        Version string (e.g., "0.26.0")
+    """
+    try:
+        from importlib.metadata import version
+
+        return version("kinemotion")
+    except Exception:
+        return "unknown"

kinemotion/core/quality.py

@@ -0,0 +1,396 @@
+"""Quality assessment and confidence scoring for pose tracking and analysis."""
+
+from dataclasses import dataclass
+from typing import Literal
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+@dataclass
+class QualityIndicators:
+    """Detailed quality indicators for pose tracking and analysis.
+
+    Attributes:
+        avg_visibility: Mean visibility score across all key landmarks (0-1)
+        min_visibility: Minimum visibility score encountered (0-1)
+        tracking_stable: Whether landmark tracking was stable (low jitter)
+        phase_detection_clear: Whether phase transitions were clearly detected
+        outliers_detected: Number of outlier frames detected and corrected
+        outlier_percentage: Percentage of frames with outliers (0-100)
+        position_variance: Variance in position tracking (lower is more stable)
+        fps: Video frame rate (higher is better for accuracy)
+    """
+
+    avg_visibility: float
+    min_visibility: float
+    tracking_stable: bool
+    phase_detection_clear: bool
+    outliers_detected: int
+    outlier_percentage: float
+    position_variance: float
+    fps: float
+
+
+@dataclass
+class QualityAssessment:
+    """Overall quality assessment with confidence level and warnings.
+
+    Attributes:
+        confidence: Overall confidence level (high/medium/low)
+        quality_indicators: Detailed quality metrics
+        warnings: List of warning messages for user
+        quality_score: Numerical quality score (0-100)
+    """
+
+    confidence: Literal["high", "medium", "low"]
+    quality_indicators: QualityIndicators
+    warnings: list[str]
+    quality_score: float
+
+    def to_dict(self) -> dict:
+        """Convert quality assessment to JSON-serializable dictionary."""
+        return {
+            "confidence": self.confidence,
+            "quality_score": round(self.quality_score, 1),
+            "quality_indicators": {
+                "avg_visibility": round(self.quality_indicators.avg_visibility, 3),
+                "min_visibility": round(self.quality_indicators.min_visibility, 3),
+                "tracking_stable": self.quality_indicators.tracking_stable,
+                "phase_detection_clear": self.quality_indicators.phase_detection_clear,
+                "outliers_detected": self.quality_indicators.outliers_detected,
+                "outlier_percentage": round(
+                    self.quality_indicators.outlier_percentage, 1
+                ),
+                "position_variance": round(
+                    self.quality_indicators.position_variance, 6
+                ),
+                "fps": round(self.quality_indicators.fps, 1),
+            },
+            "warnings": self.warnings,
+        }
+
+
+def calculate_position_stability(
+    positions: NDArray[np.float64],
+    window_size: int = 10,
+) -> float:
+    """
+    Calculate position tracking stability using rolling variance.
+
+    Lower variance indicates more stable tracking (less jitter).
+
+    Args:
+        positions: Array of position values (e.g., foot y-positions)
+        window_size: Window size for rolling variance calculation
+
+    Returns:
+        Mean rolling variance (lower is better)
+    """
+    if len(positions) < window_size:
+        return float(np.var(positions))
+
+    # Calculate rolling variance
+    rolling_vars = []
+    for i in range(len(positions) - window_size + 1):
+        window = positions[i : i + window_size]
+        rolling_vars.append(np.var(window))
+
+    return float(np.mean(rolling_vars))
+
+
+def assess_tracking_quality(
+    visibilities: NDArray[np.float64],
+    positions: NDArray[np.float64],
+    outlier_mask: NDArray[np.bool_] | None,
+    fps: float,
+    phases_detected: bool = True,
+    phase_count: int = 0,
+) -> QualityAssessment:
+    """
+    Assess overall tracking quality and assign confidence level.
+
+    Evaluates multiple quality indicators to determine confidence:
+    - Landmark visibility (MediaPipe confidence scores)
+    - Tracking stability (position variance, jitter)
+    - Outlier detection (frames requiring correction)
+    - Phase detection success (clear transitions found)
+    - Frame rate (higher = better temporal resolution)
+
+    Args:
+        visibilities: Array of visibility scores for each frame (0-1)
+        positions: Array of tracked positions (normalized coordinates)
+        outlier_mask: Boolean array marking outlier frames (None if no outliers)
+        fps: Video frame rate
+        phases_detected: Whether jump phases were successfully detected
+        phase_count: Number of phases detected (0 if failed)
+
+    Returns:
+        QualityAssessment object with confidence level, indicators, and warnings
+    """
+    # Calculate visibility metrics
+    avg_visibility = float(np.mean(visibilities))
+    min_visibility = float(np.min(visibilities))
+
+    # Calculate tracking stability
+    position_variance = calculate_position_stability(positions)
+    tracking_stable = position_variance < 0.001  # Threshold for stable tracking
+
+    # Count outliers
+    outliers_detected = 0
+    outlier_percentage = 0.0
+    if outlier_mask is not None:
+        outliers_detected = int(np.sum(outlier_mask))
+        outlier_percentage = (outliers_detected / len(outlier_mask)) * 100
+
+    # Assess phase detection clarity
+    phase_detection_clear = phases_detected and phase_count >= 2
+
+    # Create quality indicators
+    indicators = QualityIndicators(
+        avg_visibility=avg_visibility,
+        min_visibility=min_visibility,
+        tracking_stable=tracking_stable,
+        phase_detection_clear=phase_detection_clear,
+        outliers_detected=outliers_detected,
+        outlier_percentage=outlier_percentage,
+        position_variance=position_variance,
+        fps=fps,
+    )
+
+    # Calculate overall quality score (0-100)
+    quality_score = _calculate_quality_score(indicators)
+
+    # Determine confidence level
+    confidence = _determine_confidence_level(quality_score)
+
+    # Generate warnings
+    warnings = _generate_warnings(indicators, confidence)
+
+    return QualityAssessment(
+        confidence=confidence,
+        quality_indicators=indicators,
+        warnings=warnings,
+        quality_score=quality_score,
+    )
+
+
+def _calculate_quality_score(indicators: QualityIndicators) -> float:
+    """
+    Calculate numerical quality score (0-100) from quality indicators.
+
+    Weighted combination of different quality factors:
+    - Visibility: 40% weight (most critical)
+    - Tracking stability: 25% weight
+    - Outlier rate: 20% weight
+    - Phase detection: 10% weight
+    - Frame rate: 5% weight
+
+    Args:
+        indicators: Quality indicators object
+
+    Returns:
+        Quality score from 0 (worst) to 100 (best)
+    """
+    # Visibility score (40% weight)
+    # Perfect: avg_vis=1.0, min_vis>0.8
+    visibility_score = indicators.avg_visibility * 100
+    if indicators.min_visibility < 0.5:
+        visibility_score *= 0.7  # Penalty for low minimum visibility
+
+    # Tracking stability score (25% weight)
+    # Perfect: position_variance < 0.0005
+    # Good: position_variance < 0.001
+    # Medium: position_variance < 0.003
+    if indicators.position_variance < 0.0005:
+        stability_score = 100.0
+    elif indicators.position_variance < 0.001:
+        stability_score = 85.0
+    elif indicators.position_variance < 0.003:
+        stability_score = 65.0
+    else:
+        stability_score = max(0.0, 100 - indicators.position_variance * 10000)
+
+    # Outlier score (20% weight)
+    # Perfect: 0% outliers
+    # Good: <5% outliers
+    # Acceptable: <10% outliers
+    outlier_score = max(0.0, 100 - indicators.outlier_percentage * 10)
+
+    # Phase detection score (10% weight)
+    phase_score = 100.0 if indicators.phase_detection_clear else 50.0
+
+    # Frame rate score (5% weight)
+    # Perfect: 60fps+
+    # Good: 30-60fps
+    # Poor: <30fps
+    if indicators.fps >= 60:
+        fps_score = 100.0
+    elif indicators.fps >= 30:
+        fps_score = 80.0
+    elif indicators.fps >= 24:
+        fps_score = 60.0
+    else:
+        fps_score = 40.0
+
+    # Weighted combination
+    quality_score = (
+        visibility_score * 0.40
+        + stability_score * 0.25
+        + outlier_score * 0.20
+        + phase_score * 0.10
+        + fps_score * 0.05
+    )
+
+    return float(np.clip(quality_score, 0, 100))
+
+
+def _determine_confidence_level(
+    quality_score: float,
+) -> Literal["high", "medium", "low"]:
+    """
+    Determine confidence level from quality score.
+
+    Thresholds:
+    - High: quality_score >= 75
+    - Medium: quality_score >= 50
+    - Low: quality_score < 50
+
+    Args:
+        quality_score: Numerical quality score (0-100)
+
+    Returns:
+        Confidence level: "high", "medium", or "low"
+    """
+    if quality_score >= 75:
+        return "high"
+    elif quality_score >= 50:
+        return "medium"
+    else:
+        return "low"
+
+
+def _generate_warnings(
+    indicators: QualityIndicators,
+    confidence: Literal["high", "medium", "low"],
+) -> list[str]:
+    """
+    Generate user-facing warning messages based on quality indicators.
+
+    Args:
+        indicators: Quality indicators object
+        confidence: Overall confidence level
+
+    Returns:
+        List of warning messages (empty if no warnings)
+    """
+    warnings: list[str] = []
+
+    # Visibility warnings
+    if indicators.avg_visibility < 0.7:
+        warnings.append(
+            f"Poor landmark visibility (avg {indicators.avg_visibility:.2f}). "
+            "Check lighting, camera angle, and ensure full body is visible."
+        )
+    elif indicators.avg_visibility < 0.8:
+        warnings.append(
+            f"Moderate landmark visibility (avg {indicators.avg_visibility:.2f}). "
+            "Results may be less accurate."
+        )
+
+    if indicators.min_visibility < 0.5:
+        warnings.append(
+            f"Very low visibility detected ({indicators.min_visibility:.2f}). "
+            "Some frames may have occlusion or tracking loss."
+        )
+
+    # Tracking stability warnings
+    if not indicators.tracking_stable:
+        warnings.append(
+            f"Unstable landmark tracking detected (variance {indicators.position_variance:.4f}). "
+            "This may indicate jitter or occlusion. Consider better lighting or camera position."
+        )
+
+    # Outlier warnings
+    if indicators.outlier_percentage > 10:
+        warnings.append(
+            f"High outlier rate ({indicators.outlier_percentage:.1f}%). "
+            f"{indicators.outliers_detected} frames required correction. "
+            "This may reduce measurement accuracy."
+        )
+    elif indicators.outlier_percentage > 5:
+        warnings.append(
+            f"Moderate outlier rate ({indicators.outlier_percentage:.1f}%). "
+            f"{indicators.outliers_detected} frames were corrected."
+        )
+
+    # Phase detection warnings
+    if not indicators.phase_detection_clear:
+        warnings.append(
+            "Unclear phase transitions detected. "
+            "Jump phases may not be accurately identified. "
+            "Check if full jump is captured in video."
+        )
+
+    # Frame rate warnings
+    if indicators.fps < 30:
+        warnings.append(
+            f"Low frame rate ({indicators.fps:.0f} fps). "
+            "Recommend recording at 30fps or higher for better accuracy. "
+            "Validated apps use 120-240fps."
+        )
+    elif indicators.fps < 60:
+        warnings.append(
+            f"Frame rate is {indicators.fps:.0f} fps. "
+            "Consider 60fps or higher for improved temporal resolution. "
+            "Validated apps (MyJump) use 120-240fps."
+        )
+
+    # Overall confidence warning
+    if confidence == "low":
+        warnings.append(
+            "⚠️ LOW CONFIDENCE: Results may be unreliable. "
+            "Review quality indicators and consider re-recording with better conditions."
+        )
+    elif confidence == "medium":
+        warnings.append(
+            "⚠️ MEDIUM CONFIDENCE: Results should be interpreted with caution. "
+            "Check quality indicators for specific issues."
+        )
+
+    return warnings
+
+
+def assess_jump_quality(
+    visibilities: NDArray[np.float64],
+    positions: NDArray[np.float64],
+    outlier_mask: NDArray[np.bool_] | None,
+    fps: float,
+    phases_detected: bool = True,
+    phase_count: int = 0,
+) -> QualityAssessment:
+    """
+    Convenience function for assessing jump analysis quality.
+
+    This is the main entry point for quality assessment, called from
+    dropjump and CMJ analysis modules.
+
+    Args:
+        visibilities: Array of visibility scores (0-1)
+        positions: Array of tracked positions
+        outlier_mask: Boolean array marking outliers (None if none detected)
+        fps: Video frame rate
+        phases_detected: Whether phases were successfully detected
+        phase_count: Number of phases detected
+
+    Returns:
+        QualityAssessment with confidence, indicators, and warnings
+    """
+    return assess_tracking_quality(
+        visibilities=visibilities,
+        positions=positions,
+        outlier_mask=outlier_mask,
+        fps=fps,
+        phases_detected=phases_detected,
+        phase_count=phase_count,
+    )