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

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/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.27.0.dist-info → kinemotion-0.28.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.27.0
+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.27.0.dist-info → kinemotion-0.28.0.dist-info}/RECORD

@@ -6,12 +6,13 @@ kinemotion/cmj/analysis.py,sha256=4HYGn4VDIB6oExAees-VcPfpNgWOltpgwjyNTU7YAb4,18
 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
@@ -21,10 +22,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=Ig9TqXr-OEUm19gqIvUjQkqrCuw1csYt1f4ZfwG8oGc,17464
+kinemotion/dropjump/kinematics.py,sha256=Yr3G7AQwtYy1dxyeOAYfqqgd4pzoZwWQAhZzxI5RbnE,16658
 kinemotion/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kinemotion-0.27.0.dist-info/METADATA,sha256=YhRgdOUcZ_mIgOgj0wJBdTW_msbUPlyZaCx7ND0dVTI,23244
-kinemotion-0.27.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-kinemotion-0.27.0.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
-kinemotion-0.27.0.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
-kinemotion-0.27.0.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,,