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

kinemotion/api.py

@@ -244,6 +244,20 @@ def _apply_smoothing(
         )
 
 
+def _calculate_foot_visibility(frame_landmarks: dict) -> float:
+    """Calculate average visibility of foot landmarks.
+
+    Args:
+        frame_landmarks: Dictionary of landmarks for a frame
+
+    Returns:
+        Average visibility value (0-1)
+    """
+    foot_keys = ["left_ankle", "right_ankle", "left_heel", "right_heel"]
+    foot_vis = [frame_landmarks[key][2] for key in foot_keys if key in frame_landmarks]
+    return float(np.mean(foot_vis)) if foot_vis else 0.0
+
+
 def _extract_vertical_positions(
     smoothed_landmarks: list,
 ) -> tuple[np.ndarray, np.ndarray]:
@@ -262,13 +276,7 @@ def _extract_vertical_positions(
         if frame_landmarks:
             _, foot_y = compute_average_foot_position(frame_landmarks)
             position_list.append(foot_y)
-
-            # Average visibility of foot landmarks
-            foot_vis = []
-            for key in ["left_ankle", "right_ankle", "left_heel", "right_heel"]:
-                if key in frame_landmarks:
-                    foot_vis.append(frame_landmarks[key][2])
-            visibilities_list.append(float(np.mean(foot_vis)) if foot_vis else 0.0)
+            visibilities_list.append(_calculate_foot_visibility(frame_landmarks))
         else:
             position_list.append(position_list[-1] if position_list else 0.5)
             visibilities_list.append(0.0)

kinemotion/dropjump/analysis.py

@@ -235,6 +235,86 @@ def detect_drop_start(
     )
 
 
+def _filter_stationary_with_visibility(
+    is_stationary: np.ndarray,
+    visibilities: np.ndarray | None,
+    visibility_threshold: float,
+) -> np.ndarray:
+    """Apply visibility filter to stationary flags.
+
+    Args:
+        is_stationary: Boolean array indicating stationary frames
+        visibilities: Optional visibility scores for each frame
+        visibility_threshold: Minimum visibility to trust landmark
+
+    Returns:
+        Filtered is_stationary array
+    """
+    if visibilities is not None:
+        is_visible = visibilities > visibility_threshold
+        return is_stationary & is_visible
+    return is_stationary
+
+
+def _find_contact_frames(
+    is_stationary: np.ndarray,
+    min_contact_frames: int,
+) -> set[int]:
+    """Find frames with sustained contact using minimum duration filter.
+
+    Args:
+        is_stationary: Boolean array indicating stationary frames
+        min_contact_frames: Minimum consecutive frames to confirm contact
+
+    Returns:
+        Set of frame indices that meet minimum contact duration
+    """
+    contact_frames: set[int] = set()
+    current_run = []
+
+    for i, stationary in enumerate(is_stationary):
+        if stationary:
+            current_run.append(i)
+        else:
+            if len(current_run) >= min_contact_frames:
+                contact_frames.update(current_run)
+            current_run = []
+
+    # Handle last run
+    if len(current_run) >= min_contact_frames:
+        contact_frames.update(current_run)
+
+    return contact_frames
+
+
+def _assign_contact_states(
+    n_frames: int,
+    contact_frames: set[int],
+    visibilities: np.ndarray | None,
+    visibility_threshold: float,
+) -> list[ContactState]:
+    """Assign contact states based on contact frames and visibility.
+
+    Args:
+        n_frames: Total number of frames
+        contact_frames: Set of frames with confirmed contact
+        visibilities: Optional visibility scores for each frame
+        visibility_threshold: Minimum visibility to trust landmark
+
+    Returns:
+        List of ContactState for each frame
+    """
+    states = []
+    for i in range(n_frames):
+        if visibilities is not None and visibilities[i] < visibility_threshold:
+            states.append(ContactState.UNKNOWN)
+        elif i in contact_frames:
+            states.append(ContactState.ON_GROUND)
+        else:
+            states.append(ContactState.IN_AIR)
+    return states
+
+
 def detect_ground_contact(
     foot_positions: np.ndarray,
     velocity_threshold: float = 0.02,
@@ -247,7 +327,7 @@ def detect_ground_contact(
     """
     Detect when feet are in contact with ground based on vertical motion.
 
-    Uses derivative-based velocity calculation via Savitzky-Golay filter for smooth,
+    Uses derivative-based velocity calculation via Savitzky-Goyal filter for smooth,
     accurate velocity estimates. This is consistent with the velocity calculation used
     throughout the pipeline for sub-frame interpolation and curvature analysis.
 
@@ -264,52 +344,30 @@ def detect_ground_contact(
         List of ContactState for each frame
     """
     n_frames = len(foot_positions)
-    states = [ContactState.UNKNOWN] * n_frames
 
     if n_frames < 2:
-        return states
+        return [ContactState.UNKNOWN] * n_frames
 
     # Compute vertical velocity using derivative-based method
-    # This provides smoother, more accurate velocity estimates than frame-to-frame differences
-    # and is consistent with the velocity calculation used for sub-frame interpolation
     velocities = compute_velocity_from_derivative(
         foot_positions, window_length=window_length, polyorder=polyorder
     )
 
-    # Detect potential contact frames based on low velocity
+    # Detect stationary frames based on velocity threshold
     is_stationary = np.abs(velocities) < velocity_threshold
 
     # Apply visibility filter
-    if visibilities is not None:
-        is_visible = visibilities > visibility_threshold
-        is_stationary = is_stationary & is_visible
-
-    # Apply minimum contact duration filter
-    contact_frames = []
-    current_run = []
-
-    for i, stationary in enumerate(is_stationary):
-        if stationary:
-            current_run.append(i)
-        else:
-            if len(current_run) >= min_contact_frames:
-                contact_frames.extend(current_run)
-            current_run = []
-
-    # Don't forget the last run
-    if len(current_run) >= min_contact_frames:
-        contact_frames.extend(current_run)
+    is_stationary = _filter_stationary_with_visibility(
+        is_stationary, visibilities, visibility_threshold
+    )
 
-    # Set states
-    for i in range(n_frames):
-        if visibilities is not None and visibilities[i] < visibility_threshold:
-            states[i] = ContactState.UNKNOWN
-        elif i in contact_frames:
-            states[i] = ContactState.ON_GROUND
-        else:
-            states[i] = ContactState.IN_AIR
+    # Find frames with sustained contact
+    contact_frames = _find_contact_frames(is_stationary, min_contact_frames)
 
-    return states
+    # Assign states
+    return _assign_contact_states(
+        n_frames, contact_frames, visibilities, visibility_threshold
+    )
 
 
 def find_contact_phases(

kinemotion/dropjump/kinematics.py

@@ -19,6 +19,38 @@ 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."""
 
@@ -69,94 +101,65 @@ class DropJumpMetrics:
         # Complete metadata
         self.result_metadata: ResultMetadata | None = None
 
-    def to_dict(self) -> DropJumpResultDict:
-        """Convert metrics to JSON-serializable dictionary with data/metadata structure.
+    def _build_data_dict(self) -> DropJumpDataDict:
+        """Build the data portion of the result dictionary.
 
         Returns:
-            Dictionary with nested data and metadata structure.
+            Dictionary containing formatted metric values.
         """
-        data: DropJumpDataDict = {
-            "ground_contact_time_ms": (
-                round(self.ground_contact_time * 1000, 2)
-                if self.ground_contact_time is not None
-                else None
-            ),
-            "flight_time_ms": (
-                round(self.flight_time * 1000, 2)
-                if self.flight_time is not None
-                else None
+        return {
+            "ground_contact_time_ms": _format_float_metric(
+                self.ground_contact_time, 1000, 2
             ),
-            "jump_height_m": (
-                round(self.jump_height, 3) if self.jump_height is not None else None
+            "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_kinematic_m": (
-                round(self.jump_height_kinematic, 3)
-                if self.jump_height_kinematic is not None
-                else None
+            "jump_height_trajectory_normalized": _format_float_metric(
+                self.jump_height_trajectory, 1, 4
             ),
-            "jump_height_trajectory_normalized": (
-                round(self.jump_height_trajectory, 4)
-                if self.jump_height_trajectory is not None
-                else None
+            "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_start_frame": (
-                int(self.contact_start_frame)
-                if self.contact_start_frame is not None
-                else None
+            "contact_end_frame_precise": _format_float_metric(
+                self.contact_end_frame_precise, 1, 3
             ),
-            "contact_end_frame": (
-                int(self.contact_end_frame)
-                if self.contact_end_frame is not None
-                else None
+            "flight_start_frame_precise": _format_float_metric(
+                self.flight_start_frame_precise, 1, 3
             ),
-            "flight_start_frame": (
-                int(self.flight_start_frame)
-                if self.flight_start_frame is not None
-                else None
-            ),
-            "flight_end_frame": (
-                int(self.flight_end_frame)
-                if self.flight_end_frame is not None
-                else None
-            ),
-            "peak_height_frame": (
-                int(self.peak_height_frame)
-                if self.peak_height_frame is not None
-                else None
-            ),
-            "contact_start_frame_precise": (
-                round(self.contact_start_frame_precise, 3)
-                if self.contact_start_frame_precise is not None
-                else None
-            ),
-            "contact_end_frame_precise": (
-                round(self.contact_end_frame_precise, 3)
-                if self.contact_end_frame_precise is not None
-                else None
-            ),
-            "flight_start_frame_precise": (
-                round(self.flight_start_frame_precise, 3)
-                if self.flight_start_frame_precise is not None
-                else None
-            ),
-            "flight_end_frame_precise": (
-                round(self.flight_end_frame_precise, 3)
-                if self.flight_end_frame_precise is not None
-                else None
+            "flight_end_frame_precise": _format_float_metric(
+                self.flight_end_frame_precise, 1, 3
             ),
         }
 
-        # Build metadata from ResultMetadata if available, otherwise use legacy quality
+    def _build_metadata_dict(self) -> dict:
+        """Build the metadata portion of the result dictionary.
+
+        Returns:
+            Metadata dictionary from available sources.
+        """
         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}
+            return self.result_metadata.to_dict()
+        if self.quality_assessment is not None:
+            return {"quality": self.quality_assessment.to_dict()}
+        return {}
+
+    def to_dict(self) -> DropJumpResultDict:
+        """Convert metrics to JSON-serializable dictionary with data/metadata structure.
+
+        Returns:
+            Dictionary with nested data and metadata structure.
+        """
+        return {
+            "data": self._build_data_dict(),
+            "metadata": self._build_metadata_dict(),
+        }
 
 
 def _determine_drop_start_frame(

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

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

@@ -1,5 +1,5 @@
 kinemotion/__init__.py,sha256=vAEIg-oDX1ZkQMnWgXd__tekaA5KUcEvdJSAGWS8VUY,722
-kinemotion/api.py,sha256=3oLJEjtHweG85t_BG1nCWnZ-8yl3tGW_6ZoBAILMfJw,38006
+kinemotion/api.py,sha256=ELkAk0xq2MaafVwSAahXIf1KP9am8rpxHibqcnId6pg,38213
 kinemotion/cli.py,sha256=cqYV_7URH0JUDy1VQ_EDLv63FmNO4Ns20m6s1XAjiP4,464
 kinemotion/cmj/__init__.py,sha256=Ynv0-Oco4I3Y1Ubj25m3h9h2XFqeNwpAewXmAYOmwfU,127
 kinemotion/cmj/analysis.py,sha256=4HYGn4VDIB6oExAees-VcPfpNgWOltpgwjyNTU7YAb4,18263
@@ -18,13 +18,13 @@ kinemotion/core/quality.py,sha256=OC9nuf5IrQ9xURf3eA50VoNWOqkGwbjJpS90q2FDQzA,13
 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/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=PaVakc8eiYR6ZErp2jO3A8Ey-rNIso0rGLft6-yOEzs,17510
+kinemotion/dropjump/kinematics.py,sha256=Ig9TqXr-OEUm19gqIvUjQkqrCuw1csYt1f4ZfwG8oGc,17464
 kinemotion/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-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,,
+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,,