video-analysis-workflow

name	video-analysis-workflow
description	Guides video analysis for CMJ and drop jump. Use when processing athlete videos, debugging pose detection, troubleshooting analysis failures, or running kinemotion CLI commands.

Video Analysis Workflow

Analysis Commands

# CMJ analysis
uv run kinemotion cmj-analyze <video> [--output debug.mp4]

# Drop Jump analysis
uv run kinemotion dropjump-analyze <video> [--output debug.mp4]

# Batch processing
uv run kinemotion cmj-analyze videos/*.mp4 --batch --workers 4

Quality Presets

Preset	Use Case	Trade-off
fast	Quick preview, large batches	Lower accuracy
balanced	Default, most use cases	Good accuracy/speed
accurate	Validation, research	Best accuracy, slower

uv run kinemotion cmj-analyze video.mp4 --quality accurate

Debug Output

Always use --output debug.mp4 when:

• Metrics seem incorrect
• Troubleshooting pose detection
• Validating new videos
• Training coaches on video quality

The debug video shows:

• Skeleton overlay with joint angles
• Phase markers (takeoff, landing, peak)
• Real-time metrics display

Camera Angle Recommendations

Angle	Recommendation	Reason
45° oblique	Recommended	Both legs clearly visible, accurate tracking
90° lateral	Not recommended	MediaPipe confuses left/right feet (occlusion)
Front/back	Not recommended	Depth ambiguity for sagittal plane motion

Troubleshooting

No Takeoff Detected

1. Verify video contains complete jump (before, during, after)
2. Check athlete is fully visible throughout
3. Try --quality accurate for stricter detection
4. Review debug video for landmark quality

Invalid Metrics

1. Video may be too short (need full jump cycle)
2. Athlete may be partially occluded
3. Poor lighting affecting pose detection
4. Camera shake causing landmark jitter

Jittery Landmarks

1. Check lighting conditions (avoid backlighting)
2. Ensure stable camera (tripod recommended)
3. Verify athlete clothing contrast with background
4. Try --quality accurate for better filtering

Rotation Issues (Mobile Videos)

• Mobile videos often have rotation metadata
• kinemotion handles this automatically via video_io.py
• If issues persist, pre-process with: ffmpeg -i input.mp4 -vf "transpose=1" output.mp4

Video Requirements

Requirement	Specification
Frame rate	30+ fps (60+ preferred)
Resolution	720p minimum
Duration	Full jump cycle visible
Lighting	Even, front-lit preferred
Background	Contrasting with athlete
Camera	Stable, tripod recommended

Output Metrics

CMJ Metrics

• jump_height_cm: Calculated from flight time
• flight_time_ms: Time in air
• countermovement_depth_cm: Lowest point before takeoff
• takeoff_velocity_m_s: Velocity at ground leave
• triple_extension: Hip, knee, ankle angles at takeoff

Drop Jump Metrics

• ground_contact_time_ms: Time on ground after drop
• flight_time_ms: Time in air after contact
• reactive_strength_index: RSI = flight_time / contact_time
• drop_height_cm: Initial drop height (if detectable)

Python API Alternative

from kinemotion import process_cmj_video, process_dropjump_video

# CMJ
metrics = process_cmj_video("video.mp4", quality="balanced")

# Drop Jump
metrics = process_dropjump_video("video.mp4", quality="balanced")

Advanced Troubleshooting

If you encounter issues not covered here:

• Use ref_search_documentation to check Kinemotion docs or MediaPipe/OpenCV docs.
• Use web_search_exa to search for similar issues online.