# hamza-louzan/bjj-position-classifier architecture

> Architecture diagram of the GitHub repository hamza-louzan/bjj-position-classifier, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hamza-louzan/bjj-position-classifier
- Repository: https://github.com/hamza-louzan/bjj-position-classifier

## Overview

Based on our analysis of the file tree and README, this project is a computer vision and machine learning application that automatically detects and classifies Brazilian Jiu-Jitsu (BJJ) positions in images. The project leverages MediaPipe for pose detection, computes features from the detected keypoints, and classifies positions using a neural network model (trained with TensorFlow/Keras).

##### Project Type and Purpose
- This is an ML-based computer vision project focused on detecting human poses (of two athletes) and classifying BJJ positions.
- The system is split into two primary pipelines: one for training the position classifier and another for running predictions on new images.

##### Main Components
a. Data Pipeline:
- Input Data: Represent the expected external data folder (data/annotations.json and data/images/) as a source feeding into the system.

b. Pose Detection Module:
- A component labeled “Pose Detection” which uses MediaPipe libraries.
- Link the input image from the Data Pipeline to this module.
- Inside this component (or as a side note), specify that it extracts keypoints for both athletes.
- Reference the "pose_utils.py" which encapsulates the logic of pose detection and any utilities for processing and normalizing keypoints.

c. Feature Extraction and Preprocessing:

d. Model Training Pipeline:
- A component for "Neural Network Training" which represents the training logic encapsulated in "model_training.py".
- That this component receives the extracted features and uses them to train the classifier model.
- Outputs like: trained model file (bjj_position_model.h5), scaler (bjj_scaler.pkl), and label encoder (bjj_label_encoder.pkl).
- The training pipeline is triggered via main.py with a "train" command.

e. Model Inference / Prediction Pipeline:
- Interactions where the trained model, scaler, and label encoder are applied to new images to predict the BJJ position.

f. Command Controller:

##### Relationships and Data Flow
- Input data (images and annotations) → Pose Detection (via pose_utils.py).
- Pose Detection → Feature Extraction.
- Feature Extraction → Neural Network Training (for the training pipeline).
- For inference, route a new image through Pose Detection & Feature Extraction → Prediction Engine.
- From the training process, output artifacts (model file, scaler, encoder) become the inputs for the prediction process.
- That "main.py" acts as the orchestrator for switching between train and predict modes.

##### Architectural Patterns and Important Technologies
- Separation of concerns: distinct modules for pose detection, feature extraction, model training, and inference.
- That the design leverages an ML workflow design pattern (data ingestion, preprocessing, model training, evaluation/prediction).
- Mention that the project depends on external libraries: MediaPipe for pose estimation and TensorFlow/Keras for the neural network.
- For example, use rectangles for processing components (Pose Detection, Feature Extraction, Model Training, Inference).
- Use ellipses for external data sources (images, annotations).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Controller
    MC["Main Controller (Orchestrates train_and_predict flows)"]:::controller

    %% Training Pipeline Subgraph
    subgraph "Training Pipeline"
        T1["Data Pipeline (Images & Annotations)"]:::external
        PD_train["Pose Detection (MediaPipe)\n(Extracts keypoints for both athletes)"]:::module
        FE_train["Feature Extraction\n(Normalizes keypoints & computes distances)"]:::module
        NT["Neural Network Training\n(Outputs: bjj_position_model.h5, bjj_scaler.pkl, bjj_label_encoder.pkl)"]:::module
        T1 -->|"feeds"| PD_train
        PD_train -->|"processes"| FE_train
        FE_train -->|"generates features"| NT
    end

    %% Inference Pipeline Subgraph
    subgraph "Inference Pipeline"
        NI["New Image Input"]:::external
        PD_infer["Pose Detection (MediaPipe)\n(Extracts keypoints for both athletes)"]:::module
        FE_infer["Feature Extraction\n(Normalizes keypoints & computes distances)"]:::module
        PI["Prediction Engine"]:::module
        NI -->|"feeds"| PD_infer
        PD_infer -->|"processes"| FE_infer
        FE_infer -->|"predicts"| PI
    end

    %% Main Controller directs both flows
    MC -->|"triggers"| NT
    MC -->|"triggers"| PI

    %% Use training outputs in inference
    NT -->|"artifacts used"| PI

    %% Click Events
    click T1 "https://github.com/hamza-louzan/bjj-position-classifier/tree/main/images/"
    click PD_train "https://github.com/hamza-louzan/bjj-position-classifier/blob/main/pose_utils.py"
    click PD_infer "https://github.com/hamza-louzan/bjj-position-classifier/blob/main/pose_utils.py"
    click NT "https://github.com/hamza-louzan/bjj-position-classifier/blob/main/model_training.py"
    click PI "https://github.com/hamza-louzan/bjj-position-classifier/blob/main/inference.py"
    click MC "https://github.com/hamza-louzan/bjj-position-classifier/blob/main/main.py"

    %% Styles
    classDef external fill:#A9DFBF,stroke:#1D8348,stroke-width:2px;
    classDef controller fill:#AED6F1,stroke:#2874A6,stroke-width:2px,stroke-dasharray: 5 5;
    classDef module fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
```
