kinemotion 0.6.4__tar.gz → 0.7.0__tar.gz

{kinemotion-0.6.4 → kinemotion-0.7.0}/.pre-commit-config.yaml

@@ -15,19 +15,20 @@ repos:
       - id: mixed-line-ending
 
   - repo: https://github.com/psf/black
-    rev: 23.12.1
+    rev: 25.9.0
     hooks:
       - id: black
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.1.9
+    rev: v0.14.3
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.7.1
+    rev: v1.18.2
     hooks:
       - id: mypy
         args: [--ignore-missing-imports, --no-strict-optional]
-        exclude: ^tests/
+        files: ^src/
+        exclude: ^(tests/|examples/)

{kinemotion-0.6.4 → kinemotion-0.7.0}/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## v0.7.0 (2025-11-01)
+
+### Features
+
+- Add intelligent auto-tuning and video rotation handling
+  ([`7b35f67`](https://github.com/feniix/kinemotion/commit/7b35f6790dd8b6714f3e42389555107a043d486c))
+
+
 ## v0.6.4 (2025-10-26)
 
 ### Bug Fixes

{kinemotion-0.6.4 → kinemotion-0.7.0}/CLAUDE.md

@@ -240,6 +240,48 @@ self.height = int(self.cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
 - Runtime validation in `write_frame()` ensures every frame matches expected encoded dimensions
 - Raises `ValueError` if aspect ratio would be corrupted
 
+### Video Rotation Handling (core/video_io.py)
+
+**IMPORTANT**: The tool automatically handles video rotation metadata from mobile devices. OpenCV ignores rotation metadata, so we extract and apply it manually.
+
+#### Rotation Metadata Extraction (`core/video_io.py:65-126`)
+
+- **Display Matrix Metadata**: iPhones and other mobile devices store rotation in `side_data_list`
+  - Common rotation values: -90° (portrait right), 90° (portrait left), 180° (upside down)
+  - OpenCV's `VideoCapture.read()` ignores this metadata (known OpenCV issue #26876)
+  - Extracted using ffprobe from the same call that extracts SAR metadata
+- **Automatic Frame Rotation**: Applied in `read_frame()` method using `cv2.rotate()`
+  - -90° / 270° → `cv2.ROTATE_90_CLOCKWISE`
+  - 90° / -270° → `cv2.ROTATE_90_COUNTERCLOCKWISE`
+  - ±180° → `cv2.ROTATE_180`
+- **Dimension Updates**: Width and height are swapped after 90°/-90° rotations
+
+```python
+# Rotation extraction from side_data_list
+side_data_list = stream.get("side_data_list", [])
+for side_data in side_data_list:
+    if side_data.get("side_data_type") == "Display Matrix":
+        self.rotation = int(side_data.get("rotation", 0))
+
+# Automatic rotation in read_frame()
+if self.rotation == -90 or self.rotation == 270:
+    frame = cv2.rotate(frame, cv2.ROTATE_90_CLOCKWISE)
+```
+
+**Why this matters:**
+
+- Without rotation handling, portrait videos are processed sideways
+- MediaPipe would detect poses on rotated frames (person lying horizontally)
+- Output videos would have incorrect orientation
+- Jump analysis would fail due to incorrect gravity axis
+
+**Example:**
+
+- iPhone video encoded as 1920x1080 (landscape) with -90° rotation metadata
+- Should be displayed as 1080x1920 (portrait)
+- Tool automatically rotates frames and updates dimensions
+- Output video correctly shows 1080x1920 portrait orientation
+
 ### Sub-Frame Interpolation (contact_detection.py:113-227)
 
 **IMPORTANT**: The tool uses sub-frame interpolation with derivative-based velocity to achieve timing precision beyond frame boundaries.
@@ -462,30 +504,129 @@ Modify `smooth_landmarks()` in `core/smoothing.py:9`:
 - `window_length`: Controls smoothing strength (must be odd, default: 5)
 - `polyorder`: Polynomial order for Savitzky-Golay filter (default: 2)
 
-### Parameter Tuning
+### Intelligent Auto-Tuning System
 
-**IMPORTANT**: See `docs/PARAMETERS.md` for comprehensive guide on all CLI parameters.
+**NEW**: The tool now features intelligent auto-tuning that eliminates the need for manual parameter adjustment!
 
-Quick reference for `dropjump-analyze`:
+#### How It Works (core/auto_tuning.py)
 
-- **smoothing-window**: Trajectory smoothness (↑ for noisy video)
-- **velocity-threshold**: Contact sensitivity (↓ to detect brief contacts)
-- **min-contact-frames**: Temporal filter (↑ to remove false contacts)
-- **visibility-threshold**: Landmark confidence (↓ for occluded landmarks)
-- **detection-confidence**: Pose detection strictness (MediaPipe)
-- **tracking-confidence**: Tracking persistence (MediaPipe)
-- **drop-height**: Drop box height in meters for calibration (e.g., 0.40 for 40cm)
-- **use-curvature**: Enable trajectory curvature analysis (default: enabled)
+The auto-tuning system analyzes your video and automatically selects optimal parameters:
 
-**Note**: Drop jump analysis always uses foot-based tracking with fixed velocity thresholds because typical drop jump videos are ~3 seconds long without a stationary baseline period. The `--use-com` and `--adaptive-threshold` options (available in `core/` modules) require longer videos (~5+ seconds) with 3 seconds of standing baseline, making them suitable for future jump types like CMJ (countermovement jump) but not drop jumps.
+**Phase 1: Video Analysis**
+- Extracts frame rate from video metadata
+- Analyzes landmark visibility quality (average MediaPipe confidence scores)
+- Measures position variance (tracking stability)
+- Detects drop jump pattern (stationary period on platform)
 
-The detailed guide includes:
+**Phase 2: Automatic Parameter Selection**
 
-- How each parameter works internally
-- Frame rate considerations
-- Scenario-based recommended settings
-- Debugging workflow with visual indicators
-- Parameter interaction effects
+**FPS-based scaling** (maintains consistent temporal resolution):
+```python
+velocity_threshold = 0.02 × (30 / fps)
+# 30fps → 0.020, 60fps → 0.010, 120fps → 0.005
+
+min_contact_frames = round(3 × (fps / 30))
+# 30fps → 3 frames (100ms), 60fps → 6 frames (100ms)
+
+smoothing_window = 5 if fps ≤ 30 else 3
+# Higher fps → less smoothing (better temporal resolution)
+```
+
+**Quality-based adjustments** (adapts to tracking quality):
+- High visibility (>0.7): Minimal smoothing, no bilateral filter
+- Medium visibility (0.4-0.7): Moderate smoothing, enable bilateral filter
+- Low visibility (<0.4): Aggressive smoothing, bilateral filter, lower confidence thresholds
+
+**Always enabled** (proven beneficial, no downsides):
+- Outlier rejection (removes tracking glitches)
+- Trajectory curvature analysis (sub-frame precision)
+- Drop start auto-detection (skips stationary period)
+- Polyorder 2 (optimal for parabolic jump motion)
+
+#### Quality Presets
+
+**`--quality fast`** (50% faster, good for batch processing)
+- Velocity threshold ×1.5 (less sensitive)
+- Reduced smoothing (-2 frames)
+- Skips bilateral filter
+- Lower detection confidence (0.3)
+
+**`--quality balanced`** (default, best for most cases)
+- FPS-adjusted parameters
+- Adaptive smoothing based on quality
+- All accuracy features enabled
+
+**`--quality accurate`** (research-grade, slower)
+- Velocity threshold ×0.5 (more sensitive)
+- Increased smoothing (+2 frames)
+- Always enables bilateral filter
+- Higher detection confidence (0.6)
+
+#### User-Facing Parameters
+
+**Reduced from 13 → 2 required + 2 optional:**
+
+**Required:**
+- `--drop-height`: Box height in meters (e.g., 0.40 for 40cm) - REQUIRED for accurate calibration
+
+**Optional:**
+- `--output`: Debug video path
+- `--json-output`: Metrics JSON path
+- `--quality`: fast/balanced/accurate (default: balanced)
+- `--verbose`: Show auto-selected parameters
+
+**Expert overrides** (rarely needed):
+- `--drop-start-frame`: Manual drop start frame
+- `--smoothing-window`: Override auto-tuned smoothing
+- `--velocity-threshold`: Override auto-tuned threshold
+- `--min-contact-frames`: Override auto-tuned minimum
+- `--visibility-threshold`: Override visibility threshold
+- `--detection-confidence`: Override MediaPipe detection
+- `--tracking-confidence`: Override MediaPipe tracking
+
+#### Migration from Manual Parameters
+
+**Old way** (complex, error-prone):
+```bash
+# User had to know these magic numbers for 60fps video
+uv run kinemotion dropjump-analyze video.mp4 \
+  --smoothing-window 3 \
+  --velocity-threshold 0.01 \
+  --min-contact-frames 6 \
+  --outlier-rejection \
+  --use-curvature
+```
+
+**New way** (simple, automatic):
+```bash
+# Just works - auto-detects 60fps and adjusts all parameters
+uv run kinemotion dropjump-analyze video.mp4
+```
+
+#### Viewing Auto-Selected Parameters
+
+Use `--verbose` to see what parameters were automatically selected:
+
+```bash
+uv run kinemotion dropjump-analyze video.mp4 --verbose
+
+# Output shows:
+# ============================================================
+# AUTO-TUNED PARAMETERS
+# ============================================================
+# Video FPS: 59.98
+# Tracking quality: high (avg visibility: 0.79)
+# Quality preset: balanced
+#
+# Selected parameters:
+#   smoothing_window: 3
+#   velocity_threshold: 0.0100
+#   min_contact_frames: 6
+#   ...
+# ============================================================
+```
+
+**Note**: See `docs/PARAMETERS.md` for detailed explanation of what each parameter does internally (useful for expert mode overrides).
 
 ### Working with Different Video Formats
 
@@ -576,6 +717,10 @@ If mypy reports errors:
 
 ## CLI Usage Examples
 
+**NEW: The tool now features intelligent auto-tuning!** Parameters are automatically adjusted based on video frame rate, tracking quality, and analysis preset. No manual parameter tuning required.
+
+### Simple Usage (Recommended)
+
 ```bash
 # Show main command help
 uv run kinemotion --help
@@ -583,35 +728,91 @@ uv run kinemotion --help
 # Show subcommand help
 uv run kinemotion dropjump-analyze --help
 
-# Basic analysis (JSON to stdout)
-uv run kinemotion dropjump-analyze video.mp4
+# Basic analysis (JSON to stdout) - JUST WORKS!
+# Drop-height is REQUIRED - specify your box height in meters
+# Auto-detects fps, tracking quality, and selects optimal parameters
+uv run kinemotion dropjump-analyze video.mp4 --drop-height 0.40
 
 # Save metrics to file
-uv run kinemotion dropjump-analyze video.mp4 --json-output results.json
+uv run kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --json-output results.json
 
 # Generate debug video
-uv run kinemotion dropjump-analyze video.mp4 --output debug.mp4
+uv run kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --output debug.mp4
 
-# Drop jump with calibration (40cm box)
-uv run kinemotion dropjump-analyze video.mp4 --drop-height 0.40
+# Complete analysis with all outputs
+uv run kinemotion dropjump-analyze video.mp4 \
+  --drop-height 0.40 \
+  --output debug.mp4 \
+  --json-output metrics.json
+
+# See what parameters were auto-selected
+uv run kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --verbose
+
+# Different box heights (examples)
+uv run kinemotion dropjump-analyze video.mp4 --drop-height 0.30  # 30cm box
+uv run kinemotion dropjump-analyze video.mp4 --drop-height 0.60  # 60cm box
+```
 
-# Custom parameters for noisy video
+### Quality Presets
+
+```bash
+# Fast analysis (quick, less precise)
+# - 50% faster processing
+# - Good for batch processing or initial assessment
+uv run kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --quality fast
+
+# Balanced analysis (default)
+# - Good accuracy/speed tradeoff
+# - Best for most use cases
+uv run kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --quality balanced
+
+# Accurate analysis (research-grade, slower)
+# - Maximum accuracy
+# - More aggressive smoothing and filtering
+# - Best for publication-quality data
+uv run kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --quality accurate
+```
+
+### Expert Mode (Advanced Users Only)
+
+```bash
+# Override specific auto-tuned parameters
 uv run kinemotion dropjump-analyze video.mp4 \
+  --drop-height 0.40 \
+  --expert \
   --smoothing-window 7 \
-  --velocity-threshold 0.01 \
-  --min-contact-frames 5
+  --velocity-threshold 0.015
 
-# Full analysis with calibration and all outputs
+# Manual drop start frame (if auto-detection fails)
 uv run kinemotion dropjump-analyze video.mp4 \
-  --output debug.mp4 \
-  --json-output metrics.json \
   --drop-height 0.40 \
-  --smoothing-window 7
+  --drop-start-frame 120
+```
 
-# Regular jump (no calibration, uses corrected kinematic method)
-uv run kinemotion dropjump-analyze jump.mp4 \
-  --output debug.mp4 \
-  --json-output metrics.json
+### Auto-Tuning Examples
+
+```bash
+# 30fps video - auto-selects:
+#   velocity_threshold: 0.020
+#   min_contact_frames: 3
+#   smoothing_window: 5
+uv run kinemotion dropjump-analyze video_30fps.mp4 --drop-height 0.40
+
+# 60fps video - auto-selects:
+#   velocity_threshold: 0.010
+#   min_contact_frames: 6
+#   smoothing_window: 3
+uv run kinemotion dropjump-analyze video_60fps.mp4 --drop-height 0.40
+
+# Low quality video (avg visibility < 0.4) - auto-enables:
+#   bilateral_filter: True
+#   smoothing_window: +2 adjustment
+uv run kinemotion dropjump-analyze low_quality.mp4 --drop-height 0.40
+
+# High quality video (avg visibility > 0.7) - optimizes:
+#   bilateral_filter: False (not needed)
+#   smoothing_window: minimal (preserve detail)
+uv run kinemotion dropjump-analyze high_quality.mp4 --drop-height 0.40
 ```
 
 ## MCP Server Configuration

{kinemotion-0.6.4 → kinemotion-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.6.4
+Version: 0.7.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.6.4 → kinemotion-0.7.0}/examples/programmatic_usage.py

@@ -1,7 +1,6 @@
 """Example of using drop-jump analysis programmatically."""
 
 import numpy as np
-
 from dropjump.contact_detection import (
     compute_average_foot_position,
     detect_ground_contact,
@@ -12,7 +11,7 @@ from dropjump.smoothing import smooth_landmarks
 from dropjump.video_io import VideoProcessor
 
 
-def analyze_video(video_path: str):
+def analyze_video(video_path: str) -> dict:
     """
     Analyze a drop-jump video and return metrics.
 

{kinemotion-0.6.4 → kinemotion-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kinemotion"
-version = "0.6.4"
+version = "0.7.0"
 description = "Video-based kinematic analysis for athletic performance"
 readme = "README.md"
 requires-python = ">=3.10,<3.13"
@@ -84,6 +84,8 @@ warn_redundant_casts = true
 warn_unused_ignores = true
 warn_no_return = true
 strict_equality = true
+files = ["src"]
+exclude = ["tests", "examples"]
 
 [[tool.mypy.overrides]]
 module = [

kinemotion-0.7.0/src/kinemotion/core/auto_tuning.py

@@ -0,0 +1,289 @@
+"""Automatic parameter tuning based on video characteristics."""
+
+from dataclasses import dataclass
+from enum import Enum
+
+import numpy as np
+
+
+class QualityPreset(str, Enum):
+    """Quality presets for analysis."""
+
+    FAST = "fast"  # Quick analysis, lower precision
+    BALANCED = "balanced"  # Default: good balance of speed and accuracy
+    ACCURATE = "accurate"  # Research-grade analysis, slower
+
+
+@dataclass
+class VideoCharacteristics:
+    """Characteristics extracted from video analysis."""
+
+    fps: float
+    frame_count: int
+    avg_visibility: float  # Average landmark visibility (0-1)
+    position_variance: float  # Variance in foot positions
+    has_stable_period: bool  # Whether video has initial stationary period
+    tracking_quality: str  # "low", "medium", "high"
+
+
+@dataclass
+class AnalysisParameters:
+    """Auto-tuned parameters for drop jump analysis."""
+
+    smoothing_window: int
+    polyorder: int
+    velocity_threshold: float
+    min_contact_frames: int
+    visibility_threshold: float
+    detection_confidence: float
+    tracking_confidence: float
+    outlier_rejection: bool
+    bilateral_filter: bool
+    use_curvature: bool
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary."""
+        return {
+            "smoothing_window": self.smoothing_window,
+            "polyorder": self.polyorder,
+            "velocity_threshold": self.velocity_threshold,
+            "min_contact_frames": self.min_contact_frames,
+            "visibility_threshold": self.visibility_threshold,
+            "detection_confidence": self.detection_confidence,
+            "tracking_confidence": self.tracking_confidence,
+            "outlier_rejection": self.outlier_rejection,
+            "bilateral_filter": self.bilateral_filter,
+            "use_curvature": self.use_curvature,
+        }
+
+
+def analyze_tracking_quality(avg_visibility: float) -> str:
+    """
+    Classify tracking quality based on average landmark visibility.
+
+    Args:
+        avg_visibility: Average visibility score across all tracked landmarks
+
+    Returns:
+        Quality classification: "low", "medium", or "high"
+    """
+    if avg_visibility < 0.4:
+        return "low"
+    elif avg_visibility < 0.7:
+        return "medium"
+    else:
+        return "high"
+
+
+def auto_tune_parameters(
+    characteristics: VideoCharacteristics,
+    quality_preset: QualityPreset = QualityPreset.BALANCED,
+) -> AnalysisParameters:
+    """
+    Automatically tune analysis parameters based on video characteristics.
+
+    This function implements heuristics to select optimal parameters without
+    requiring user expertise in video analysis or kinematic tracking.
+
+    Key principles:
+    1. FPS-based scaling: Higher fps needs lower velocity thresholds
+    2. Quality-based smoothing: Noisy video needs more smoothing
+    3. Always enable proven features: outlier rejection, curvature analysis
+    4. Preset modifiers: fast/balanced/accurate adjust base parameters
+
+    Args:
+        characteristics: Analyzed video characteristics
+        quality_preset: Quality vs speed tradeoff
+
+    Returns:
+        AnalysisParameters with auto-tuned values
+    """
+    fps = characteristics.fps
+    quality = characteristics.tracking_quality
+
+    # =================================================================
+    # STEP 1: FPS-based baseline parameters
+    # These scale automatically with frame rate to maintain consistent
+    # temporal resolution and sensitivity
+    # =================================================================
+
+    # Velocity threshold: Scale inversely with fps
+    # At 30fps, feet move ~2% of frame per frame when "stationary"
+    # At 60fps, feet move ~1% of frame per frame when "stationary"
+    # Formula: threshold = 0.02 * (30 / fps)
+    base_velocity_threshold = 0.02 * (30.0 / fps)
+
+    # Min contact frames: Scale with fps to maintain same time duration
+    # Goal: ~100ms minimum contact (3 frames @ 30fps, 6 frames @ 60fps)
+    # Formula: frames = round(3 * (fps / 30))
+    base_min_contact_frames = max(2, round(3.0 * (fps / 30.0)))
+
+    # Smoothing window: Decrease with higher fps for better temporal resolution
+    # Lower fps (30fps): 5-frame window = 167ms
+    # Higher fps (60fps): 3-frame window = 50ms (same temporal resolution)
+    if fps <= 30:
+        base_smoothing_window = 5
+    elif fps <= 60:
+        base_smoothing_window = 3
+    else:
+        base_smoothing_window = 3  # Even at 120fps, 3 is minimum for Savitzky-Golay
+
+    # =================================================================
+    # STEP 2: Quality-based adjustments
+    # Adapt smoothing and filtering based on tracking quality
+    # =================================================================
+
+    smoothing_adjustment = 0
+    enable_bilateral = False
+
+    if quality == "low":
+        # Poor tracking quality: aggressive smoothing and filtering
+        smoothing_adjustment = +2
+        enable_bilateral = True
+    elif quality == "medium":
+        # Moderate quality: slight smoothing increase
+        smoothing_adjustment = +1
+        enable_bilateral = True
+    else:  # high quality
+        # Good tracking: preserve detail, minimal smoothing
+        smoothing_adjustment = 0
+        enable_bilateral = False
+
+    # =================================================================
+    # STEP 3: Apply quality preset modifiers
+    # User can choose speed vs accuracy tradeoff
+    # =================================================================
+
+    if quality_preset == QualityPreset.FAST:
+        # Fast: Trade accuracy for speed
+        velocity_threshold = base_velocity_threshold * 1.5  # Less sensitive
+        min_contact_frames = max(2, int(base_min_contact_frames * 0.67))
+        smoothing_window = max(3, base_smoothing_window - 2 + smoothing_adjustment)
+        bilateral_filter = False  # Skip expensive filtering
+        detection_confidence = 0.3
+        tracking_confidence = 0.3
+
+    elif quality_preset == QualityPreset.ACCURATE:
+        # Accurate: Maximize accuracy, accept slower processing
+        velocity_threshold = base_velocity_threshold * 0.5  # More sensitive
+        min_contact_frames = (
+            base_min_contact_frames  # Don't increase (would miss brief)
+        )
+        smoothing_window = min(11, base_smoothing_window + 2 + smoothing_adjustment)
+        bilateral_filter = True  # Always use for best accuracy
+        detection_confidence = 0.6
+        tracking_confidence = 0.6
+
+    else:  # QualityPreset.BALANCED (default)
+        # Balanced: Good accuracy, reasonable speed
+        velocity_threshold = base_velocity_threshold
+        min_contact_frames = base_min_contact_frames
+        smoothing_window = max(3, base_smoothing_window + smoothing_adjustment)
+        bilateral_filter = enable_bilateral
+        detection_confidence = 0.5
+        tracking_confidence = 0.5
+
+    # Ensure smoothing window is odd (required for Savitzky-Golay)
+    if smoothing_window % 2 == 0:
+        smoothing_window += 1
+
+    # =================================================================
+    # STEP 4: Set fixed optimal values
+    # These are always the same regardless of video characteristics
+    # =================================================================
+
+    # Polyorder: Always 2 (quadratic) - optimal for jump physics (parabolic motion)
+    polyorder = 2
+
+    # Visibility threshold: Standard MediaPipe threshold
+    visibility_threshold = 0.5
+
+    # Always enable proven accuracy features
+    outlier_rejection = True  # Removes tracking glitches (minimal cost)
+    use_curvature = True  # Trajectory curvature analysis (minimal cost)
+
+    return AnalysisParameters(
+        smoothing_window=smoothing_window,
+        polyorder=polyorder,
+        velocity_threshold=velocity_threshold,
+        min_contact_frames=min_contact_frames,
+        visibility_threshold=visibility_threshold,
+        detection_confidence=detection_confidence,
+        tracking_confidence=tracking_confidence,
+        outlier_rejection=outlier_rejection,
+        bilateral_filter=bilateral_filter,
+        use_curvature=use_curvature,
+    )
+
+
+def analyze_video_sample(
+    landmarks_sequence: list[dict[str, tuple[float, float, float]] | None],
+    fps: float,
+    frame_count: int,
+) -> VideoCharacteristics:
+    """
+    Analyze video characteristics from a sample of frames.
+
+    This function should be called after tracking the first 30-60 frames
+    to understand video quality and characteristics.
+
+    Args:
+        landmarks_sequence: Tracked landmarks from sample frames
+        fps: Video frame rate
+        frame_count: Total number of frames in video
+
+    Returns:
+        VideoCharacteristics with analyzed properties
+    """
+    # Calculate average landmark visibility
+    visibilities = []
+    positions = []
+
+    for frame_landmarks in landmarks_sequence:
+        if frame_landmarks:
+            # Collect visibility scores from foot landmarks
+            foot_keys = [
+                "left_ankle",
+                "right_ankle",
+                "left_heel",
+                "right_heel",
+                "left_foot_index",
+                "right_foot_index",
+            ]
+
+            frame_vis = []
+            frame_y_positions = []
+
+            for key in foot_keys:
+                if key in frame_landmarks:
+                    _, y, vis = frame_landmarks[key]  # x not needed for analysis
+                    frame_vis.append(vis)
+                    frame_y_positions.append(y)
+
+            if frame_vis:
+                visibilities.append(float(np.mean(frame_vis)))
+            if frame_y_positions:
+                positions.append(float(np.mean(frame_y_positions)))
+
+    # Compute metrics
+    avg_visibility = float(np.mean(visibilities)) if visibilities else 0.5
+    position_variance = float(np.var(positions)) if len(positions) > 1 else 0.0
+
+    # Determine tracking quality
+    tracking_quality = analyze_tracking_quality(avg_visibility)
+
+    # Check for stable period (indicates drop jump from elevated platform)
+    # Simple check: do first 30 frames have low variance?
+    has_stable_period = False
+    if len(positions) >= 30:
+        first_30_std = float(np.std(positions[:30]))
+        has_stable_period = first_30_std < 0.01  # Very stable = on platform
+
+    return VideoCharacteristics(
+        fps=fps,
+        frame_count=frame_count,
+        avg_visibility=avg_visibility,
+        position_variance=position_variance,
+        has_stable_period=has_stable_period,
+        tracking_quality=tracking_quality,
+    )