# raulmdb/padel-pose-estimator architecture

> Architecture diagram of the GitHub repository raulmdb/padel-pose-estimator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/raulmdb/padel-pose-estimator
- Repository: https://github.com/raulmdb/padel-pose-estimator

## Overview

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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Preparation
    subgraph "Data Preparation"
        RawVideo["Raw Video Store\n(videos/)"]:::datastore
        DataCollectorNB["Raw Data Collection Notebook\n(notebooks/DataColector.ipynb)"]:::notebook
        Preprocessor["Video Normalizer & Frame Extractor\n(notebooks/utils/data_colector.py)"]:::process
        Pose["MediaPipe Pose Detector\n(notebooks/utils/data_colector.py)"]:::process
        Angle["Angle Calculator\n(notebooks/utils/constant.py & data_colector.py)"]:::process
        StorageCSV["Aggregated Data Store\n(global_data.csv)"]:::datastore
        JSONMap["JSON Classification Mappings\n(clasificacion_golpes.json, fast_clasification.json)"]:::config
    end

    %% Modeling and Analysis
    subgraph "Modeling & Analysis"
        EDA["Exploratory Data Analysis\n(notebooks/EDA.ipynb)"]:::notebook
        Training["LSTM Training Pipeline\n(notebooks/ModelTraining.ipynb & notebooks/utils/model_training.py)"]:::notebook
        Model["Trained Model Artifact\n(momento_model.keras)"]:::model
        Predictor["Prediction Service\n(notebooks/Predictor.ipynb)"]:::notebook
        Output["Classification Output"]:::notebook
    end

    %% Data Flow
    RawVideo -->|"MP4"| DataCollectorNB
    DataCollectorNB -->|"Videos"| Preprocessor
    Preprocessor -->|"Frames"| Pose
    Pose -->|"Landmarks"| Angle
    Angle -->|"Angle CSVs"| StorageCSV

    StorageCSV -->|"CSV"| EDA
    StorageCSV -->|"CSV"| Training
    Training -->|"Model (.keras)"| Model

    StorageCSV -->|"CSV Sequences"| Predictor
    Model -->|".keras"| Predictor
    Predictor -->|"Predictions"| Output

    %% Config flows
    JSONMap -.-> Training
    JSONMap -.-> Predictor

    %% Click Events
    click RawVideo "https://github.com/raulmdb/padel-pose-estimator/tree/videos_estimator/videos/"
    click DataCollectorNB "https://github.com/raulmdb/padel-pose-estimator/blob/videos_estimator/notebooks/DataColector.ipynb"
    click Preprocessor "https://github.com/raulmdb/padel-pose-estimator/blob/videos_estimator/notebooks/utils/data_colector.py"
    click Pose "https://github.com/raulmdb/padel-pose-estimator/blob/videos_estimator/notebooks/utils/data_colector.py"
    click Angle "https://github.com/raulmdb/padel-pose-estimator/blob/videos_estimator/notebooks/utils/constant.py"
    click Angle "https://github.com/raulmdb/padel-pose-estimator/blob/videos_estimator/notebooks/utils/data_colector.py"
    click StorageCSV "https://github.com/raulmdb/padel-pose-estimator/blob/videos_estimator/global_data.csv"
    click JSONMap "https://github.com/raulmdb/padel-pose-estimator/blob/videos_estimator/clasificacion_golpes.json"
    click JSONMap "https://github.com/raulmdb/padel-pose-estimator/blob/videos_estimator/fast_clasification.json"
    click EDA "https://github.com/raulmdb/padel-pose-estimator/blob/videos_estimator/notebooks/EDA.ipynb"
    click Training "https://github.com/raulmdb/padel-pose-estimator/blob/videos_estimator/notebooks/ModelTraining.ipynb"
    click Training "https://github.com/raulmdb/padel-pose-estimator/blob/videos_estimator/notebooks/utils/model_training.py"
    click Model "https://github.com/raulmdb/padel-pose-estimator/blob/videos_estimator/momento_model.keras"
    click Predictor "https://github.com/raulmdb/padel-pose-estimator/blob/videos_estimator/notebooks/Predictor.ipynb"

    %% Styles
    classDef datastore fill:#ADD8E6,stroke:#1E90FF,color:#000
    classDef process fill:#90EE90,stroke:#2E8B57,color:#000
    classDef notebook fill:#FFA500,stroke:#FF8C00,color:#000
    classDef model fill:#DDA0DD,stroke:#9932CC,color:#000
    classDef config fill:#D3D3D3,stroke:#696969,color:#000
```
