kinemotion 0.26.1__py3-none-any.whl → 0.28.0__py3-none-any.whl

kinemotion/api.py

@@ -532,7 +532,7 @@ def process_dropjump_video(
             height=video.height,
             duration_s=video.frame_count / video.fps,
             frame_count=video.frame_count,
-            codec=None,
+            codec=video.codec,
         )
 
         processing_info = ProcessingInfo(
@@ -973,7 +973,7 @@ def process_cmj_video(
             height=video.height,
             duration_s=video.frame_count / video.fps,
             frame_count=video.frame_count,
-            codec=None,  # TODO: Extract from video metadata if available
+            codec=video.codec,
         )
 
         processing_info = ProcessingInfo(

kinemotion/cmj/kinematics.py

@@ -6,6 +6,8 @@ from typing import TYPE_CHECKING, TypedDict
 import numpy as np
 from numpy.typing import NDArray
 
+from ..core.formatting import format_float_metric
+
 if TYPE_CHECKING:
     from ..core.metadata import ResultMetadata
     from ..core.quality import QualityAssessment
@@ -15,14 +17,14 @@ class CMJDataDict(TypedDict, total=False):
     """Type-safe dictionary for CMJ measurement data."""
 
     jump_height_m: float
-    flight_time_s: float
+    flight_time_ms: float
     countermovement_depth_m: float
-    eccentric_duration_s: float
-    concentric_duration_s: float
-    total_movement_time_s: float
+    eccentric_duration_ms: float
+    concentric_duration_ms: float
+    total_movement_time_ms: float
     peak_eccentric_velocity_m_s: float
     peak_concentric_velocity_m_s: float
-    transition_time_s: float | None
+    transition_time_ms: float | None
     standing_start_frame: float | None
     lowest_point_frame: float
     takeoff_frame: float
@@ -43,14 +45,14 @@ class CMJMetrics:
 
     Attributes:
         jump_height: Maximum jump height in meters
-        flight_time: Time spent in the air in seconds
+        flight_time: Time spent in the air in milliseconds
         countermovement_depth: Vertical distance traveled during eccentric phase in meters
-        eccentric_duration: Time from countermovement start to lowest point in seconds
-        concentric_duration: Time from lowest point to takeoff in seconds
-        total_movement_time: Total time from countermovement start to takeoff in seconds
+        eccentric_duration: Time from countermovement start to lowest point in milliseconds
+        concentric_duration: Time from lowest point to takeoff in milliseconds
+        total_movement_time: Total time from countermovement start to takeoff in milliseconds
         peak_eccentric_velocity: Maximum downward velocity during countermovement in m/s
         peak_concentric_velocity: Maximum upward velocity during propulsion in m/s
-        transition_time: Duration at lowest point (amortization phase) in seconds
+        transition_time: Duration at lowest point (amortization phase) in milliseconds
         standing_start_frame: Frame where standing phase ends (countermovement begins)
         lowest_point_frame: Frame at lowest point of countermovement
         takeoff_frame: Frame where athlete leaves ground
@@ -85,19 +87,27 @@ class CMJMetrics:
             Dictionary with nested data and metadata structure.
         """
         data: CMJDataDict = {
-            "jump_height_m": float(self.jump_height),
-            "flight_time_s": float(self.flight_time),
-            "countermovement_depth_m": float(self.countermovement_depth),
-            "eccentric_duration_s": float(self.eccentric_duration),
-            "concentric_duration_s": float(self.concentric_duration),
-            "total_movement_time_s": float(self.total_movement_time),
-            "peak_eccentric_velocity_m_s": float(self.peak_eccentric_velocity),
-            "peak_concentric_velocity_m_s": float(self.peak_concentric_velocity),
-            "transition_time_s": (
-                float(self.transition_time)
-                if self.transition_time is not None
-                else None
-            ),
+            "jump_height_m": format_float_metric(self.jump_height, 1, 3),  # type: ignore[typeddict-item]
+            "flight_time_ms": format_float_metric(self.flight_time, 1000, 2),  # type: ignore[typeddict-item]
+            "countermovement_depth_m": format_float_metric(
+                self.countermovement_depth, 1, 3
+            ),  # type: ignore[typeddict-item]
+            "eccentric_duration_ms": format_float_metric(
+                self.eccentric_duration, 1000, 2
+            ),  # type: ignore[typeddict-item]
+            "concentric_duration_ms": format_float_metric(
+                self.concentric_duration, 1000, 2
+            ),  # type: ignore[typeddict-item]
+            "total_movement_time_ms": format_float_metric(
+                self.total_movement_time, 1000, 2
+            ),  # type: ignore[typeddict-item]
+            "peak_eccentric_velocity_m_s": format_float_metric(
+                self.peak_eccentric_velocity, 1, 4
+            ),  # type: ignore[typeddict-item]
+            "peak_concentric_velocity_m_s": format_float_metric(
+                self.peak_concentric_velocity, 1, 4
+            ),  # type: ignore[typeddict-item]
+            "transition_time_ms": format_float_metric(self.transition_time, 1000, 2),
             "standing_start_frame": (
                 float(self.standing_start_frame)
                 if self.standing_start_frame is not None

kinemotion/core/formatting.py

@@ -0,0 +1,75 @@
+"""Formatting utilities for consistent numeric output across jump analysis types.
+
+This module provides shared helpers for formatting numeric values with appropriate
+precision based on measurement type and capabilities of video-based analysis.
+"""
+
+# Standard precision values for different measurement types
+# These values are chosen based on:
+# - Video analysis capabilities (30-240 fps)
+# - Typical measurement uncertainty in video-based biomechanics
+# - Balance between accuracy and readability
+
+PRECISION_TIME_MS = 2  # Time in milliseconds: ±0.01ms (e.g., 534.12)
+PRECISION_DISTANCE_M = 3  # Distance in meters: ±1mm (e.g., 0.352)
+PRECISION_VELOCITY_M_S = 4  # Velocity in m/s: ±0.0001 m/s (e.g., 2.6340)
+PRECISION_FRAME = 3  # Sub-frame interpolation precision (e.g., 154.342)
+PRECISION_NORMALIZED = 4  # Normalized values 0-1 ratios (e.g., 0.0582)
+
+
+def format_float_metric(
+    value: float | None,
+    multiplier: float = 1.0,
+    decimals: int = 2,
+) -> float | None:
+    """Format a float metric value with optional scaling and rounding.
+
+    This helper ensures consistent precision across all jump analysis outputs,
+    preventing false precision in measurements while maintaining appropriate
+    accuracy for the measurement type.
+
+    Args:
+        value: The value to format, or None
+        multiplier: Factor to multiply value by (e.g., 1000 for seconds→milliseconds)
+        decimals: Number of decimal places to round to
+
+    Returns:
+        Formatted value rounded to specified decimals, or None if input is None
+
+    Examples:
+        >>> format_float_metric(0.534123, 1000, 2)  # seconds to ms
+        534.12
+        >>> format_float_metric(0.3521234, 1, 3)  # meters
+        0.352
+        >>> format_float_metric(None, 1, 2)
+        None
+        >>> format_float_metric(-1.23456, 1, 4)  # negative values preserved
+        -1.2346
+    """
+    if value is None:
+        return None
+    return round(value * multiplier, decimals)
+
+
+def format_int_metric(value: float | int | None) -> int | None:
+    """Format a value as an integer.
+
+    Used for frame numbers and other integer-valued metrics.
+
+    Args:
+        value: The value to format, or None
+
+    Returns:
+        Value converted to int, or None if input is None
+
+    Examples:
+        >>> format_int_metric(42.7)
+        42
+        >>> format_int_metric(None)
+        None
+        >>> format_int_metric(154)
+        154
+    """
+    if value is None:
+        return None
+    return int(value)

kinemotion/core/video_io.py

@@ -50,6 +50,9 @@ class VideoProcessor:
         # 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
+        self.codec: str | None = None  # Will be set by _extract_video_metadata()
+
         # Calculate display dimensions considering SAR (Sample Aspect Ratio)
         # Mobile videos often have non-square pixels encoded in SAR metadata
         # OpenCV doesn't directly expose SAR, but we need to handle display correctly
@@ -141,6 +144,9 @@ class VideoProcessor:
 
             stream = data["streams"][0]
 
+            # Extract codec name (e.g., "h264", "hevc", "vp9")
+            self.codec = stream.get("codec_name")
+
             # Extract and parse SAR (Sample Aspect Ratio)
             sar_str = stream.get("sample_aspect_ratio", "1:1")
             self._parse_sample_aspect_ratio(sar_str)

kinemotion/dropjump/kinematics.py

@@ -5,6 +5,7 @@ from typing import TYPE_CHECKING, TypedDict
 import numpy as np
 from numpy.typing import NDArray
 
+from ..core.formatting import format_float_metric, format_int_metric
 from ..core.smoothing import compute_acceleration_from_derivative
 from .analysis import (
     ContactState,
@@ -19,38 +20,6 @@ if TYPE_CHECKING:
     from ..core.quality import QualityAssessment
 
 
-def _format_float_metric(
-    value: float | None, multiplier: float = 1, decimals: int = 2
-) -> float | None:
-    """Format a float metric value with optional scaling and rounding.
-
-    Args:
-        value: The value to format, or None
-        multiplier: Factor to multiply value by (default: 1)
-        decimals: Number of decimal places to round to (default: 2)
-
-    Returns:
-        Formatted value rounded to specified decimals, or None if input is None
-    """
-    if value is None:
-        return None
-    return round(value * multiplier, decimals)
-
-
-def _format_int_metric(value: float | int | None) -> int | None:
-    """Format a value as an integer.
-
-    Args:
-        value: The value to format, or None
-
-    Returns:
-        Value converted to int, or None if input is None
-    """
-    if value is None:
-        return None
-    return int(value)
-
-
 class DropJumpDataDict(TypedDict, total=False):
     """Type-safe dictionary for drop jump measurement data."""
 
@@ -108,32 +77,32 @@ class DropJumpMetrics:
             Dictionary containing formatted metric values.
         """
         return {
-            "ground_contact_time_ms": _format_float_metric(
+            "ground_contact_time_ms": format_float_metric(
                 self.ground_contact_time, 1000, 2
             ),
-            "flight_time_ms": _format_float_metric(self.flight_time, 1000, 2),
-            "jump_height_m": _format_float_metric(self.jump_height, 1, 3),
-            "jump_height_kinematic_m": _format_float_metric(
+            "flight_time_ms": format_float_metric(self.flight_time, 1000, 2),
+            "jump_height_m": format_float_metric(self.jump_height, 1, 3),
+            "jump_height_kinematic_m": format_float_metric(
                 self.jump_height_kinematic, 1, 3
             ),
-            "jump_height_trajectory_normalized": _format_float_metric(
+            "jump_height_trajectory_normalized": format_float_metric(
                 self.jump_height_trajectory, 1, 4
             ),
-            "contact_start_frame": _format_int_metric(self.contact_start_frame),
-            "contact_end_frame": _format_int_metric(self.contact_end_frame),
-            "flight_start_frame": _format_int_metric(self.flight_start_frame),
-            "flight_end_frame": _format_int_metric(self.flight_end_frame),
-            "peak_height_frame": _format_int_metric(self.peak_height_frame),
-            "contact_start_frame_precise": _format_float_metric(
+            "contact_start_frame": format_int_metric(self.contact_start_frame),
+            "contact_end_frame": format_int_metric(self.contact_end_frame),
+            "flight_start_frame": format_int_metric(self.flight_start_frame),
+            "flight_end_frame": format_int_metric(self.flight_end_frame),
+            "peak_height_frame": format_int_metric(self.peak_height_frame),
+            "contact_start_frame_precise": format_float_metric(
                 self.contact_start_frame_precise, 1, 3
             ),
-            "contact_end_frame_precise": _format_float_metric(
+            "contact_end_frame_precise": format_float_metric(
                 self.contact_end_frame_precise, 1, 3
             ),
-            "flight_start_frame_precise": _format_float_metric(
+            "flight_start_frame_precise": format_float_metric(
                 self.flight_start_frame_precise, 1, 3
             ),
-            "flight_end_frame_precise": _format_float_metric(
+            "flight_end_frame_precise": format_float_metric(
                 self.flight_end_frame_precise, 1, 3
             ),
         }

{kinemotion-0.26.1.dist-info → kinemotion-0.28.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.26.1
+Version: 0.28.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

{kinemotion-0.26.1.dist-info → kinemotion-0.28.0.dist-info}/RECORD

@@ -1,30 +1,31 @@
 kinemotion/__init__.py,sha256=vAEIg-oDX1ZkQMnWgXd__tekaA5KUcEvdJSAGWS8VUY,722
-kinemotion/api.py,sha256=ELkAk0xq2MaafVwSAahXIf1KP9am8rpxHibqcnId6pg,38213
+kinemotion/api.py,sha256=tbkjXsfe0N0Bmik6XRIOYM7Nom4QqeQJSpDx7IoiuSA,38177
 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=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=4-YDbCq9e7JlyGl_R3W1tvo8iAkXhjNla9J5yevUSRk,9165
+kinemotion/cmj/kinematics.py,sha256=-iBFg2AkQR4LaThCQzO09fx6qJed27ZfMDQJgE7Si4k,9772
 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/formatting.py,sha256=G_3eqgOtym9RFOZVEwCxye4A2cyrmgvtQ214vIshowU,2480
 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/core/video_io.py,sha256=SQBJSgAV8uOkAh96gNZRjd6XJG1G9dZzDc8kAZ_twy0,7538
 kinemotion/dropjump/__init__.py,sha256=yc1XiZ9vfo5h_n7PKVSiX2TTgaIfGL7Y7SkQtiDZj_E,838
 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=Ig9TqXr-OEUm19gqIvUjQkqrCuw1csYt1f4ZfwG8oGc,17464
+kinemotion/dropjump/kinematics.py,sha256=Yr3G7AQwtYy1dxyeOAYfqqgd4pzoZwWQAhZzxI5RbnE,16658
 kinemotion/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kinemotion-0.26.1.dist-info/METADATA,sha256=4Ads7Gis9jvPj3qOXQBwyGB6c3wJr8kkVWpX-kKwI1Q,23244
-kinemotion-0.26.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-kinemotion-0.26.1.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
-kinemotion-0.26.1.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
-kinemotion-0.26.1.dist-info/RECORD,,
+kinemotion-0.28.0.dist-info/METADATA,sha256=RIUN7r__qFVHSNzj2CglERzONmcmLiIYrDZLkpztZu8,23244
+kinemotion-0.28.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+kinemotion-0.28.0.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
+kinemotion-0.28.0.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
+kinemotion-0.28.0.dist-info/RECORD,,