How raulmdb/padel-pose-estimator works
A. Project Type and Purpose
1. This is a data-processing and machine-learning pipeline for automatic biomechanical analysis and shot classification in padel videos.
2. It is not a traditional client-server full-stack app but rather a research/analysis tool that ingests raw video, extracts features, stores them, performs EDA, trains LSTM models, and generates predictions.
B. File-Structure Analysis
Top-Level Files
• README.md, LICENSE, requirements.txt: project metadata.
• JSON files (clasificacion_golpes.json, fast_clasification.json) and CSVs (global_data.csv, train_data.csv): classification mappings and aggregated data.
• momento_model.keras: serialized trained model.
Key Directories
• videos/: raw, rendered, no_rendered folders for video lifecycle.
• notebooks/: Jupyter notebooks for each stage (data collection, EDA, model training, prediction).
• notebooks/utils/: helper scripts for data collection, constant definitions, and model training logic.
Implicit Data Directories (described in README but not in tree)
• jugadores/: per-player angular data.
• golpes/: organized by shot type / hand / quality.
C. Supplemental Insights from README
1. Workflow stages: Video capture & normalization → Pose detection via MediaPipe → Joint-angle computation → Data organization → EDA → LSTM training & evaluation → Inference.
Video Ingestion
• Component: Raw Video Store (videos/raw)
• Technology: Local file system or optional cloud bucket.
Preprocessing
• Component: Video Normalizer & Frame Extractor
• Inputs: raw videos
• Outputs: 60-frame sequences in videos/rendered and videos/no_rendered
• Code location: notebooks/utils/data_colector.py
Pose Estimation
• Component: MediaPipe Pose Detector
• Inputs: normalized frames
• Outputs: 3D landmarks per frame
• Code location: notebooks/utils/data_colector.py
Feature Extraction
• Component: Angle Calculator
• Inputs: landmarks
• Outputs: per-frame CSV of joint angles
• Code location: notebooks/utils/constant.py and data_colector.py
Data Storage
• Components:
• Per-player folder structure (jugadores/)
• Per-shot folder structure (golpes/)
• Aggregated CSV (global_data.csv)
• JSON mappings for classification
Exploratory Data Analysis (EDA)
• Component: EDA Notebook
• Inputs: aggregated CSVs
• Outputs: plots and statistical summaries
• Location: notebooks/EDA.ipynb
Model Training
• Component: LSTM Training Pipeline
• Inputs: train_data.csv or generated datasets
• Outputs: momento_model.keras, training metrics (precision, recall, AUC)
• Location: notebooks/ModelTraining.ipynb and notebooks/utils/model_training.py
Prediction Service
• Component: Prediction Notebook / Script
• Inputs: new angle CSV sequences
• Outputs: shot classification labels and quality
• Location: notebooks/Predictor.ipynb
External Libraries & Frameworks
• MediaPipe for pose detection
• TensorFlow/Keras for LSTM
• Pandas/NumPy for data handling
• Matplotlib/Seaborn for visualization
E. Relationships and Data Flow
JSON config files used at classification and quick-class phases
F. Architectural Patterns and Principles
Separation of Concerns: each stage lives in its own module/notebook.
3. Data-centric Architecture: file system as primary storage, CSV/JSON as interchange formats.
Modular Utilities: shared code under notebooks/utils for reusability.
G. Diagramming Guidelines
• Another for “Processing Units” (preprocessor, pose detector, angle calculator) in green.
• “Notebooks/Training” in orange.
• “Model Artifact” in purple.
4. If desired, group related components in swim-lanes or clusters: e.g., “Data Preparation”, “Feature Engineering”, “Modeling”.
H. Tailoring to This Project
Iterative nature: notebooks feed back into code utilities.
3. External dependencies (MediaPipe, TensorFlow) outside the core pipeline, connected to the components that use them.