kinemotion 0.47.2__tar.gz → 0.47.3__tar.gz

{kinemotion-0.47.2 → kinemotion-0.47.3}/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## v0.47.3 (2025-12-12)
+
+### Bug Fixes
+
+- **api**: Remove unused timer parameter from _assess_dropjump_quality
+  ([`31ac8ef`](https://github.com/feniix/kinemotion/commit/31ac8efc8b474383f9de72eccc50ea02d408eb86))
+
+### Refactoring
+
+- **api**: Split large api.py into modular architecture
+  ([`6eb3f06`](https://github.com/feniix/kinemotion/commit/6eb3f06ab52534e7f97ad85d6e9a361b657cabb8))
+
+
 ## v0.47.2 (2025-12-12)
 
 ### Bug Fixes

{kinemotion-0.47.2 → kinemotion-0.47.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.47.2
+Version: 0.47.3
 Summary: Video-based kinematic analysis for athletic performance
 Project-URL: Homepage, https://github.com/feniix/kinemotion
 Project-URL: Repository, https://github.com/feniix/kinemotion

{kinemotion-0.47.2 → kinemotion-0.47.3}/backend/pyproject.toml

@@ -30,12 +30,6 @@ dependencies = [
     "supabase>=2.10.0",
     "pyjwt>=2.8.0",
     "httpx>=0.27.0",
-    "opentelemetry-api>=1.20.0",
-    "opentelemetry-sdk>=1.20.0",
-    "opentelemetry-exporter-otlp>=1.20.0",
-    "opentelemetry-exporter-gcp-trace>=1.6.0",
-    "opentelemetry-instrumentation-fastapi>=0.40b0",
-    "opentelemetry-instrumentation-logging>=0.40b0",
     # Local development: use editable install via `uv sync`
     # Production deployment: use released package from PyPI
     "kinemotion>=0.37.0",

{kinemotion-0.47.2 → kinemotion-0.47.3}/backend/src/kinemotion_backend/app.py

@@ -27,8 +27,6 @@ from fastapi.responses import JSONResponse
 from kinemotion.api import process_cmj_video, process_dropjump_video
 from kinemotion.core.pose import PoseTracker
 from kinemotion.core.timing import (
-    CompositeTimer,
-    OpenTelemetryTimer,
     PerformanceTimer,
     Timer,
 )
@@ -37,7 +35,6 @@ from slowapi.util import get_remote_address
 
 from kinemotion_backend.logging_config import get_logger, setup_logging
 from kinemotion_backend.middleware import RequestLoggingMiddleware
-from kinemotion_backend.telemetry import setup_telemetry
 
 # Initialize structured logging
 setup_logging(
@@ -223,9 +220,6 @@ global_pose_trackers: dict[str, PoseTracker] = {}
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     """Manage application lifecycle and global resources."""
-    # Initialize telemetry
-    app.state.telemetry_enabled = setup_telemetry(app)
-
     logger.info("initializing_pose_trackers")
     try:
         # Initialize trackers for each quality preset
@@ -614,12 +608,8 @@ async def analyze_video(
         # Process video with real kinemotion analysis
         analysis_start = time.time()
 
-        # Initialize timer (with optional telemetry)
-        base_timer = PerformanceTimer()
-        if getattr(request.app.state, "telemetry_enabled", False):
-            timer = CompositeTimer([base_timer, OpenTelemetryTimer()])
-        else:
-            timer = base_timer
+        # Initialize timer
+        timer = PerformanceTimer()
 
         # Select appropriate pre-initialized tracker from pool
         # Default to balanced if quality not found or trackers not initialized
@@ -866,12 +856,8 @@ async def analyze_local_video(
             )
 
         # Process video
-        # Initialize timer (with optional telemetry)
-        base_timer = PerformanceTimer()
-        if getattr(request.app.state, "telemetry_enabled", False):
-            timer = CompositeTimer([base_timer, OpenTelemetryTimer()])
-        else:
-            timer = base_timer
+        # Initialize timer
+        timer = PerformanceTimer()
 
         # Select appropriate pre-initialized tracker from pool
         tracker_key = quality.lower()

{kinemotion-0.47.2 → kinemotion-0.47.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kinemotion"
-version = "0.47.2"
+version = "0.47.3"
 description = "Video-based kinematic analysis for athletic performance"
 readme = "README.md"
 requires-python = ">=3.10,<3.13"

kinemotion-0.47.3/src/kinemotion/api.py

@@ -0,0 +1,38 @@
+"""Public API for programmatic use of kinemotion analysis.
+
+This module provides a unified interface for both drop jump and CMJ video analysis.
+The actual implementations have been moved to their respective submodules:
+- Drop jump: kinemotion.dropjump.api
+- CMJ: kinemotion.cmj.api
+"""
+
+# CMJ API
+from .cmj.api import (
+    CMJVideoConfig,
+    CMJVideoResult,
+    process_cmj_video,
+    process_cmj_videos_bulk,
+)
+from .cmj.kinematics import CMJMetrics
+
+# Drop jump API
+from .dropjump.api import (
+    DropJumpVideoConfig,
+    DropJumpVideoResult,
+    process_dropjump_video,
+    process_dropjump_videos_bulk,
+)
+
+__all__ = [
+    # Drop jump
+    "DropJumpVideoConfig",
+    "DropJumpVideoResult",
+    "process_dropjump_video",
+    "process_dropjump_videos_bulk",
+    # CMJ
+    "CMJMetrics",
+    "CMJVideoConfig",
+    "CMJVideoResult",
+    "process_cmj_video",
+    "process_cmj_videos_bulk",
+]

{kinemotion-0.47.2 → kinemotion-0.47.3}/src/kinemotion/cmj/__init__.py

@@ -1,5 +1,5 @@
 """Counter Movement Jump (CMJ) analysis module."""
 
-from kinemotion.cmj.kinematics import CMJMetrics
+from .kinematics import CMJMetrics
 
 __all__ = ["CMJMetrics"]

kinemotion-0.47.3/src/kinemotion/cmj/api.py

@@ -0,0 +1,433 @@
+"""Public API for CMJ (Counter Movement Jump) video analysis."""
+
+import json
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    pass
+
+from ..core.auto_tuning import (
+    analyze_video_sample,
+    auto_tune_parameters,
+)
+from ..core.filtering import reject_outliers
+from ..core.metadata import (
+    AlgorithmConfig,
+    DetectionConfig,
+    ProcessingInfo,
+    ResultMetadata,
+    SmoothingConfig,
+    VideoInfo,
+    create_timestamp,
+    get_kinemotion_version,
+)
+from ..core.pipeline_utils import (
+    apply_expert_overrides,
+    apply_smoothing,
+    convert_timer_to_stage_names,
+    determine_confidence_levels,
+    extract_vertical_positions,
+    parse_quality_preset,
+    print_verbose_parameters,
+    process_all_frames,
+    process_videos_bulk_generic,
+)
+from ..core.pose import PoseTracker
+from ..core.quality import assess_jump_quality
+from ..core.timing import PerformanceTimer, Timer
+from ..core.video_io import VideoProcessor
+from .analysis import compute_signed_velocity, detect_cmj_phases
+from .debug_overlay import CMJDebugOverlayRenderer
+from .kinematics import CMJMetrics, calculate_cmj_metrics
+from .metrics_validator import CMJMetricsValidator
+
+
+@dataclass
+class CMJVideoConfig:
+    """Configuration for processing a single CMJ video."""
+
+    video_path: str
+    quality: str = "balanced"
+    output_video: str | None = None
+    json_output: str | None = None
+    smoothing_window: int | None = None
+    velocity_threshold: float | None = None
+    min_contact_frames: int | None = None
+    visibility_threshold: float | None = None
+    detection_confidence: float | None = None
+    tracking_confidence: float | None = None
+
+
+@dataclass
+class CMJVideoResult:
+    """Result of processing a single CMJ video."""
+
+    video_path: str
+    success: bool
+    metrics: CMJMetrics | None = None
+    error: str | None = None
+    processing_time: float = 0.0
+
+
+def process_cmj_video(
+    video_path: str,
+    quality: str = "balanced",
+    output_video: str | None = None,
+    json_output: str | None = None,
+    smoothing_window: int | None = None,
+    velocity_threshold: float | None = None,
+    min_contact_frames: int | None = None,
+    visibility_threshold: float | None = None,
+    detection_confidence: float | None = None,
+    tracking_confidence: float | None = None,
+    verbose: bool = False,
+    timer: Timer | None = None,
+    pose_tracker: "PoseTracker | None" = None,
+) -> CMJMetrics:
+    """
+    Process a single CMJ video and return metrics.
+
+    CMJ (Counter Movement Jump) is performed at floor level without a drop box.
+    Athletes start standing, perform a countermovement (eccentric phase), then
+    jump upward (concentric phase).
+
+    Args:
+        video_path: Path to the input video file
+        quality: Analysis quality preset ("fast", "balanced", or "accurate")
+        output_video: Optional path for debug video output
+        json_output: Optional path for JSON metrics output
+        smoothing_window: Optional override for smoothing window
+        velocity_threshold: Optional override for velocity threshold
+        min_contact_frames: Optional override for minimum contact frames
+        visibility_threshold: Optional override for visibility threshold
+        detection_confidence: Optional override for pose detection confidence
+        tracking_confidence: Optional override for pose tracking confidence
+        verbose: Print processing details
+        timer: Optional Timer for measuring operations
+        pose_tracker: Optional pre-initialized PoseTracker instance (reused if provided)
+
+    Returns:
+        CMJMetrics object containing analysis results
+
+    Raises:
+        ValueError: If video cannot be processed or parameters are invalid
+        FileNotFoundError: If video file does not exist
+    """
+    if not Path(video_path).exists():
+        raise FileNotFoundError(f"Video file not found: {video_path}")
+
+    start_time = time.time()
+    if timer is None:
+        timer = PerformanceTimer()
+
+    quality_preset = parse_quality_preset(quality)
+
+    with timer.measure("video_initialization"):
+        with VideoProcessor(video_path, timer=timer) as video:
+            if verbose:
+                print(
+                    f"Video: {video.width}x{video.height} @ {video.fps:.2f} fps, "
+                    f"{video.frame_count} frames"
+                )
+
+            det_conf, track_conf = determine_confidence_levels(
+                quality_preset, detection_confidence, tracking_confidence
+            )
+
+            if verbose:
+                print("Processing all frames with MediaPipe pose tracking...")
+
+            tracker = pose_tracker
+            should_close_tracker = False
+
+            if tracker is None:
+                tracker = PoseTracker(
+                    min_detection_confidence=det_conf,
+                    min_tracking_confidence=track_conf,
+                    timer=timer,
+                )
+                should_close_tracker = True
+
+            frames, landmarks_sequence, frame_indices = process_all_frames(
+                video, tracker, verbose, timer, close_tracker=should_close_tracker
+            )
+
+            with timer.measure("parameter_auto_tuning"):
+                characteristics = analyze_video_sample(
+                    landmarks_sequence, video.fps, video.frame_count
+                )
+                params = auto_tune_parameters(characteristics, quality_preset)
+
+                params = apply_expert_overrides(
+                    params,
+                    smoothing_window,
+                    velocity_threshold,
+                    min_contact_frames,
+                    visibility_threshold,
+                )
+
+                if verbose:
+                    print_verbose_parameters(
+                        video, characteristics, quality_preset, params
+                    )
+
+            smoothed_landmarks = apply_smoothing(
+                landmarks_sequence, params, verbose, timer
+            )
+
+            if verbose:
+                print("Extracting vertical positions (Hip and Foot)...")
+            with timer.measure("vertical_position_extraction"):
+                vertical_positions, visibilities = extract_vertical_positions(
+                    smoothed_landmarks, target="hip"
+                )
+
+                foot_positions, _ = extract_vertical_positions(
+                    smoothed_landmarks, target="foot"
+                )
+
+            tracking_method = "hip_hybrid"
+
+            if verbose:
+                print("Detecting CMJ phases...")
+            with timer.measure("phase_detection"):
+                phases = detect_cmj_phases(
+                    vertical_positions,
+                    video.fps,
+                    window_length=params.smoothing_window,
+                    polyorder=params.polyorder,
+                    landing_positions=foot_positions,
+                    timer=timer,
+                )
+
+            if phases is None:
+                raise ValueError("Could not detect CMJ phases in video")
+
+            standing_end, lowest_point, takeoff_frame, landing_frame = phases
+
+            if verbose:
+                print("Calculating metrics...")
+            with timer.measure("metrics_calculation"):
+                velocities = compute_signed_velocity(
+                    vertical_positions,
+                    window_length=params.smoothing_window,
+                    polyorder=params.polyorder,
+                )
+
+                metrics = calculate_cmj_metrics(
+                    vertical_positions,
+                    velocities,
+                    standing_end,
+                    lowest_point,
+                    takeoff_frame,
+                    landing_frame,
+                    video.fps,
+                    tracking_method=tracking_method,
+                )
+
+            if verbose:
+                print("Assessing tracking quality...")
+            with timer.measure("quality_assessment"):
+                _, outlier_mask = reject_outliers(
+                    vertical_positions,
+                    use_ransac=True,
+                    use_median=True,
+                    interpolate=False,
+                )
+
+                phases_detected = True
+                phase_count = 4
+
+                quality_result = assess_jump_quality(
+                    visibilities=visibilities,
+                    positions=vertical_positions,
+                    outlier_mask=outlier_mask,
+                    fps=video.fps,
+                    phases_detected=phases_detected,
+                    phase_count=phase_count,
+                )
+
+            algorithm_config = AlgorithmConfig(
+                detection_method="backward_search",
+                tracking_method="mediapipe_pose",
+                model_complexity=1,
+                smoothing=SmoothingConfig(
+                    window_size=params.smoothing_window,
+                    polynomial_order=params.polyorder,
+                    use_bilateral_filter=params.bilateral_filter,
+                    use_outlier_rejection=params.outlier_rejection,
+                ),
+                detection=DetectionConfig(
+                    velocity_threshold=params.velocity_threshold,
+                    min_contact_frames=params.min_contact_frames,
+                    visibility_threshold=params.visibility_threshold,
+                    use_curvature_refinement=params.use_curvature,
+                ),
+                drop_detection=None,
+            )
+
+            video_info = VideoInfo(
+                source_path=video_path,
+                fps=video.fps,
+                width=video.width,
+                height=video.height,
+                duration_s=video.frame_count / video.fps,
+                frame_count=video.frame_count,
+                codec=video.codec,
+            )
+
+            if verbose and quality_result.warnings:
+                print("\n⚠️  Quality Warnings:")
+                for warning in quality_result.warnings:
+                    print(f"  - {warning}")
+                print()
+
+            if output_video:
+                if verbose:
+                    print(f"Generating debug video: {output_video}")
+
+                debug_h, debug_w = frames[0].shape[:2]
+                step = max(1, int(video.fps / 30.0))
+                debug_fps = video.fps / step
+
+                with timer.measure("debug_video_generation"):
+                    with CMJDebugOverlayRenderer(
+                        output_video,
+                        debug_w,
+                        debug_h,
+                        debug_w,
+                        debug_h,
+                        debug_fps,
+                        timer=timer,
+                    ) as renderer:
+                        for frame, idx in zip(frames, frame_indices, strict=True):
+                            annotated = renderer.render_frame(
+                                frame, smoothed_landmarks[idx], idx, metrics
+                            )
+                            renderer.write_frame(annotated)
+
+                if verbose:
+                    print(f"Debug video saved: {output_video}")
+
+            with timer.measure("metrics_validation"):
+                validator = CMJMetricsValidator()
+                validation_result = validator.validate(metrics.to_dict())  # type: ignore[arg-type]
+                metrics.validation_result = validation_result
+
+            processing_time = time.time() - start_time
+            stage_times = convert_timer_to_stage_names(timer.get_metrics())
+
+            processing_info = ProcessingInfo(
+                version=get_kinemotion_version(),
+                timestamp=create_timestamp(),
+                quality_preset=quality_preset.value,
+                processing_time_s=processing_time,
+                timing_breakdown=stage_times,
+            )
+
+            result_metadata = ResultMetadata(
+                quality=quality_result,
+                video=video_info,
+                processing=processing_info,
+                algorithm=algorithm_config,
+            )
+
+            metrics.result_metadata = result_metadata
+
+            if json_output:
+                with timer.measure("json_serialization"):
+                    output_path = Path(json_output)
+                    metrics_dict = metrics.to_dict()
+                    json_str = json.dumps(metrics_dict, indent=2)
+                    output_path.write_text(json_str)
+
+                if verbose:
+                    print(f"Metrics written to: {json_output}")
+
+            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}")
+
+            if verbose:
+                total_time = time.time() - start_time
+                stage_times = convert_timer_to_stage_names(timer.get_metrics())
+
+                print("\n=== Timing Summary ===")
+                for stage, duration in stage_times.items():
+                    percentage = (duration / total_time) * 100
+                    dur_ms = duration * 1000
+                    print(f"{stage:. <40} {dur_ms:>6.0f}ms ({percentage:>5.1f}%)")
+                total_ms = total_time * 1000
+                print(f"{('Total'):.>40} {total_ms:>6.0f}ms (100.0%)")
+                print()
+
+                print(f"\nJump height: {metrics.jump_height:.3f}m")
+                print(f"Flight time: {metrics.flight_time * 1000:.1f}ms")
+                print(f"Countermovement depth: {metrics.countermovement_depth:.3f}m")
+
+            return metrics
+
+
+def process_cmj_videos_bulk(
+    configs: list[CMJVideoConfig],
+    max_workers: int = 4,
+    progress_callback: Callable[[CMJVideoResult], None] | None = None,
+) -> list[CMJVideoResult]:
+    """
+    Process multiple CMJ videos in parallel.
+    """
+
+    def error_factory(video_path: str, error_msg: str) -> CMJVideoResult:
+        return CMJVideoResult(video_path=video_path, success=False, error=error_msg)
+
+    return process_videos_bulk_generic(
+        configs,
+        _process_cmj_video_wrapper,
+        error_factory,
+        max_workers,
+        progress_callback,
+    )
+
+
+def _process_cmj_video_wrapper(config: CMJVideoConfig) -> CMJVideoResult:
+    """Wrapper function for parallel CMJ processing."""
+    start_time = time.time()
+
+    try:
+        metrics = process_cmj_video(
+            video_path=config.video_path,
+            quality=config.quality,
+            output_video=config.output_video,
+            json_output=config.json_output,
+            smoothing_window=config.smoothing_window,
+            velocity_threshold=config.velocity_threshold,
+            min_contact_frames=config.min_contact_frames,
+            visibility_threshold=config.visibility_threshold,
+            detection_confidence=config.detection_confidence,
+            tracking_confidence=config.tracking_confidence,
+            verbose=False,
+        )
+
+        processing_time = time.time() - start_time
+
+        return CMJVideoResult(
+            video_path=config.video_path,
+            success=True,
+            metrics=metrics,
+            processing_time=processing_time,
+        )
+
+    except Exception as e:
+        processing_time = time.time() - start_time
+
+        return CMJVideoResult(
+            video_path=config.video_path,
+            success=False,
+            error=str(e),
+            processing_time=processing_time,
+        )

{kinemotion-0.47.2 → kinemotion-0.47.3}/src/kinemotion/cmj/cli.py

@@ -6,13 +6,14 @@ from dataclasses import dataclass
 
 import click
 
-from ..api import CMJMetrics, process_cmj_video
 from ..core.auto_tuning import QualityPreset
 from ..core.cli_utils import (
     collect_video_files,
     common_output_options,
     generate_batch_output_paths,
 )
+from .api import process_cmj_video
+from .kinematics import CMJMetrics
 
 
 @dataclass

{kinemotion-0.47.2 → kinemotion-0.47.3}/src/kinemotion/core/__init__.py

@@ -24,9 +24,7 @@ from .smoothing import (
 )
 from .timing import (
     NULL_TIMER,
-    CompositeTimer,
     NullTimer,
-    OpenTelemetryTimer,
     PerformanceTimer,
     Timer,
 )
@@ -59,8 +57,6 @@ __all__ = [
     "Timer",
     "NullTimer",
     "NULL_TIMER",
-    "CompositeTimer",
-    "OpenTelemetryTimer",
     # Video I/O
     "VideoProcessor",
 ]