How hamza-louzan/bjj-position-classifier works
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).