kinemotion 0.29.2__py3-none-any.whl → 0.30.0__py3-none-any.whl

kinemotion/api.py

@@ -18,6 +18,8 @@ from .core.auto_tuning import (
     analyze_video_sample,
     auto_tune_parameters,
 )
+from .core.cmj_metrics_validator import CMJMetricsValidator
+from .core.dropjump_metrics_validator import DropJumpMetricsValidator
 from .core.filtering import reject_outliers
 from .core.metadata import (
     AlgorithmConfig,
@@ -602,6 +604,16 @@ def process_dropjump_video(
         if verbose:
             print("Analysis complete!")
 
+        # Validate metrics against physiological bounds
+        validator = DropJumpMetricsValidator()
+        validation_result = validator.validate(metrics.to_dict())  # type: ignore[arg-type]
+        metrics.validation_result = validation_result
+
+        if verbose and validation_result.issues:
+            print("\n⚠️  Validation Results:")
+            for issue in validation_result.issues:
+                print(f"  [{issue.severity.value}] {issue.metric}: {issue.message}")
+
         return metrics
 
 
@@ -1038,6 +1050,16 @@ def process_cmj_video(
             print(f"Flight time: {metrics.flight_time*1000:.1f}ms")
             print(f"Countermovement depth: {metrics.countermovement_depth:.3f}m")
 
+        # Validate metrics against physiological bounds
+        validator = CMJMetricsValidator()
+        validation_result = validator.validate(metrics.to_dict()["data"])  # type: ignore[arg-type]
+        metrics.validation_result = validation_result
+
+        if verbose and validation_result.issues:
+            print("\n⚠️  Validation Results:")
+            for issue in validation_result.issues:
+                print(f"  [{issue.severity.value}] {issue.metric}: {issue.message}")
+
         return metrics
 
 

kinemotion/cmj/kinematics.py

@@ -9,6 +9,7 @@ from numpy.typing import NDArray
 from ..core.formatting import format_float_metric
 
 if TYPE_CHECKING:
+    from ..core.cmj_metrics_validator import ValidationResult
     from ..core.metadata import ResultMetadata
     from ..core.quality import QualityAssessment
 
@@ -32,11 +33,12 @@ class CMJDataDict(TypedDict, total=False):
     tracking_method: str
 
 
-class CMJResultDict(TypedDict):
+class CMJResultDict(TypedDict, total=False):
     """Type-safe dictionary for complete CMJ result with data and metadata."""
 
     data: CMJDataDict
     metadata: dict  # ResultMetadata.to_dict()
+    validation: dict  # ValidationResult.to_dict()
 
 
 @dataclass
@@ -60,6 +62,7 @@ class CMJMetrics:
         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
+        validation_result: Optional validation result with physiological bounds checks
     """
 
     jump_height: float
@@ -79,6 +82,7 @@ class CMJMetrics:
     tracking_method: str
     quality_assessment: "QualityAssessment | None" = None
     result_metadata: "ResultMetadata | None" = None
+    validation_result: "ValidationResult | None" = None
 
     def to_dict(self) -> CMJResultDict:
         """Convert metrics to JSON-serializable dictionary with data/metadata structure.
@@ -129,7 +133,13 @@ class CMJMetrics:
             # No metadata available
             metadata = {}
 
-        return {"data": data, "metadata": metadata}
+        result: CMJResultDict = {"data": data, "metadata": metadata}
+
+        # Include validation results if available
+        if self.validation_result is not None:
+            result["validation"] = self.validation_result.to_dict()
+
+        return result
 
 
 def calculate_cmj_metrics(

kinemotion/core/cmj_metrics_validator.py

@@ -121,6 +121,36 @@ class ValidationResult:
         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,
+            "height_flight_time_consistency_percent": (
+                self.height_flight_time_consistency
+            ),
+            "velocity_height_consistency_percent": self.velocity_height_consistency,
+            "depth_height_ratio": self.depth_height_ratio,
+            "contact_depth_ratio": self.contact_depth_ratio,
+        }
+
 
 class CMJMetricsValidator:
     """Comprehensive CMJ metrics validator."""
@@ -697,6 +727,70 @@ class CMJMetricsValidator:
                     value=ankle,
                 )
 
+        # Detect joint compensation patterns
+        self._check_joint_compensation_pattern(angles, result, profile)
+
+    def _check_joint_compensation_pattern(
+        self, angles: dict, result: ValidationResult, profile: AthleteProfile
+    ) -> None:
+        """Detect compensatory joint patterns in triple extension.
+
+        When one joint cannot achieve full extension, others may compensate.
+        Example: Limited hip extension (160°) with excessive knee extension (185°+)
+        suggests compensation rather than balanced movement quality.
+
+        This is a biomechanical quality indicator, not an error.
+        """
+        hip = angles.get("hip_angle")
+        knee = angles.get("knee_angle")
+        ankle = angles.get("ankle_angle")
+
+        if hip is None or knee is None or ankle is None:
+            return  # Need all three to detect patterns
+
+        # Get profile-specific bounds
+        if profile == AthleteProfile.ELDERLY:
+            hip_min, hip_max = 150, 175
+            knee_min, knee_max = 155, 175
+            ankle_min, ankle_max = 100, 125
+        elif profile in (AthleteProfile.UNTRAINED, AthleteProfile.RECREATIONAL):
+            hip_min, hip_max = 160, 180
+            knee_min, knee_max = 165, 182
+            ankle_min, ankle_max = 110, 140
+        elif profile in (AthleteProfile.TRAINED, AthleteProfile.ELITE):
+            hip_min, hip_max = 170, 185
+            knee_min, knee_max = 173, 190
+            ankle_min, ankle_max = 125, 155
+        else:
+            return
+
+        # Count how many joints are near their boundaries
+        joints_at_boundary = 0
+        boundary_threshold = 3.0  # degrees from limit
+
+        if hip <= hip_min + boundary_threshold or hip >= hip_max - boundary_threshold:
+            joints_at_boundary += 1
+        if (
+            knee <= knee_min + boundary_threshold
+            or knee >= knee_max - boundary_threshold
+        ):
+            joints_at_boundary += 1
+        if (
+            ankle <= ankle_min + boundary_threshold
+            or ankle >= ankle_max - boundary_threshold
+        ):
+            joints_at_boundary += 1
+
+        # If 2+ joints at boundaries, likely compensation pattern
+        if joints_at_boundary >= 2:
+            result.add_info(
+                "joint_compensation",
+                f"Multiple joints near extension limits (hip={hip:.0f}°, "
+                f"knee={knee:.0f}°, ankle={ankle:.0f}°). "
+                f"May indicate compensatory movement pattern.",
+                value=float(joints_at_boundary),
+            )
+
     @staticmethod
     def _get_profile_range(
         profile: AthleteProfile, bounds: MetricBounds

kinemotion/core/cmj_validation_bounds.py

@@ -356,7 +356,9 @@ ATHLETE_PROFILES = {
 }
 
 
-def estimate_athlete_profile(metrics_dict: dict) -> AthleteProfile:
+def estimate_athlete_profile(
+    metrics_dict: dict, gender: str | None = None
+) -> AthleteProfile:
     """Estimate athlete profile from metrics.
 
     Uses jump height as primary classifier:
@@ -365,6 +367,18 @@ def estimate_athlete_profile(metrics_dict: dict) -> AthleteProfile:
     - 0.35-0.65m: Recreational
     - 0.65-0.85m: Trained
     - >0.85m: Elite
+
+    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.
+    Example: Female athlete with 0.45m jump = Recreational male = Trained female.
+
+    Args:
+        metrics_dict: Dictionary with CMJ metric values
+        gender: Optional gender for context ("M"/"F"). Currently informational only.
+
+    Returns:
+        Estimated AthleteProfile
     """
     jump_height = metrics_dict.get("jump_height", 0)
 

kinemotion/core/dropjump_metrics_validator.py

@@ -0,0 +1,343 @@
+"""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 {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:
+            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 {percent_error:.1f}%. "
+                    f"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/dropjump/kinematics.py

@@ -16,6 +16,7 @@ from .analysis import (
 )
 
 if TYPE_CHECKING:
+    from ..core.dropjump_metrics_validator import ValidationResult
     from ..core.metadata import ResultMetadata
     from ..core.quality import QualityAssessment
 
@@ -39,11 +40,12 @@ class DropJumpDataDict(TypedDict, total=False):
     flight_end_frame_precise: float | None
 
 
-class DropJumpResultDict(TypedDict):
+class DropJumpResultDict(TypedDict, total=False):
     """Type-safe dictionary for complete drop jump result with data and metadata."""
 
     data: DropJumpDataDict
     metadata: dict  # ResultMetadata.to_dict()
+    validation: dict  # ValidationResult.to_dict()
 
 
 class DropJumpMetrics:
@@ -69,6 +71,8 @@ class DropJumpMetrics:
         self.quality_assessment: QualityAssessment | None = None
         # Complete metadata
         self.result_metadata: ResultMetadata | None = None
+        # Validation result
+        self.validation_result: ValidationResult | None = None
 
     def _build_data_dict(self) -> DropJumpDataDict:
         """Build the data portion of the result dictionary.
@@ -125,11 +129,17 @@ class DropJumpMetrics:
         Returns:
             Dictionary with nested data and metadata structure.
         """
-        return {
+        result: DropJumpResultDict = {
             "data": self._build_data_dict(),
             "metadata": self._build_metadata_dict(),
         }
 
+        # Include validation results if available
+        if self.validation_result is not None:
+            result["validation"] = self.validation_result.to_dict()
+
+        return result
+
 
 def _determine_drop_start_frame(
     drop_start_frame: int | None,

{kinemotion-0.29.2.dist-info → kinemotion-0.30.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.29.2
+Version: 0.30.0
 Summary: Video-based kinematic analysis for athletic performance
 Project-URL: Homepage, https://github.com/feniix/kinemotion
 Project-URL: Repository, https://github.com/feniix/kinemotion
@@ -36,6 +36,7 @@ Description-Content-Type: text/markdown
 [![Tests](https://github.com/feniix/kinemotion/workflows/Test%20%26%20Quality/badge.svg)](https://github.com/feniix/kinemotion/actions)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=feniix_kinemotion&metric=alert_status)](https://sonarcloud.io/summary/overall?id=feniix_kinemotion)
 [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=feniix_kinemotion&metric=coverage)](https://sonarcloud.io/summary/overall?id=feniix_kinemotion)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/11506/badge)](https://www.bestpractices.dev/projects/11506)
 
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![Type checked with pyright](https://img.shields.io/badge/type%20checked-pyright-blue.svg)](https://github.com/microsoft/pyright)
@@ -695,7 +696,7 @@ Before committing code, ensure all checks pass:
 1. Ensure type safety with pyright
 1. Run all tests with pytest
 
-See [CLAUDE.md](CLAUDE.md) for detailed development guidelines.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines and requirements, or [CLAUDE.md](CLAUDE.md) for detailed development guidelines.
 
 ## Limitations
 

{kinemotion-0.29.2.dist-info → kinemotion-0.30.0.dist-info}/RECORD

@@ -1,18 +1,20 @@
 kinemotion/__init__.py,sha256=sxdDOekOrIgjxm842gy-6zfq7OWmGl9ShJtXCm4JI7c,723
-kinemotion/api.py,sha256=tbkjXsfe0N0Bmik6XRIOYM7Nom4QqeQJSpDx7IoiuSA,38177
+kinemotion/api.py,sha256=ozt6GLZtw2ZWki0tBlkpOQgcNH_M7GfrRPlc_Rg8ROw,39284
 kinemotion/cli.py,sha256=cqYV_7URH0JUDy1VQ_EDLv63FmNO4Ns20m6s1XAjiP4,464
 kinemotion/cmj/__init__.py,sha256=Ynv0-Oco4I3Y1Ubj25m3h9h2XFqeNwpAewXmAYOmwfU,127
 kinemotion/cmj/analysis.py,sha256=il7-sfM89ZetxLhmw9boViaP4E8Y3mlS_XI-B5txmMs,19795
 kinemotion/cmj/cli.py,sha256=12FEfWrseG4kCUbgHHdBPkWp6zzVQ0VAzfgNJotArmM,10792
 kinemotion/cmj/debug_overlay.py,sha256=D-y2FQKI01KY0WXFKTKg6p9Qj3AkXCE7xjau3Ais080,15886
 kinemotion/cmj/joint_angles.py,sha256=HmheIEiKcQz39cRezk4h-htorOhGNPsqKIR9RsAEKts,9960
-kinemotion/cmj/kinematics.py,sha256=-iBFg2AkQR4LaThCQzO09fx6qJed27ZfMDQJgE7Si4k,9772
+kinemotion/cmj/kinematics.py,sha256=ax2RijtAWItZPNRmNr-CvC7bOSsZQw2qdCEnm5hUUpU,10247
 kinemotion/core/__init__.py,sha256=HsqolRa60cW3vrG8F9Lvr9WvWcs5hCmsTzSgo7imi-4,1278
 kinemotion/core/auto_tuning.py,sha256=j6cul_qC6k0XyryCG93C1AWH2MKPj3UBMzuX02xaqfI,11235
 kinemotion/core/cli_utils.py,sha256=Pq1JF7yvK1YbH0tOUWKjplthCbWsJQt4Lv7esPYH4FM,7254
-kinemotion/core/cmj_metrics_validator.py,sha256=Jfh8oxhxz5BCBIPdeMRHa60tZsliDkN10RiLQYkmck4,27262
-kinemotion/core/cmj_validation_bounds.py,sha256=WBMuJx6ewb-rYan3xmQu32m7bs9h8J5isa4LduZuZkI,13507
+kinemotion/core/cmj_metrics_validator.py,sha256=bbOPTbFqDEZv3lDA8qejjCcMqXE7TYvHizCcWzHRW9Y,30902
+kinemotion/core/cmj_validation_bounds.py,sha256=NXW0d4S8hDqSkzAiyX9UyWDnKsWf61ygEKTKE2a1uNc,14069
 kinemotion/core/debug_overlay_utils.py,sha256=TyUb5okv5qw8oeaX3jsUO_kpwf1NnaHEAOTm-8LwTno,4587
+kinemotion/core/dropjump_metrics_validator.py,sha256=yGcg8ub6Z791qj5BxCn9mHin608tfxvxxfIeTql8HcY,11967
+kinemotion/core/dropjump_validation_bounds.py,sha256=Ow7T-0IK_qy0k9UZdiCuT_tttxklWAkuXFalQkF8Jbs,6927
 kinemotion/core/filtering.py,sha256=f-m-aA59e4WqE6u-9MA51wssu7rI-Y_7n1cG8IWdeRQ,11241
 kinemotion/core/formatting.py,sha256=G_3eqgOtym9RFOZVEwCxye4A2cyrmgvtQ214vIshowU,2480
 kinemotion/core/metadata.py,sha256=PyGHL6sx7Hj21lyorg2VsWP9BGTj_y_-wWU6eKCEfJo,6817
@@ -24,10 +26,10 @@ kinemotion/dropjump/__init__.py,sha256=yc1XiZ9vfo5h_n7PKVSiX2TTgaIfGL7Y7SkQtiDZj
 kinemotion/dropjump/analysis.py,sha256=BQ5NqSPNJjFQOb-W4bXSLvjCgWd-nvqx5NElyeqZJC4,29067
 kinemotion/dropjump/cli.py,sha256=ZyroaYPwz8TgfL39Wcaj6m68Awl6lYXC75ttaflU-c0,16236
 kinemotion/dropjump/debug_overlay.py,sha256=LkPw6ucb7beoYWS4L-Lvjs1KLCm5wAWDAfiznUeV2IQ,5668
-kinemotion/dropjump/kinematics.py,sha256=Yr3G7AQwtYy1dxyeOAYfqqgd4pzoZwWQAhZzxI5RbnE,16658
+kinemotion/dropjump/kinematics.py,sha256=AfqIS8kaI3B8olPX9EY1QxQsuNmuJA5GRsI1EL4NHHg,17091
 kinemotion/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kinemotion-0.29.2.dist-info/METADATA,sha256=ISixUGRnj_7NlQFCRm7BvHG3LWQXjGUS5LiOBHHtfeE,25810
-kinemotion-0.29.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-kinemotion-0.29.2.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
-kinemotion-0.29.2.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
-kinemotion-0.29.2.dist-info/RECORD,,
+kinemotion-0.30.0.dist-info/METADATA,sha256=AUhSzQW2siu-R4KfUyS5YRDy1i9eYzzYxOMdWZXF2ww,26020
+kinemotion-0.30.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+kinemotion-0.30.0.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
+kinemotion-0.30.0.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
+kinemotion-0.30.0.dist-info/RECORD,,