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

kinemotion/dropjump/cli.py

@@ -6,37 +6,15 @@ import json
 import sys
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any
 
 import click
-import numpy as np
 
 from ..api import (
     DropJumpVideoConfig,
     DropJumpVideoResult,
+    process_dropjump_video,
     process_dropjump_videos_bulk,
 )
-from ..core.auto_tuning import (
-    QualityPreset,
-    analyze_video_sample,
-    auto_tune_parameters,
-)
-from ..core.cli_utils import (
-    apply_expert_param_overrides,
-    determine_initial_confidence,
-    print_auto_tuned_params,
-    smooth_landmark_sequence,
-    track_all_frames,
-)
-from ..core.pose import PoseTracker
-from ..core.video_io import VideoProcessor
-from .analysis import (
-    ContactState,
-    detect_ground_contact,
-    extract_foot_positions_and_visibilities,
-)
-from .debug_overlay import DebugOverlayRenderer
-from .kinematics import DropJumpMetrics, calculate_drop_jump_metrics
 
 
 @dataclass
@@ -250,81 +228,6 @@ def dropjump_analyze(  # NOSONAR(S107) - Click CLI requires individual parameter
         )
 
 
-def _extract_positions_and_visibilities(
-    smoothed_landmarks: list,
-) -> tuple[np.ndarray, np.ndarray]:
-    """Extract vertical positions and visibilities from landmarks.
-
-    Args:
-        smoothed_landmarks: Smoothed landmark sequence
-
-    Returns:
-        Tuple of (vertical_positions, visibilities)
-    """
-    click.echo("Extracting foot positions...", err=True)
-    return extract_foot_positions_and_visibilities(smoothed_landmarks)
-
-
-def _create_debug_video(
-    output: str,
-    video: VideoProcessor,
-    frames: list,
-    smoothed_landmarks: list,
-    contact_states: list[ContactState],
-    metrics: DropJumpMetrics,
-) -> None:
-    """Generate debug video with overlays.
-
-    Args:
-        output: Output video path
-        video: Video processor
-        frames: Video frames
-        smoothed_landmarks: Smoothed landmarks
-        contact_states: Contact states
-        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 DebugOverlayRenderer(
-        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],
-                    contact_states[i],
-                    i,
-                    metrics,
-                    use_com=False,
-                )
-                renderer.write_frame(annotated)
-                render_bar.update(1)
-
-    click.echo(f"Debug video saved: {output}", err=True)
-
-
 def _process_single(
     video_path: str,
     output: str | None,
@@ -333,96 +236,38 @@ def _process_single(
     verbose: bool,
     expert_params: AnalysisParameters,
 ) -> None:
-    """Process a single video (original CLI behavior)."""
+    """Process a single video by calling the API."""
     click.echo(f"Analyzing video: {video_path}", err=True)
 
-    quality_preset = QualityPreset(quality.lower())
-
     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)
-
-            # Show parameters if verbose
-            if verbose:
-                print_auto_tuned_params(video, quality_preset, params, characteristics)
-
-            # Apply smoothing
-            smoothed_landmarks = smooth_landmark_sequence(landmarks_sequence, params)
-
-            # Extract positions
-            vertical_positions, visibilities = _extract_positions_and_visibilities(
-                smoothed_landmarks
-            )
-
-            # Detect ground contact
-            contact_states = detect_ground_contact(
-                vertical_positions,
-                velocity_threshold=params.velocity_threshold,
-                min_contact_frames=params.min_contact_frames,
-                visibility_threshold=params.visibility_threshold,
-                visibilities=visibilities,
-                window_length=params.smoothing_window,
-                polyorder=params.polyorder,
-            )
-
-            # Calculate metrics
-            click.echo("Calculating metrics...", err=True)
-            metrics = calculate_drop_jump_metrics(
-                contact_states,
-                vertical_positions,
-                video.fps,
-                drop_start_frame=expert_params.drop_start_frame,
-                velocity_threshold=params.velocity_threshold,
-                smoothing_window=params.smoothing_window,
-                polyorder=params.polyorder,
-                use_curvature=params.use_curvature,
-            )
-
-            # Output metrics
-            metrics_json = json.dumps(metrics.to_dict(), indent=2)
-            if json_output:
-                Path(json_output).write_text(metrics_json)
-                click.echo(f"Metrics written to: {json_output}", err=True)
-            else:
-                click.echo(metrics_json)
+        # Call the API function (handles all processing logic)
+        metrics = process_dropjump_video(
+            video_path=video_path,
+            quality=quality,
+            output_video=output,
+            json_output=json_output,
+            drop_start_frame=expert_params.drop_start_frame,
+            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, contact_states, metrics
-                )
+        # Print formatted summary to stdout if no JSON output specified
+        if not json_output:
+            click.echo(json.dumps(metrics.to_dict(), indent=2))
 
-            click.echo("Analysis complete!", err=True)
+        click.echo("Analysis complete!", err=True)
 
     except Exception as e:
         click.echo(f"Error: {str(e)}", err=True)
+        if verbose:
+            import traceback
+
+            traceback.print_exc()
         sys.exit(1)
 
 

kinemotion/dropjump/kinematics.py

@@ -1,6 +1,6 @@
 """Kinematic calculations for drop-jump metrics."""
 
-from typing import TypedDict
+from typing import TYPE_CHECKING, TypedDict
 
 import numpy as np
 from numpy.typing import NDArray
@@ -14,9 +14,13 @@ from .analysis import (
     find_landing_from_acceleration,
 )
 
+if TYPE_CHECKING:
+    from ..core.metadata import ResultMetadata
+    from ..core.quality import QualityAssessment
 
-class DropJumpMetricsDict(TypedDict, total=False):
-    """Type-safe dictionary for drop jump metrics JSON output."""
+
+class DropJumpDataDict(TypedDict, total=False):
+    """Type-safe dictionary for drop jump measurement data."""
 
     ground_contact_time_ms: float | None
     flight_time_ms: float | None
@@ -34,6 +38,13 @@ class DropJumpMetricsDict(TypedDict, total=False):
     flight_end_frame_precise: float | None
 
 
+class DropJumpResultDict(TypedDict):
+    """Type-safe dictionary for complete drop jump result with data and metadata."""
+
+    data: DropJumpDataDict
+    metadata: dict  # ResultMetadata.to_dict()
+
+
 class DropJumpMetrics:
     """Container for drop-jump analysis metrics."""
 
@@ -53,10 +64,18 @@ class DropJumpMetrics:
         self.contact_end_frame_precise: float | None = None
         self.flight_start_frame_precise: float | None = None
         self.flight_end_frame_precise: float | None = None
-
-    def to_dict(self) -> DropJumpMetricsDict:
-        """Convert metrics to dictionary for JSON output."""
-        return {
+        # Quality assessment
+        self.quality_assessment: QualityAssessment | None = None
+        # Complete metadata
+        self.result_metadata: ResultMetadata | None = None
+
+    def to_dict(self) -> DropJumpResultDict:
+        """Convert metrics to JSON-serializable dictionary with data/metadata structure.
+
+        Returns:
+            Dictionary with nested data and metadata structure.
+        """
+        data: DropJumpDataDict = {
             "ground_contact_time_ms": (
                 round(self.ground_contact_time * 1000, 2)
                 if self.ground_contact_time is not None
@@ -127,6 +146,18 @@ class DropJumpMetrics:
             ),
         }
 
+        # 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 _determine_drop_start_frame(
     drop_start_frame: int | None,

{kinemotion-0.24.0.dist-info → kinemotion-0.25.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.24.0
+Version: 0.25.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
@@ -79,17 +79,42 @@ Description-Content-Type: text/markdown
 - **Metrics**: Jump height, flight time, countermovement depth, eccentric/concentric durations
 - **Validated accuracy**: 50.6cm jump (±1 frame precision)
 
-## Validation Status
+## ⚠️ Validation Status
 
-⚠️ **IMPORTANT**: This tool's accuracy has **not been validated** against gold standard measurements (force plates, 3D motion capture). All accuracy claims and improvement estimates are theoretical and based on algorithmic considerations, not empirical testing.
+**Current Status:** Pre-validation (not validated against force plates or motion capture systems)
 
-The tool provides consistent measurements and may be useful for:
+### What This Tool IS Suitable For
 
-- Tracking relative changes in an individual athlete over time
-- Comparing similar jumps under controlled conditions
-- Exploratory analysis and research
+✅ **Training monitoring** - Track relative changes within the same athlete over time
+✅ **Educational purposes** - Learn about jump biomechanics and video analysis
+✅ **Exploratory analysis** - Initial investigation before formal testing
+✅ **Proof-of-concept research** - Demonstrate feasibility of video-based methods
 
-For clinical, research, or performance assessment requiring validated accuracy, this tool should be compared against validated measurement systems before use.
+### What This Tool IS NOT Suitable For
+
+❌ **Research publications** - As a validated measurement instrument
+❌ **Clinical decision-making** - Injury assessment, return-to-play decisions
+❌ **Talent identification** - Absolute performance comparisons between athletes
+❌ **Legal/insurance assessments** - Any context requiring validated measurements
+❌ **High-stakes testing** - Draft combines, professional athlete evaluation
+
+### Known Limitations
+
+- **No force plate validation** - Accuracy claims are theoretical, not empirical
+- **MediaPipe constraints** - Accuracy affected by lighting, clothing, occlusion, camera quality
+- **Lower sampling rate** - Typical video (30-60fps) vs validated apps (120-240Hz)
+- **Indirect measurement** - Landmarks → CoM estimation introduces potential error
+- **No correction factors** - Unlike validated tools (e.g., MyJump), no systematic bias corrections applied
+
+### Recommended Use
+
+If you need validated measurements for research or clinical use, consider:
+
+- **Commercial validated apps**: MyJump 2, MyJumpLab (smartphone-based, force plate validated)
+- **Laboratory equipment**: Force plates, optical motion capture systems
+- **Validation testing**: Compare kinemotion against validated equipment in your specific use case
+
+For detailed validation status and roadmap, see [`docs/validation-status.md`](docs/validation-status.md).
 
 ## Setup
 
@@ -242,6 +267,55 @@ kinemotion cmj-analyze videos/*.mp4 --batch --workers 4 \
   --csv-summary summary.csv
 ```
 
+### Quality Indicators & Confidence Scores
+
+All analysis outputs include automatic quality assessment to help you know when to trust results:
+
+```json
+{
+  "jump_height_m": 0.352,
+  "flight_time_s": 0.534,
+  "confidence": "high",
+  "quality_score": 87.3,
+  "quality_indicators": {
+    "avg_visibility": 0.89,
+    "min_visibility": 0.82,
+    "tracking_stable": true,
+    "phase_detection_clear": true,
+    "outliers_detected": 2,
+    "outlier_percentage": 1.5,
+    "position_variance": 0.0008,
+    "fps": 60.0
+  },
+  "warnings": []
+}
+```
+
+**Confidence Levels:**
+
+- **High** (score ≥75): Trust these results, good tracking quality
+- **Medium** (score 50-74): Use with caution, check quality indicators
+- **Low** (score \<50): Results may be unreliable, review warnings
+
+**Common Warnings:**
+
+- Poor lighting or occlusion detected
+- Unstable landmark tracking (jitter)
+- High outlier rate (tracking glitches)
+- Low frame rate (\<30fps)
+- Unclear phase transitions
+
+**Filtering by Quality:**
+
+```python
+# Only use high-confidence results
+metrics = process_cmj_video("video.mp4")
+if metrics.quality_assessment.confidence == "high":
+    print(f"Reliable jump height: {metrics.jump_height:.3f}m")
+else:
+    print(f"Low quality - warnings: {metrics.quality_assessment.warnings}")
+```
+
 ## Python API
 
 Use kinemotion as a library for automated pipelines and custom analysis.

{kinemotion-0.24.0.dist-info → kinemotion-0.25.0.dist-info}/RECORD

@@ -1,28 +1,30 @@
 kinemotion/__init__.py,sha256=vAEIg-oDX1ZkQMnWgXd__tekaA5KUcEvdJSAGWS8VUY,722
-kinemotion/api.py,sha256=T9oqDxelyrVPhWifxUV8BVm8lu9sTREBLkEbT9fr678,31360
+kinemotion/api.py,sha256=3oLJEjtHweG85t_BG1nCWnZ-8yl3tGW_6ZoBAILMfJw,38006
 kinemotion/cli.py,sha256=cqYV_7URH0JUDy1VQ_EDLv63FmNO4Ns20m6s1XAjiP4,464
 kinemotion/cmj/__init__.py,sha256=Ynv0-Oco4I3Y1Ubj25m3h9h2XFqeNwpAewXmAYOmwfU,127
 kinemotion/cmj/analysis.py,sha256=4HYGn4VDIB6oExAees-VcPfpNgWOltpgwjyNTU7YAb4,18263
-kinemotion/cmj/cli.py,sha256=bmDvNvL7cu65-R8YkRIZYKD0nuTA0IJnWLcLlH_kFm0,16843
+kinemotion/cmj/cli.py,sha256=12FEfWrseG4kCUbgHHdBPkWp6zzVQ0VAzfgNJotArmM,10792
 kinemotion/cmj/debug_overlay.py,sha256=D-y2FQKI01KY0WXFKTKg6p9Qj3AkXCE7xjau3Ais080,15886
 kinemotion/cmj/joint_angles.py,sha256=8ucpDGPvbt4iX3tx9eVxJEUv0laTm2Y58_--VzJCogE,9113
-kinemotion/cmj/kinematics.py,sha256=bCtAQY2DIX2JMMou1Z8_Wil3a0sJhpw19pl1CsPKnBg,8202
-kinemotion/core/__init__.py,sha256=3yzDhb5PekDNjydqrs8aWGneUGJBt-lB0SoB_Y2FXqU,1010
+kinemotion/cmj/kinematics.py,sha256=4-YDbCq9e7JlyGl_R3W1tvo8iAkXhjNla9J5yevUSRk,9165
+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/debug_overlay_utils.py,sha256=TyUb5okv5qw8oeaX3jsUO_kpwf1NnaHEAOTm-8LwTno,4587
 kinemotion/core/filtering.py,sha256=f-m-aA59e4WqE6u-9MA51wssu7rI-Y_7n1cG8IWdeRQ,11241
+kinemotion/core/metadata.py,sha256=PyGHL6sx7Hj21lyorg2VsWP9BGTj_y_-wWU6eKCEfJo,6817
 kinemotion/core/pose.py,sha256=ztemdZ_ysVVK3gbXabm8qS_dr1VfJX9KZjmcO-Z-iNE,8532
+kinemotion/core/quality.py,sha256=OC9nuf5IrQ9xURf3eA50VoNWOqkGwbjJpS90q2FDQzA,13082
 kinemotion/core/smoothing.py,sha256=x4o3BnG6k8OaV3emgpoJDF84CE9k5RYR7BeSYH_-8Es,14092
 kinemotion/core/video_io.py,sha256=0bJTheYidEqxGP5Y2dSO2x6sbOrnBDBu2TEiV8gT23A,7285
 kinemotion/dropjump/__init__.py,sha256=yc1XiZ9vfo5h_n7PKVSiX2TTgaIfGL7Y7SkQtiDZj_E,838
 kinemotion/dropjump/analysis.py,sha256=1AsIsgWg5wuwJo7poFK7aMCFr93yHVms-fEvaOGQQWs,27448
-kinemotion/dropjump/cli.py,sha256=J2F8ij-UcybY7YjK_bncQZiHNzrgS3Y7uTBkNo7y_L4,21328
+kinemotion/dropjump/cli.py,sha256=ZyroaYPwz8TgfL39Wcaj6m68Awl6lYXC75ttaflU-c0,16236
 kinemotion/dropjump/debug_overlay.py,sha256=LkPw6ucb7beoYWS4L-Lvjs1KLCm5wAWDAfiznUeV2IQ,5668
-kinemotion/dropjump/kinematics.py,sha256=VZWdytkw58Vk9dsNe8U15sFB84kfZKLo4argvt0CTPM,16361
+kinemotion/dropjump/kinematics.py,sha256=PaVakc8eiYR6ZErp2jO3A8Ey-rNIso0rGLft6-yOEzs,17510
 kinemotion/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kinemotion-0.24.0.dist-info/METADATA,sha256=q-Zj983PFHne1aGTqC7JU90XxUC6g0c_SFT1p1HPGXQ,20762
-kinemotion-0.24.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-kinemotion-0.24.0.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
-kinemotion-0.24.0.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
-kinemotion-0.24.0.dist-info/RECORD,,
+kinemotion-0.25.0.dist-info/METADATA,sha256=lJ39uLFmaTzqvZXJNw8eWBwwvWIeM2VQDd1D2cDcBUw,23244
+kinemotion-0.25.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+kinemotion-0.25.0.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
+kinemotion-0.25.0.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
+kinemotion-0.25.0.dist-info/RECORD,,