kinemotion 0.17.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Potentially problematic release.
This version of kinemotion might be problematic. Click here for more details.
- kinemotion/__init__.py +31 -0
- kinemotion/api.py +946 -0
- kinemotion/cli.py +22 -0
- kinemotion/cmj/__init__.py +5 -0
- kinemotion/cmj/analysis.py +528 -0
- kinemotion/cmj/cli.py +543 -0
- kinemotion/cmj/debug_overlay.py +463 -0
- kinemotion/cmj/joint_angles.py +290 -0
- kinemotion/cmj/kinematics.py +191 -0
- kinemotion/core/__init__.py +40 -0
- kinemotion/core/auto_tuning.py +325 -0
- kinemotion/core/cli_utils.py +212 -0
- kinemotion/core/debug_overlay_utils.py +143 -0
- kinemotion/core/filtering.py +345 -0
- kinemotion/core/pose.py +259 -0
- kinemotion/core/smoothing.py +412 -0
- kinemotion/core/video_io.py +186 -0
- kinemotion/dropjump/__init__.py +29 -0
- kinemotion/dropjump/analysis.py +790 -0
- kinemotion/dropjump/cli.py +704 -0
- kinemotion/dropjump/debug_overlay.py +179 -0
- kinemotion/dropjump/kinematics.py +446 -0
- kinemotion/py.typed +0 -0
- kinemotion-0.17.0.dist-info/METADATA +529 -0
- kinemotion-0.17.0.dist-info/RECORD +28 -0
- kinemotion-0.17.0.dist-info/WHEEL +4 -0
- kinemotion-0.17.0.dist-info/entry_points.txt +2 -0
- kinemotion-0.17.0.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,529 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: kinemotion
|
|
3
|
+
Version: 0.17.0
|
|
4
|
+
Summary: Video-based kinematic analysis for athletic performance
|
|
5
|
+
Project-URL: Homepage, https://github.com/feniix/kinemotion
|
|
6
|
+
Project-URL: Repository, https://github.com/feniix/kinemotion
|
|
7
|
+
Project-URL: Source, https://github.com/feniix/kinemotion
|
|
8
|
+
Project-URL: Issues, https://github.com/feniix/kinemotion/issues
|
|
9
|
+
Author-email: Sebastian Otaegui <feniix@gmail.com>
|
|
10
|
+
License: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: athletic-performance,drop-jump,kinemetry,kinemotion,mediapipe,pose-tracking,video-analysis
|
|
13
|
+
Classifier: Development Status :: 3 - Alpha
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Topic :: Multimedia :: Video
|
|
21
|
+
Classifier: Topic :: Scientific/Engineering :: Image Recognition
|
|
22
|
+
Requires-Python: <3.13,>=3.10
|
|
23
|
+
Requires-Dist: click>=8.1.7
|
|
24
|
+
Requires-Dist: mediapipe>=0.10.9
|
|
25
|
+
Requires-Dist: numpy>=1.26.0
|
|
26
|
+
Requires-Dist: opencv-python>=4.9.0
|
|
27
|
+
Requires-Dist: scipy>=1.11.0
|
|
28
|
+
Description-Content-Type: text/markdown
|
|
29
|
+
|
|
30
|
+
# Kinemotion
|
|
31
|
+
|
|
32
|
+
[](https://pypi.org/project/kinemotion/)
|
|
33
|
+
[](https://opensource.org/licenses/MIT)
|
|
34
|
+
[](https://github.com/psf/black)
|
|
35
|
+
[](https://github.com/microsoft/pyright)
|
|
36
|
+
[](https://github.com/astral-sh/ruff)
|
|
37
|
+
[](https://sonarcloud.io/summary/new_code?id=feniix_kinemotion)
|
|
38
|
+
|
|
39
|
+
A video-based kinematic analysis tool for athletic performance. Analyzes vertical jump videos to estimate key performance metrics using MediaPipe pose tracking and advanced kinematics.
|
|
40
|
+
|
|
41
|
+
**Supported jump types:**
|
|
42
|
+
|
|
43
|
+
- **Drop Jump**: Ground contact time, flight time, reactive strength index
|
|
44
|
+
- **Counter Movement Jump (CMJ)**: Jump height, flight time, countermovement depth, triple extension biomechanics
|
|
45
|
+
|
|
46
|
+
## Features
|
|
47
|
+
|
|
48
|
+
### Core Features
|
|
49
|
+
|
|
50
|
+
- **Automatic pose tracking** using MediaPipe Pose landmarks
|
|
51
|
+
- **Derivative-based velocity** - smooth velocity calculation from position trajectory
|
|
52
|
+
- **Trajectory curvature analysis** - acceleration patterns for refined event detection
|
|
53
|
+
- **Sub-frame interpolation** - precise timing beyond frame boundaries
|
|
54
|
+
- **Intelligent auto-tuning** - automatic parameter optimization based on video characteristics
|
|
55
|
+
- **JSON output** for easy integration with other tools
|
|
56
|
+
- **Debug video overlays** with visual analysis
|
|
57
|
+
- **Batch processing** - CLI and Python API for parallel processing
|
|
58
|
+
- **Python library API** - use kinemotion programmatically
|
|
59
|
+
- **CSV export** - aggregated results for research
|
|
60
|
+
|
|
61
|
+
### Drop Jump Analysis
|
|
62
|
+
|
|
63
|
+
- **Ground contact detection** based on foot velocity and position
|
|
64
|
+
- **Automatic drop jump detection** - identifies box → drop → landing → jump phases
|
|
65
|
+
- **Metrics**: Ground contact time, flight time, jump height (with drop height calibration)
|
|
66
|
+
- **Reactive strength index** calculations
|
|
67
|
+
|
|
68
|
+
### Counter Movement Jump (CMJ) Analysis
|
|
69
|
+
|
|
70
|
+
- **Backward search algorithm** - robust phase detection from peak height
|
|
71
|
+
- **Flight time method** - force plate standard (h = g×t²/8)
|
|
72
|
+
- **Triple extension tracking** - ankle, knee, hip joint angles
|
|
73
|
+
- **Skeleton overlay** - biomechanical visualization
|
|
74
|
+
- **Metrics**: Jump height, flight time, countermovement depth, eccentric/concentric durations
|
|
75
|
+
- **Validated accuracy**: 50.6cm jump (±1 frame precision)
|
|
76
|
+
|
|
77
|
+
## Validation Status
|
|
78
|
+
|
|
79
|
+
⚠️ **IMPORTANT**: This tool's accuracy has **not been validated** against gold standard measurements (force plates, 3D motion capture). All accuracy claims and improvement estimates are theoretical and based on algorithmic considerations, not empirical testing.
|
|
80
|
+
|
|
81
|
+
The tool provides consistent measurements and may be useful for:
|
|
82
|
+
|
|
83
|
+
- Tracking relative changes in an individual athlete over time
|
|
84
|
+
- Comparing similar jumps under controlled conditions
|
|
85
|
+
- Exploratory analysis and research
|
|
86
|
+
|
|
87
|
+
For clinical, research, or performance assessment requiring validated accuracy, this tool should be compared against validated measurement systems before use.
|
|
88
|
+
|
|
89
|
+
## Setup
|
|
90
|
+
|
|
91
|
+
### Prerequisites
|
|
92
|
+
|
|
93
|
+
- [asdf](https://asdf-vm.com/) version manager
|
|
94
|
+
- asdf plugins for Python and uv
|
|
95
|
+
|
|
96
|
+
### Installation
|
|
97
|
+
|
|
98
|
+
1. **Install asdf plugins** (if not already installed):
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
asdf plugin add python
|
|
102
|
+
asdf plugin add uv
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
1. **Install versions specified in `.tool-versions`**:
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
asdf install
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
1. **Install project dependencies using uv**:
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
uv sync
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
This will install all dependencies and make the `kinemotion` command available.
|
|
118
|
+
|
|
119
|
+
## Usage
|
|
120
|
+
|
|
121
|
+
Kinemotion supports two jump types with intelligent auto-tuning that automatically optimizes parameters based on video characteristics.
|
|
122
|
+
|
|
123
|
+
### Drop Jump Analysis
|
|
124
|
+
|
|
125
|
+
Analyzes reactive strength and ground contact time:
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
# Automatic parameter tuning based on video characteristics
|
|
129
|
+
kinemotion dropjump-analyze video.mp4
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### Counter Movement Jump (CMJ) Analysis
|
|
133
|
+
|
|
134
|
+
Analyzes jump height and biomechanics:
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
# No drop height needed (floor level)
|
|
138
|
+
kinemotion cmj-analyze video.mp4
|
|
139
|
+
|
|
140
|
+
# With triple extension visualization
|
|
141
|
+
kinemotion cmj-analyze video.mp4 --output debug.mp4
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
### Common Options (Both Jump Types)
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
# Save metrics to JSON
|
|
148
|
+
kinemotion cmj-analyze video.mp4 --json-output results.json
|
|
149
|
+
|
|
150
|
+
# Generate debug video
|
|
151
|
+
kinemotion cmj-analyze video.mp4 --output debug.mp4
|
|
152
|
+
|
|
153
|
+
# Complete analysis with all outputs
|
|
154
|
+
kinemotion cmj-analyze video.mp4 \
|
|
155
|
+
--output debug.mp4 \
|
|
156
|
+
--json-output results.json \
|
|
157
|
+
--verbose
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
### Quality Presets
|
|
161
|
+
|
|
162
|
+
```bash
|
|
163
|
+
# Fast (50% faster, good for batch)
|
|
164
|
+
kinemotion cmj-analyze video.mp4 --quality fast
|
|
165
|
+
|
|
166
|
+
# Balanced (default)
|
|
167
|
+
kinemotion cmj-analyze video.mp4 --quality balanced
|
|
168
|
+
|
|
169
|
+
# Accurate (research-grade)
|
|
170
|
+
kinemotion cmj-analyze video.mp4 --quality accurate --verbose
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
### Batch Processing
|
|
174
|
+
|
|
175
|
+
Process multiple videos in parallel:
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
# Drop jumps
|
|
179
|
+
kinemotion dropjump-analyze videos/*.mp4 --batch --workers 4
|
|
180
|
+
|
|
181
|
+
# CMJ with output directories
|
|
182
|
+
kinemotion cmj-analyze videos/*.mp4 --batch --workers 4 \
|
|
183
|
+
--json-output-dir results/ \
|
|
184
|
+
--csv-summary summary.csv
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
## Python API
|
|
188
|
+
|
|
189
|
+
Use kinemotion as a library for automated pipelines and custom analysis.
|
|
190
|
+
|
|
191
|
+
### Drop Jump API
|
|
192
|
+
|
|
193
|
+
```python
|
|
194
|
+
from kinemotion import process_dropjump_video
|
|
195
|
+
|
|
196
|
+
# Process a single video
|
|
197
|
+
metrics = process_dropjump_video(
|
|
198
|
+
video_path="athlete_jump.mp4",
|
|
199
|
+
quality="balanced",
|
|
200
|
+
verbose=True
|
|
201
|
+
)
|
|
202
|
+
|
|
203
|
+
# Access results
|
|
204
|
+
print(f"Jump height: {metrics.jump_height:.3f} m")
|
|
205
|
+
print(f"Ground contact time: {metrics.ground_contact_time * 1000:.1f} ms")
|
|
206
|
+
print(f"Flight time: {metrics.flight_time * 1000:.1f} ms")
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
### Bulk Video Processing
|
|
210
|
+
|
|
211
|
+
```python
|
|
212
|
+
# Drop jump bulk processing
|
|
213
|
+
from kinemotion import DropJumpVideoConfig, process_dropjump_videos_bulk
|
|
214
|
+
|
|
215
|
+
configs = [
|
|
216
|
+
DropJumpVideoConfig("video1.mp4", quality="balanced"),
|
|
217
|
+
DropJumpVideoConfig("video2.mp4", quality="accurate"),
|
|
218
|
+
]
|
|
219
|
+
|
|
220
|
+
results = process_dropjump_videos_bulk(configs, max_workers=4)
|
|
221
|
+
|
|
222
|
+
# CMJ bulk processing
|
|
223
|
+
from kinemotion import CMJVideoConfig, process_cmj_videos_bulk
|
|
224
|
+
|
|
225
|
+
cmj_configs = [
|
|
226
|
+
CMJVideoConfig("cmj1.mp4"),
|
|
227
|
+
CMJVideoConfig("cmj2.mp4", quality="accurate"),
|
|
228
|
+
]
|
|
229
|
+
|
|
230
|
+
cmj_results = process_cmj_videos_bulk(cmj_configs, max_workers=4)
|
|
231
|
+
|
|
232
|
+
for result in cmj_results:
|
|
233
|
+
if result.success:
|
|
234
|
+
print(f"{result.video_path}: {result.metrics.jump_height*100:.1f}cm")
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
See `examples/bulk/README.md` for comprehensive API documentation.
|
|
238
|
+
|
|
239
|
+
### CMJ-Specific Features
|
|
240
|
+
|
|
241
|
+
```python
|
|
242
|
+
# Triple extension angles available in metrics
|
|
243
|
+
metrics = process_cmj_video("video.mp4", output_video="debug.mp4")
|
|
244
|
+
|
|
245
|
+
# Debug video shows:
|
|
246
|
+
# - Skeleton overlay (foot→shin→femur→trunk)
|
|
247
|
+
# - Joint angles (ankle, knee, hip, trunk)
|
|
248
|
+
# - Phase-coded visualization
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
### CSV Export Example
|
|
252
|
+
|
|
253
|
+
```python
|
|
254
|
+
# See examples/bulk/ for complete CSV export examples
|
|
255
|
+
from kinemotion import process_cmj_video
|
|
256
|
+
import csv
|
|
257
|
+
|
|
258
|
+
# ... process videos ...
|
|
259
|
+
with open("results.csv", "w", newline="") as f:
|
|
260
|
+
writer = csv.writer(f)
|
|
261
|
+
writer.writerow(["Video", "GCT (ms)", "Flight (ms)", "Jump (m)"])
|
|
262
|
+
|
|
263
|
+
for r in results:
|
|
264
|
+
if r.success and r.metrics:
|
|
265
|
+
writer.writerow([
|
|
266
|
+
Path(r.video_path).name,
|
|
267
|
+
f"{r.metrics.ground_contact_time * 1000:.1f}" if r.metrics.ground_contact_time else "N/A",
|
|
268
|
+
f"{r.metrics.flight_time * 1000:.1f}" if r.metrics.flight_time else "N/A",
|
|
269
|
+
f"{r.metrics.jump_height:.3f}" if r.metrics.jump_height else "N/A",
|
|
270
|
+
])
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
**See [examples/bulk/README.md](examples/bulk/README.md) for comprehensive API documentation and more examples.**
|
|
274
|
+
|
|
275
|
+
## Configuration Options
|
|
276
|
+
|
|
277
|
+
### Intelligent Auto-Tuning
|
|
278
|
+
|
|
279
|
+
Kinemotion automatically optimizes parameters based on your video:
|
|
280
|
+
|
|
281
|
+
- **FPS-based scaling**: 30fps, 60fps, 120fps videos use different thresholds automatically
|
|
282
|
+
- **Quality-based adjustments**: Adapts smoothing based on MediaPipe tracking confidence
|
|
283
|
+
- **Always enabled**: Outlier rejection, curvature analysis, drop start detection
|
|
284
|
+
|
|
285
|
+
### Required Parameters
|
|
286
|
+
|
|
287
|
+
- `--drop-height <float>` **\[REQUIRED\]**
|
|
288
|
+
- Height of drop box/platform in meters (e.g., 0.40 for 40cm)
|
|
289
|
+
- Used for accurate calibration of jump height measurements
|
|
290
|
+
- Measure your box height accurately for best results
|
|
291
|
+
|
|
292
|
+
### Optional Parameters
|
|
293
|
+
|
|
294
|
+
- `--quality [fast|balanced|accurate]` (default: balanced)
|
|
295
|
+
|
|
296
|
+
- **fast**: Quick analysis, less precise (~50% faster)
|
|
297
|
+
- **balanced**: Good accuracy/speed tradeoff (recommended)
|
|
298
|
+
- **accurate**: Research-grade analysis, slower (maximum precision)
|
|
299
|
+
|
|
300
|
+
- `--verbose` / `-v`
|
|
301
|
+
|
|
302
|
+
- Show auto-selected parameters and analysis details
|
|
303
|
+
- Useful for understanding what the tool is doing
|
|
304
|
+
|
|
305
|
+
- `--output <path>` / `-o`
|
|
306
|
+
|
|
307
|
+
- Generate annotated debug video with pose tracking visualization
|
|
308
|
+
|
|
309
|
+
- `--json-output <path>` / `-j`
|
|
310
|
+
|
|
311
|
+
- Save metrics to JSON file instead of stdout
|
|
312
|
+
|
|
313
|
+
### Expert Overrides (Rarely Needed)
|
|
314
|
+
|
|
315
|
+
For advanced users who need manual control:
|
|
316
|
+
|
|
317
|
+
- `--drop-start-frame <int>`: Manually specify where drop begins (if auto-detection fails)
|
|
318
|
+
- `--smoothing-window <int>`: Override auto-tuned smoothing window
|
|
319
|
+
- `--velocity-threshold <float>`: Override auto-tuned velocity threshold
|
|
320
|
+
- `--min-contact-frames <int>`: Override auto-tuned minimum contact frames
|
|
321
|
+
- `--visibility-threshold <float>`: Override visibility threshold
|
|
322
|
+
- `--detection-confidence <float>`: Override MediaPipe detection confidence
|
|
323
|
+
- `--tracking-confidence <float>`: Override MediaPipe tracking confidence
|
|
324
|
+
|
|
325
|
+
> **📖 For detailed parameter explanations, see [docs/reference/parameters.md](docs/reference/parameters.md)**
|
|
326
|
+
>
|
|
327
|
+
> **Note:** Most users never need expert parameters - auto-tuning handles optimization automatically!
|
|
328
|
+
|
|
329
|
+
## Output Format
|
|
330
|
+
|
|
331
|
+
### JSON Metrics
|
|
332
|
+
|
|
333
|
+
```json
|
|
334
|
+
{
|
|
335
|
+
"ground_contact_time_ms": 245.67,
|
|
336
|
+
"flight_time_ms": 456.78,
|
|
337
|
+
"jump_height_m": 0.339,
|
|
338
|
+
"jump_height_kinematic_m": 0.256,
|
|
339
|
+
"jump_height_trajectory_normalized": 0.0845,
|
|
340
|
+
"contact_start_frame": 45,
|
|
341
|
+
"contact_end_frame": 67,
|
|
342
|
+
"flight_start_frame": 68,
|
|
343
|
+
"flight_end_frame": 95,
|
|
344
|
+
"peak_height_frame": 82
|
|
345
|
+
}
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
**Fields**:
|
|
349
|
+
|
|
350
|
+
- `jump_height_m`: Primary jump height measurement (calibrated if --drop-height provided, otherwise corrected kinematic)
|
|
351
|
+
- `jump_height_kinematic_m`: Kinematic estimate from flight time: h = (g × t²) / 8
|
|
352
|
+
- `jump_height_trajectory_normalized`: Position-based measurement in normalized coordinates (0-1 range)
|
|
353
|
+
- `contact_start_frame_precise`, `contact_end_frame_precise`: Sub-frame timing (fractional frames)
|
|
354
|
+
- `flight_start_frame_precise`, `flight_end_frame_precise`: Sub-frame timing (fractional frames)
|
|
355
|
+
|
|
356
|
+
**Note**: Integer frame indices (e.g., `contact_start_frame`) are provided for visualization in debug videos. Precise fractional frames (e.g., `contact_start_frame_precise`) are used for all timing calculations and provide higher accuracy.
|
|
357
|
+
|
|
358
|
+
### Debug Video
|
|
359
|
+
|
|
360
|
+
The debug video includes:
|
|
361
|
+
|
|
362
|
+
- **Green circle**: Average foot position when on ground
|
|
363
|
+
- **Red circle**: Average foot position when in air
|
|
364
|
+
- **Yellow circles**: Individual foot landmarks (ankles, heels)
|
|
365
|
+
- **State indicator**: Current contact state (on_ground/in_air)
|
|
366
|
+
- **Phase labels**: "GROUND CONTACT" and "FLIGHT PHASE" during relevant periods
|
|
367
|
+
- **Peak marker**: "PEAK HEIGHT" at maximum jump height
|
|
368
|
+
- **Frame number**: Current frame index
|
|
369
|
+
|
|
370
|
+
## Troubleshooting
|
|
371
|
+
|
|
372
|
+
### Poor Tracking Quality
|
|
373
|
+
|
|
374
|
+
**Symptoms**: Erratic landmark positions, missing detections, incorrect contact states
|
|
375
|
+
|
|
376
|
+
**Solutions**:
|
|
377
|
+
|
|
378
|
+
1. **Check video quality**: Ensure the athlete is clearly visible in profile view
|
|
379
|
+
1. **Increase smoothing**: Use `--smoothing-window 7` or higher
|
|
380
|
+
1. **Adjust detection confidence**: Try `--detection-confidence 0.6` or `--tracking-confidence 0.6`
|
|
381
|
+
1. **Generate debug video**: Use `--output` to visualize what's being tracked
|
|
382
|
+
|
|
383
|
+
### No Pose Detected
|
|
384
|
+
|
|
385
|
+
**Symptoms**: "No frames processed" error or all null landmarks
|
|
386
|
+
|
|
387
|
+
**Solutions**:
|
|
388
|
+
|
|
389
|
+
1. **Verify video format**: OpenCV must be able to read the video
|
|
390
|
+
1. **Check framing**: Ensure full body is visible in side view
|
|
391
|
+
1. **Lower confidence thresholds**: Try `--detection-confidence 0.3 --tracking-confidence 0.3`
|
|
392
|
+
1. **Test video playback**: Verify video opens correctly with standard video players
|
|
393
|
+
|
|
394
|
+
### Incorrect Contact Detection
|
|
395
|
+
|
|
396
|
+
**Symptoms**: Wrong ground contact times, flight phases not detected
|
|
397
|
+
|
|
398
|
+
**Solutions**:
|
|
399
|
+
|
|
400
|
+
1. **Generate debug video**: Visualize contact states to diagnose the issue
|
|
401
|
+
1. **Adjust velocity threshold**:
|
|
402
|
+
- If missing contacts: decrease to `--velocity-threshold 0.01`
|
|
403
|
+
- If false contacts: increase to `--velocity-threshold 0.03`
|
|
404
|
+
1. **Adjust minimum frames**: `--min-contact-frames 5` for longer required contact
|
|
405
|
+
1. **Check visibility**: Lower `--visibility-threshold 0.3` if feet are partially obscured
|
|
406
|
+
|
|
407
|
+
### Jump Height Seems Wrong
|
|
408
|
+
|
|
409
|
+
**Symptoms**: Unrealistic jump height values
|
|
410
|
+
|
|
411
|
+
**Solutions**:
|
|
412
|
+
|
|
413
|
+
1. **Use calibration**: For drop jumps, add `--drop-height` parameter with box height in meters (e.g., `--drop-height 0.40`)
|
|
414
|
+
- Theoretically improves accuracy (⚠️ unvalidated)
|
|
415
|
+
1. **Verify flight time detection**: Check `flight_start_frame` and `flight_end_frame` in JSON
|
|
416
|
+
1. **Compare measurements**: JSON output includes both `jump_height_m` (primary) and `jump_height_kinematic_m` (kinematic-only)
|
|
417
|
+
1. **Check for drop jump detection**: If doing a drop jump, ensure first phase is elevated enough (>5% of frame height)
|
|
418
|
+
|
|
419
|
+
### Video Codec Issues
|
|
420
|
+
|
|
421
|
+
**Symptoms**: Cannot write debug video or corrupted output
|
|
422
|
+
|
|
423
|
+
**Solutions**:
|
|
424
|
+
|
|
425
|
+
1. **Install additional codecs**: Ensure OpenCV has proper video codec support
|
|
426
|
+
1. **Try different output format**: Use `.avi` extension instead of `.mp4`
|
|
427
|
+
1. **Check output path**: Ensure write permissions for output directory
|
|
428
|
+
|
|
429
|
+
## How It Works
|
|
430
|
+
|
|
431
|
+
1. **Pose Tracking**: MediaPipe extracts 2D pose landmarks (foot points: ankles, heels, foot indices) from each frame
|
|
432
|
+
1. **Position Calculation**: Averages ankle, heel, and foot index positions to determine foot location
|
|
433
|
+
1. **Smoothing**: Savitzky-Golay filter reduces tracking jitter while preserving motion dynamics
|
|
434
|
+
1. **Contact Detection**: Analyzes vertical position velocity to identify ground contact vs. flight phases
|
|
435
|
+
1. **Phase Identification**: Finds continuous ground contact and flight periods
|
|
436
|
+
- Automatically detects drop jumps vs regular jumps
|
|
437
|
+
- For drop jumps: identifies box → drop → ground contact → jump sequence
|
|
438
|
+
1. **Sub-Frame Interpolation**: Estimates exact transition times between frames
|
|
439
|
+
- Uses Savitzky-Golay derivative for smooth velocity calculation
|
|
440
|
+
- Linear interpolation of velocity to find threshold crossings
|
|
441
|
+
- Achieves sub-millisecond timing precision (at 30fps: ±10ms vs ±33ms)
|
|
442
|
+
- Reduces timing error by 60-70% for contact and flight measurements
|
|
443
|
+
- Smoother velocity curves eliminate false threshold crossings
|
|
444
|
+
1. **Trajectory Curvature Analysis**: Refines transitions using acceleration patterns
|
|
445
|
+
- Computes second derivative (acceleration) from position trajectory
|
|
446
|
+
- Detects landing impact by acceleration spike
|
|
447
|
+
- Identifies takeoff by acceleration change patterns
|
|
448
|
+
- Provides independent validation and refinement of velocity-based detection
|
|
449
|
+
1. **Metric Calculation**:
|
|
450
|
+
- Ground contact time = contact phase duration (using fractional frames)
|
|
451
|
+
- Flight time = flight phase duration (using fractional frames)
|
|
452
|
+
- Jump height = calibrated position-based measurement (if --drop-height provided)
|
|
453
|
+
- Fallback: kinematic estimate (g × t²) / 8 with optional empirical correction factor (⚠️ unvalidated)
|
|
454
|
+
|
|
455
|
+
## Development
|
|
456
|
+
|
|
457
|
+
### Code Quality Standards
|
|
458
|
+
|
|
459
|
+
This project enforces strict code quality standards:
|
|
460
|
+
|
|
461
|
+
- **Type safety**: Full pyright strict mode compliance with complete type annotations
|
|
462
|
+
- **Linting**: Comprehensive ruff checks (pycodestyle, pyflakes, isort, pep8-naming, etc.)
|
|
463
|
+
- **Formatting**: Black code style
|
|
464
|
+
- **Testing**: pytest with 61 unit tests
|
|
465
|
+
- **PEP 561 compliant**: Includes py.typed marker for type checking support
|
|
466
|
+
|
|
467
|
+
### Development Commands
|
|
468
|
+
|
|
469
|
+
```bash
|
|
470
|
+
# Run the tool
|
|
471
|
+
uv run kinemotion dropjump-analyze <video_path>
|
|
472
|
+
|
|
473
|
+
# Run all tests
|
|
474
|
+
uv run pytest
|
|
475
|
+
|
|
476
|
+
# Run tests with verbose output
|
|
477
|
+
uv run pytest -v
|
|
478
|
+
|
|
479
|
+
# Format code
|
|
480
|
+
uv run black src/
|
|
481
|
+
|
|
482
|
+
# Lint code
|
|
483
|
+
uv run ruff check
|
|
484
|
+
|
|
485
|
+
# Auto-fix linting issues
|
|
486
|
+
uv run ruff check --fix
|
|
487
|
+
|
|
488
|
+
# Type check
|
|
489
|
+
uv run pyright
|
|
490
|
+
|
|
491
|
+
# Run all checks
|
|
492
|
+
uv run ruff check && uv run pyright && uv run pytest
|
|
493
|
+
```
|
|
494
|
+
|
|
495
|
+
### Contributing
|
|
496
|
+
|
|
497
|
+
Before committing code, ensure all checks pass:
|
|
498
|
+
|
|
499
|
+
1. Format with Black
|
|
500
|
+
1. Fix linting issues with ruff
|
|
501
|
+
1. Ensure type safety with pyright
|
|
502
|
+
1. Run all tests with pytest
|
|
503
|
+
|
|
504
|
+
See [CLAUDE.md](CLAUDE.md) for detailed development guidelines.
|
|
505
|
+
|
|
506
|
+
## Limitations
|
|
507
|
+
|
|
508
|
+
- **2D Analysis**: Only analyzes motion in the camera's view plane
|
|
509
|
+
- **Validation Status**: ⚠️ Accuracy has not been validated against gold standard measurements (force plates, 3D motion capture)
|
|
510
|
+
- **Side View Required**: Must film from the side to accurately track vertical motion
|
|
511
|
+
- **Single Athlete**: Designed for analyzing one athlete at a time
|
|
512
|
+
- **Timing precision**:
|
|
513
|
+
- 30fps videos: ±10ms with sub-frame interpolation (vs ±33ms without)
|
|
514
|
+
- 60fps videos: ±5ms with sub-frame interpolation (vs ±17ms without)
|
|
515
|
+
- Higher frame rates still beneficial for better temporal resolution
|
|
516
|
+
- **Drop jump detection**: Requires first ground phase to be >5% higher than second ground phase
|
|
517
|
+
|
|
518
|
+
## Future Enhancements
|
|
519
|
+
|
|
520
|
+
- Advanced camera calibration (intrinsic parameters, lens distortion)
|
|
521
|
+
- Multi-angle analysis support
|
|
522
|
+
- Automatic camera orientation detection
|
|
523
|
+
- Real-time analysis from webcam
|
|
524
|
+
- Comparison with reference values
|
|
525
|
+
- Force plate integration for validation
|
|
526
|
+
|
|
527
|
+
## License
|
|
528
|
+
|
|
529
|
+
MIT License - feel free to use for personal experiments and research.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
kinemotion/__init__.py,sha256=vAEIg-oDX1ZkQMnWgXd__tekaA5KUcEvdJSAGWS8VUY,722
|
|
2
|
+
kinemotion/api.py,sha256=T9oqDxelyrVPhWifxUV8BVm8lu9sTREBLkEbT9fr678,31360
|
|
3
|
+
kinemotion/cli.py,sha256=cqYV_7URH0JUDy1VQ_EDLv63FmNO4Ns20m6s1XAjiP4,464
|
|
4
|
+
kinemotion/cmj/__init__.py,sha256=Ynv0-Oco4I3Y1Ubj25m3h9h2XFqeNwpAewXmAYOmwfU,127
|
|
5
|
+
kinemotion/cmj/analysis.py,sha256=4HYGn4VDIB6oExAees-VcPfpNgWOltpgwjyNTU7YAb4,18263
|
|
6
|
+
kinemotion/cmj/cli.py,sha256=bmDvNvL7cu65-R8YkRIZYKD0nuTA0IJnWLcLlH_kFm0,16843
|
|
7
|
+
kinemotion/cmj/debug_overlay.py,sha256=D-y2FQKI01KY0WXFKTKg6p9Qj3AkXCE7xjau3Ais080,15886
|
|
8
|
+
kinemotion/cmj/joint_angles.py,sha256=8ucpDGPvbt4iX3tx9eVxJEUv0laTm2Y58_--VzJCogE,9113
|
|
9
|
+
kinemotion/cmj/kinematics.py,sha256=Xl_PlC2OqMoA-zOc3SRB_GqI0AgLlJol5FTPe5J_qLc,7573
|
|
10
|
+
kinemotion/core/__init__.py,sha256=3yzDhb5PekDNjydqrs8aWGneUGJBt-lB0SoB_Y2FXqU,1010
|
|
11
|
+
kinemotion/core/auto_tuning.py,sha256=j6cul_qC6k0XyryCG93C1AWH2MKPj3UBMzuX02xaqfI,11235
|
|
12
|
+
kinemotion/core/cli_utils.py,sha256=Pq1JF7yvK1YbH0tOUWKjplthCbWsJQt4Lv7esPYH4FM,7254
|
|
13
|
+
kinemotion/core/debug_overlay_utils.py,sha256=TyUb5okv5qw8oeaX3jsUO_kpwf1NnaHEAOTm-8LwTno,4587
|
|
14
|
+
kinemotion/core/filtering.py,sha256=f-m-aA59e4WqE6u-9MA51wssu7rI-Y_7n1cG8IWdeRQ,11241
|
|
15
|
+
kinemotion/core/pose.py,sha256=ztemdZ_ysVVK3gbXabm8qS_dr1VfJX9KZjmcO-Z-iNE,8532
|
|
16
|
+
kinemotion/core/smoothing.py,sha256=C9GK3PAN16RpqJw2UWeVslSTJZEvALeVADjtnJnSF88,14240
|
|
17
|
+
kinemotion/core/video_io.py,sha256=kH5FYPx3y3lFZ3ybdgxaZfKPdHJ37eqxSeAaZjyQnJk,6817
|
|
18
|
+
kinemotion/dropjump/__init__.py,sha256=yc1XiZ9vfo5h_n7PKVSiX2TTgaIfGL7Y7SkQtiDZj_E,838
|
|
19
|
+
kinemotion/dropjump/analysis.py,sha256=xx5NWy6s0eb9BEyO_FByY1Ahunaoh3TyaTAxjlPrvxg,27153
|
|
20
|
+
kinemotion/dropjump/cli.py,sha256=J2F8ij-UcybY7YjK_bncQZiHNzrgS3Y7uTBkNo7y_L4,21328
|
|
21
|
+
kinemotion/dropjump/debug_overlay.py,sha256=LkPw6ucb7beoYWS4L-Lvjs1KLCm5wAWDAfiznUeV2IQ,5668
|
|
22
|
+
kinemotion/dropjump/kinematics.py,sha256=txDxpDti3VJVctWGbe3aIrlIx83UY8-ynzlX01TOvTA,15577
|
|
23
|
+
kinemotion/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
24
|
+
kinemotion-0.17.0.dist-info/METADATA,sha256=A7nGWLrkA83K6La3PZcU6V32Fm7EpvMpSePTtGLgbLw,18986
|
|
25
|
+
kinemotion-0.17.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
|
|
26
|
+
kinemotion-0.17.0.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
|
|
27
|
+
kinemotion-0.17.0.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
|
|
28
|
+
kinemotion-0.17.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Drop-Jump Analysis Contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|