kinemotion 0.29.3__py3-none-any.whl → 0.31.0__py3-none-any.whl

kinemotion/core/dropjump_metrics_validator.py

@@ -0,0 +1,346 @@
+"""Drop jump metrics validation using physiological bounds.
+
+Comprehensive validation of Drop Jump metrics against biomechanical bounds,
+consistency checks, and cross-validation of RSI calculation.
+
+Provides severity levels (ERROR, WARNING, INFO) for different categories
+of metric issues.
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+from kinemotion.core.dropjump_validation_bounds import (
+    AthleteProfile,
+    DropJumpBounds,
+    estimate_athlete_profile,
+)
+
+
+class ValidationSeverity(Enum):
+    """Severity level for validation issues."""
+
+    ERROR = "ERROR"  # Metrics invalid, likely data corruption
+    WARNING = "WARNING"  # Metrics valid but unusual, needs review
+    INFO = "INFO"  # Normal variation, informational only
+
+
+@dataclass
+class ValidationIssue:
+    """Single validation issue."""
+
+    severity: ValidationSeverity
+    metric: str
+    message: str
+    value: float | None = None
+    bounds: tuple[float, float] | None = None
+
+
+@dataclass
+class ValidationResult:
+    """Complete validation result for drop jump metrics."""
+
+    issues: list[ValidationIssue] = field(default_factory=list)
+    status: str = "PASS"  # "PASS", "PASS_WITH_WARNINGS", "FAIL"
+    athlete_profile: AthleteProfile | None = None
+    rsi: float | None = None
+    contact_flight_ratio: float | None = None
+    height_kinematic_trajectory_consistency: float | None = None  # % error
+
+    def add_error(
+        self,
+        metric: str,
+        message: str,
+        value: float | None = None,
+        bounds: tuple[float, float] | None = None,
+    ) -> None:
+        """Add error-level issue."""
+        self.issues.append(
+            ValidationIssue(
+                severity=ValidationSeverity.ERROR,
+                metric=metric,
+                message=message,
+                value=value,
+                bounds=bounds,
+            )
+        )
+
+    def add_warning(
+        self,
+        metric: str,
+        message: str,
+        value: float | None = None,
+        bounds: tuple[float, float] | None = None,
+    ) -> None:
+        """Add warning-level issue."""
+        self.issues.append(
+            ValidationIssue(
+                severity=ValidationSeverity.WARNING,
+                metric=metric,
+                message=message,
+                value=value,
+                bounds=bounds,
+            )
+        )
+
+    def add_info(
+        self,
+        metric: str,
+        message: str,
+        value: float | None = None,
+    ) -> None:
+        """Add info-level issue."""
+        self.issues.append(
+            ValidationIssue(
+                severity=ValidationSeverity.INFO,
+                metric=metric,
+                message=message,
+                value=value,
+            )
+        )
+
+    def finalize_status(self) -> None:
+        """Determine final pass/fail status based on issues."""
+        has_errors = any(
+            issue.severity == ValidationSeverity.ERROR for issue in self.issues
+        )
+        has_warnings = any(
+            issue.severity == ValidationSeverity.WARNING for issue in self.issues
+        )
+
+        if has_errors:
+            self.status = "FAIL"
+        elif has_warnings:
+            self.status = "PASS_WITH_WARNINGS"
+        else:
+            self.status = "PASS"
+
+    def to_dict(self) -> dict:
+        """Convert validation result to JSON-serializable dictionary.
+
+        Returns:
+            Dictionary with status, issues, and consistency metrics.
+        """
+        return {
+            "status": self.status,
+            "issues": [
+                {
+                    "severity": issue.severity.value,
+                    "metric": issue.metric,
+                    "message": issue.message,
+                    "value": issue.value,
+                    "bounds": issue.bounds,
+                }
+                for issue in self.issues
+            ],
+            "athlete_profile": (
+                self.athlete_profile.value if self.athlete_profile else None
+            ),
+            "rsi": self.rsi,
+            "contact_flight_ratio": self.contact_flight_ratio,
+            "height_kinematic_trajectory_consistency_percent": (
+                self.height_kinematic_trajectory_consistency
+            ),
+        }
+
+
+class DropJumpMetricsValidator:
+    """Comprehensive drop jump metrics validator."""
+
+    def __init__(self, assumed_profile: AthleteProfile | None = None):
+        """Initialize validator.
+
+        Args:
+            assumed_profile: If provided, validate against this specific profile.
+                            Otherwise, estimate from metrics.
+        """
+        self.assumed_profile = assumed_profile
+
+    def validate(self, metrics: dict) -> ValidationResult:
+        """Validate drop jump metrics comprehensively.
+
+        Args:
+            metrics: Dictionary with drop jump metric values
+
+        Returns:
+            ValidationResult with all issues and status
+        """
+        result = ValidationResult()
+
+        # Estimate athlete profile if not provided
+        if self.assumed_profile:
+            result.athlete_profile = self.assumed_profile
+        else:
+            result.athlete_profile = estimate_athlete_profile(metrics)
+
+        # Extract metric values (handle nested "data" structure)
+        data = metrics.get("data", metrics)  # Support both structures
+
+        contact_time_ms = data.get("ground_contact_time_ms")
+        flight_time_ms = data.get("flight_time_ms")
+        jump_height_m = data.get("jump_height_m")
+        jump_height_kinematic_m = data.get("jump_height_kinematic_m")
+        jump_height_trajectory_m = data.get("jump_height_trajectory_normalized")
+
+        # Validate individual metrics
+        if contact_time_ms is not None:
+            self._check_contact_time(contact_time_ms, result)
+
+        if flight_time_ms is not None:
+            self._check_flight_time(flight_time_ms, result)
+
+        if jump_height_m is not None:
+            self._check_jump_height(jump_height_m, result)
+
+        # Cross-validation
+        if contact_time_ms is not None and flight_time_ms is not None:
+            self._check_rsi(contact_time_ms, flight_time_ms, result)
+
+        # Dual height validation (kinematic vs trajectory)
+        if jump_height_kinematic_m is not None and jump_height_trajectory_m is not None:
+            self._check_dual_height_consistency(
+                jump_height_kinematic_m, jump_height_trajectory_m, result
+            )
+
+        # Finalize status
+        result.finalize_status()
+
+        return result
+
+    def _check_contact_time(
+        self, contact_time_ms: float, result: ValidationResult
+    ) -> None:
+        """Validate contact time."""
+        contact_time_s = contact_time_ms / 1000.0
+        bounds = DropJumpBounds.CONTACT_TIME
+
+        if not bounds.is_physically_possible(contact_time_s):
+            result.add_error(
+                "contact_time",
+                f"Contact time {contact_time_s:.3f}s physically impossible",
+                value=contact_time_s,
+                bounds=(bounds.absolute_min, bounds.absolute_max),
+            )
+        elif result.athlete_profile and not bounds.contains(
+            contact_time_s, result.athlete_profile
+        ):
+            profile_name = result.athlete_profile.value
+            result.add_warning(
+                "contact_time",
+                f"Contact time {contact_time_s:.3f}s unusual for "
+                f"{profile_name} athlete",
+                value=contact_time_s,
+            )
+
+    def _check_flight_time(
+        self, flight_time_ms: float, result: ValidationResult
+    ) -> None:
+        """Validate flight time."""
+        flight_time_s = flight_time_ms / 1000.0
+        bounds = DropJumpBounds.FLIGHT_TIME
+
+        if not bounds.is_physically_possible(flight_time_s):
+            result.add_error(
+                "flight_time",
+                f"Flight time {flight_time_s:.3f}s physically impossible",
+                value=flight_time_s,
+                bounds=(bounds.absolute_min, bounds.absolute_max),
+            )
+        elif result.athlete_profile and not bounds.contains(
+            flight_time_s, result.athlete_profile
+        ):
+            profile_name = result.athlete_profile.value
+            result.add_warning(
+                "flight_time",
+                f"Flight time {flight_time_s:.3f}s unusual for {profile_name} athlete",
+                value=flight_time_s,
+            )
+
+    def _check_jump_height(
+        self, jump_height_m: float, result: ValidationResult
+    ) -> None:
+        """Validate jump height."""
+        bounds = DropJumpBounds.JUMP_HEIGHT
+
+        if not bounds.is_physically_possible(jump_height_m):
+            result.add_error(
+                "jump_height",
+                f"Jump height {jump_height_m:.3f}m physically impossible",
+                value=jump_height_m,
+                bounds=(bounds.absolute_min, bounds.absolute_max),
+            )
+        elif result.athlete_profile and not bounds.contains(
+            jump_height_m, result.athlete_profile
+        ):
+            profile_name = result.athlete_profile.value
+            result.add_warning(
+                "jump_height",
+                f"Jump height {jump_height_m:.3f}m unusual for {profile_name} athlete",
+                value=jump_height_m,
+            )
+
+    def _check_rsi(
+        self, contact_time_ms: float, flight_time_ms: float, result: ValidationResult
+    ) -> None:
+        """Validate RSI and cross-check consistency."""
+        contact_time_s = contact_time_ms / 1000.0
+        flight_time_s = flight_time_ms / 1000.0
+
+        if contact_time_s > 0 and flight_time_s > 0:
+            rsi = flight_time_s / contact_time_s
+            result.rsi = rsi
+            result.contact_flight_ratio = contact_time_s / flight_time_s
+
+            bounds = DropJumpBounds.RSI
+
+            if not bounds.is_physically_possible(rsi):
+                result.add_error(
+                    "rsi",
+                    f"RSI {rsi:.2f} physically impossible",
+                    value=rsi,
+                    bounds=(bounds.absolute_min, bounds.absolute_max),
+                )
+            elif result.athlete_profile and not bounds.contains(
+                rsi, result.athlete_profile
+            ):
+                result.add_warning(
+                    "rsi",
+                    f"RSI {rsi:.2f} unusual for {result.athlete_profile.value} athlete",
+                    value=rsi,
+                )
+
+    def _check_dual_height_consistency(
+        self,
+        jump_height_kinematic_m: float,
+        jump_height_trajectory_m: float,
+        result: ValidationResult,
+    ) -> None:
+        """Validate consistency between kinematic and trajectory-based heights.
+
+        Kinematic height (h = g*t²/8) comes from flight time (objective).
+        Trajectory height comes from position tracking (subject to landmark
+        detection noise).
+
+        Expected correlation: r > 0.95, absolute difference < 5% for quality video.
+        """
+        if jump_height_kinematic_m <= 0 or jump_height_trajectory_m <= 0:
+            return  # Skip if either value is missing or invalid
+
+        # Calculate percentage difference
+        avg_height = (jump_height_kinematic_m + jump_height_trajectory_m) / 2.0
+        if avg_height > 0:
+            abs_diff = abs(jump_height_kinematic_m - jump_height_trajectory_m)
+            percent_error = (abs_diff / avg_height) * 100.0
+            result.height_kinematic_trajectory_consistency = percent_error
+
+            # Allow 10% tolerance for typical video processing noise
+            if percent_error > 10.0:
+                result.add_warning(
+                    "height_consistency",
+                    f"Kinematic ({jump_height_kinematic_m:.3f}m) and trajectory "
+                    f"({jump_height_trajectory_m:.3f}m) heights differ by "
+                    f"{percent_error:.1f}%. May indicate landmark detection "
+                    "issues or video quality problems.",
+                    value=percent_error,
+                    bounds=(0, 10),
+                )

kinemotion/core/dropjump_validation_bounds.py

@@ -0,0 +1,196 @@
+"""Drop jump metrics physiological bounds for validation testing.
+
+This module defines realistic physiological bounds for Drop Jump metrics
+based on biomechanical literature and real-world athlete performance.
+
+Drop jump metrics differ from CMJ:
+- Contact time (ground interaction during landing)
+- Flight time (time in air after landing)
+- RSI (Reactive Strength Index) = flight_time / contact_time
+- Jump height (calculated from flight time)
+
+References:
+- Komi & Bosco (1978): Drop jump RSI and elastic properties
+- Flanagan & Comyns (2008): RSI reliability and athlete assessment
+- Covens et al. (2019): Drop jump kinetics across athletes
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class AthleteProfile(Enum):
+    """Athlete performance categories for metric bounds."""
+
+    ELDERLY = "elderly"  # 70+, deconditioned
+    UNTRAINED = "untrained"  # Sedentary, no training
+    RECREATIONAL = "recreational"  # Fitness class, moderate activity
+    TRAINED = "trained"  # Regular athlete, 3-5 years training
+    ELITE = "elite"  # Competitive athlete, college/professional level
+
+
+@dataclass
+class MetricBounds:
+    """Physiological bounds for a single metric.
+
+    Attributes:
+        absolute_min: Absolute minimum value (error threshold)
+        practical_min: Practical minimum for weakest athletes
+        recreational_min: Minimum for recreational athletes
+        recreational_max: Maximum for recreational athletes
+        elite_min: Minimum for elite athletes
+        elite_max: Maximum for elite athletes
+        absolute_max: Absolute maximum value (error threshold)
+        unit: Unit of measurement (e.g., "s", "m", "ratio")
+    """
+
+    absolute_min: float
+    practical_min: float
+    recreational_min: float
+    recreational_max: float
+    elite_min: float
+    elite_max: float
+    absolute_max: float
+    unit: str
+
+    def contains(self, value: float, profile: AthleteProfile) -> bool:
+        """Check if value is within bounds for athlete profile."""
+        if profile == AthleteProfile.ELDERLY:
+            return self.practical_min <= value <= self.recreational_max
+        elif profile == AthleteProfile.UNTRAINED:
+            return self.practical_min <= value <= self.recreational_max
+        elif profile == AthleteProfile.RECREATIONAL:
+            return self.recreational_min <= value <= self.recreational_max
+        elif profile == AthleteProfile.TRAINED:
+            # Trained athletes: midpoint between recreational and elite
+            trained_min = (self.recreational_min + self.elite_min) / 2
+            trained_max = (self.recreational_max + self.elite_max) / 2
+            return trained_min <= value <= trained_max
+        elif profile == AthleteProfile.ELITE:
+            return self.elite_min <= value <= self.elite_max
+        return False
+
+    def is_physically_possible(self, value: float) -> bool:
+        """Check if value is within absolute physiological limits."""
+        return self.absolute_min <= value <= self.absolute_max
+
+
+class DropJumpBounds:
+    """Collection of physiological bounds for all drop jump metrics."""
+
+    # GROUND CONTACT TIME (seconds, landing interaction)
+    CONTACT_TIME = MetricBounds(
+        absolute_min=0.08,  # Physiological minimum: neural delay + deceleration
+        practical_min=0.15,  # Extreme plyometric
+        recreational_min=0.35,  # Typical landing
+        recreational_max=0.70,  # Slower absorption
+        elite_min=0.20,
+        elite_max=0.50,
+        absolute_max=1.50,
+        unit="s",
+    )
+
+    # FLIGHT TIME (seconds, after landing)
+    FLIGHT_TIME = MetricBounds(
+        absolute_min=0.30,
+        practical_min=0.40,  # Minimal jump
+        recreational_min=0.50,
+        recreational_max=0.85,
+        elite_min=0.65,
+        elite_max=1.10,
+        absolute_max=1.40,
+        unit="s",
+    )
+
+    # JUMP HEIGHT (meters, calculated from flight time)
+    JUMP_HEIGHT = MetricBounds(
+        absolute_min=0.05,
+        practical_min=0.10,
+        recreational_min=0.25,
+        recreational_max=0.65,
+        elite_min=0.50,
+        elite_max=1.00,
+        absolute_max=1.30,
+        unit="m",
+    )
+
+    # REACTIVE STRENGTH INDEX (RSI) = flight_time / contact_time (ratio, no unit)
+    RSI = MetricBounds(
+        absolute_min=0.30,  # Very poor reactive ability
+        practical_min=0.50,
+        recreational_min=0.70,
+        recreational_max=1.80,
+        elite_min=1.50,  # Elite: fast contact, long flight
+        elite_max=3.50,
+        absolute_max=5.00,
+        unit="ratio",
+    )
+
+
+def estimate_athlete_profile(
+    metrics: dict, gender: str | None = None
+) -> AthleteProfile:
+    """Estimate athlete profile from drop jump metrics.
+
+    Uses jump_height and contact_time to classify athlete level.
+
+    NOTE: Bounds are calibrated for adult males. Female athletes typically achieve
+    60-70% of male heights due to lower muscle mass and strength. If analyzing
+    female athletes, interpret results one level lower than classification suggests.
+
+    Args:
+        metrics: Dictionary with drop jump metric values
+        gender: Optional gender for context ("M"/"F"). Currently informational only.
+
+    Returns:
+        Estimated AthleteProfile (ELDERLY, UNTRAINED, RECREATIONAL, TRAINED, or ELITE)
+    """
+    jump_height = metrics.get("data", {}).get("jump_height_m")
+    contact_time = metrics.get("data", {}).get("ground_contact_time_ms")
+
+    if jump_height is None or contact_time is None:
+        return AthleteProfile.RECREATIONAL  # Default
+
+    # Convert contact_time from ms to seconds
+    contact_time_s = contact_time / 1000.0
+
+    # Decision logic: Use weighted combination to avoid over-weighting single metrics
+    # Calculate profile scores based on each metric
+    height_score = 0.0
+    if jump_height < 0.25:
+        height_score = 0  # Elderly
+    elif jump_height < 0.35:
+        height_score = 1  # Untrained
+    elif jump_height < 0.50:
+        height_score = 2  # Recreational
+    elif jump_height < 0.70:
+        height_score = 3  # Trained
+    else:
+        height_score = 4  # Elite
+
+    contact_score = 0.0
+    if contact_time_s > 0.60:
+        contact_score = 0  # Elderly
+    elif contact_time_s > 0.50:
+        contact_score = 1  # Untrained
+    elif contact_time_s > 0.45:
+        contact_score = 2  # Recreational
+    elif contact_time_s > 0.40:
+        contact_score = 3  # Trained
+    else:
+        contact_score = 4  # Elite
+
+    # Weight height more heavily (70%) than contact time (30%)
+    # Height is more reliable indicator across populations
+    combined_score = (height_score * 0.70) + (contact_score * 0.30)
+
+    if combined_score < 1.0:
+        return AthleteProfile.ELDERLY
+    elif combined_score < 1.7:
+        return AthleteProfile.UNTRAINED
+    elif combined_score < 2.7:
+        return AthleteProfile.RECREATIONAL
+    elif combined_score < 3.7:
+        return AthleteProfile.TRAINED
+    else:
+        return AthleteProfile.ELITE

kinemotion/core/metadata.py

@@ -146,7 +146,8 @@ class AlgorithmConfig:
     """Complete algorithm configuration for reproducibility.
 
     Attributes:
-        detection_method: Algorithm used ("backward_search" for CMJ, "forward_search" for drop)
+        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

kinemotion/core/quality.py

@@ -307,8 +307,9 @@ def _generate_warnings(
     # 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."
+            f"Unstable landmark tracking detected "
+            f"(variance {indicators.position_variance:.4f}). This may indicate "
+            "jitter or occlusion. Consider better lighting or camera position."
         )
 
     # Outlier warnings
@@ -349,8 +350,8 @@ def _generate_warnings(
     # Overall confidence warning
     if confidence == "low":
         warnings.append(
-            "⚠️ LOW CONFIDENCE: Results may be unreliable. "
-            "Review quality indicators and consider re-recording with better conditions."
+            "⚠️ LOW CONFIDENCE: Results may be unreliable. Review quality "
+            "indicators and consider re-recording with better conditions."
         )
     elif confidence == "medium":
         warnings.append(

kinemotion/core/smoothing.py

@@ -124,7 +124,8 @@ def _store_smoothed_landmarks(
             )
 
 
-def _smooth_landmarks_core(  # NOSONAR(S1172) - polyorder used via closure capture in smoother_fn
+def _smooth_landmarks_core(  # NOSONAR(S1172) - polyorder used via closure
+    # capture in smoother_fn
     landmark_sequence: LandmarkSequence,
     window_length: int,
     polyorder: int,
@@ -136,7 +137,8 @@ def _smooth_landmarks_core(  # NOSONAR(S1172) - polyorder used via closure captu
     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 (captured by smoother_fn closure)
+        polyorder: Order of polynomial used to fit samples (captured by
+            smoother_fn closure)
         smoother_fn: Function that takes (x_coords, y_coords, valid_frames)
             and returns (x_smooth, y_smooth)
 

kinemotion/core/video_io.py

@@ -46,8 +46,9 @@ class VideoProcessor:
             self.width = int(self.cap.get(cv2.CAP_PROP_FRAME_WIDTH))
             self.height = int(self.cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
 
-        # Extract rotation metadata from video (iPhones store rotation in side_data_list)
-        # OpenCV ignores rotation metadata, so we need to extract and apply it manually
+        # Extract rotation metadata from video (iPhones store rotation in
+        # side_data_list). OpenCV ignores rotation metadata, so we need to
+        # extract and apply it manually
         self.rotation = 0  # Will be set by _extract_video_metadata()
 
         # Extract codec information from video metadata

kinemotion/dropjump/analysis.py

@@ -98,7 +98,8 @@ def _find_stable_baseline(
     """Find first stable period and return baseline position.
 
     Returns:
-        Tuple of (baseline_start_frame, baseline_position). Returns (-1, 0.0) if not found.
+        Tuple of (baseline_start_frame, baseline_position). Returns (-1, 0.0)
+        if not found.
     """
     stable_window = min_stable_frames
 
@@ -159,8 +160,8 @@ def _find_drop_from_baseline(
                     f"{position_change_threshold:.4f}"
                 )
                 print(
-                    f"  avg_position: {avg_position:.4f} vs "
-                    f"baseline: {baseline_position:.4f}"
+                    f"  avg_position: {avg_position:.4f} vs baseline: "
+                    f"{baseline_position:.4f}"
                 )
 
             return drop_frame
@@ -179,7 +180,8 @@ def detect_drop_start(
     debug: bool = False,
 ) -> int:
     """
-    Detect when the drop jump actually starts by finding stable period then detecting drop.
+    Detect when the drop jump actually starts by finding stable period then
+    detecting drop.
 
     Strategy:
     1. Scan forward to find first STABLE period (low variance over N frames)
@@ -191,7 +193,8 @@ def detect_drop_start(
     Args:
         positions: Array of vertical positions (0-1 normalized, y increases downward)
         fps: Video frame rate
-        min_stationary_duration: Minimum duration (seconds) of stable period (default: 1.0s)
+        min_stationary_duration: Minimum duration (seconds) of stable period
+            (default: 1.0s)
         position_change_threshold: Position change indicating start of drop
             (default: 0.02 = 2% of frame)
         smoothing_window: Window for computing position variance
@@ -832,9 +835,11 @@ def extract_foot_positions_and_visibilities(
     smoothed_landmarks: list[dict[str, tuple[float, float, float]] | None],
 ) -> tuple[np.ndarray, np.ndarray]:
     """
-    Extract vertical positions and average visibilities from smoothed landmarks.
+    Extract vertical positions and average visibilities from smoothed
+    landmarks.
 
-    This utility function eliminates code duplication between CLI and programmatic usage.
+    This utility function eliminates code duplication between CLI and
+    programmatic usage.
 
     Args:
         smoothed_landmarks: Smoothed landmark sequence from tracking

kinemotion/dropjump/cli.py

@@ -133,7 +133,8 @@ class AnalysisParameters:
     default=None,
     help="[EXPERT] Override pose tracking confidence",
 )
-def dropjump_analyze(  # NOSONAR(S107) - Click CLI requires individual parameters for each option
+def dropjump_analyze(  # NOSONAR(S107) - Click CLI requires individual
+    # parameters for each option
     video_path: tuple[str, ...],
     output: str | None,
     json_output: str | None,
@@ -153,10 +154,12 @@ def dropjump_analyze(  # NOSONAR(S107) - Click CLI requires individual parameter
     tracking_confidence: float | None,
 ) -> None:
     """
-    Analyze drop-jump video(s) to estimate ground contact time, flight time, and jump height.
+    Analyze drop-jump video(s) to estimate ground contact time, flight time,
+    and jump height.
 
-    Uses intelligent auto-tuning to select optimal parameters based on video characteristics.
-    Parameters are automatically adjusted for frame rate, tracking quality, and analysis preset.
+    Uses intelligent auto-tuning to select optimal parameters based on video
+    characteristics. Parameters are automatically adjusted for frame rate,
+    tracking quality, and analysis preset.
 
     VIDEO_PATH: Path(s) to video file(s). Supports glob patterns in batch mode
     (e.g., "videos/*.mp4").