Adjust relative paths; Add metrics; Write README

README.md

@@ -1,13 +1,151 @@
----
-title: Age Gender Detector
-emoji: 🐢
-colorFrom: green
-colorTo: gray
-sdk: gradio
-sdk_version: 5.39.0
-app_file: app.py
-pinned: false
-short_description: Detecting Face and Property using YOLO
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Age Gender Detector
+
+This project implements a semi-real-time age and gender detection application using a combination of pre-trained YOLOv8 
+and fine-tuned YOLOv11 models from [Ultralytics](https://www.ultralytics.com/). The application processes either a 
+single image or a live video feed from a webcam, detects faces, and then predicts the age and gender of each detected 
+individual.
+
+The application is built with Python 3.10.3 and Gradio, providing a user-friendly web interface.
+
+A demo can be found [here](https://nguyentoanle41-age-gender-detector.hf.space/).
+
+## Contents
+1. [Features](#1-features)
+2. [Setup](#2-setup)
+3. [How to Run](#3-how-to-run)
+4. [Model Training and Datasets](#4-model-training-and-datasets)
+5. [Performance Results](#5-performance-results)
+
+## 🚀 Getting Started
+
+## 1. Features
+- **Face Detection**: Utilizes a YOLOv8-based face detection model to accurately locate faces in images and video frames.
+- **Age and Gender Classification**: Employs two separate YOLOv11 classification models, fine-tuned for age and gender
+prediction.
+- **Real-time Processing**: Supports real-time video processing from a webcam, with bounding boxes and predictions
+displayed directly on the video feed.
+- **User-friendly Interface**: A simple and intuitive web interface is provided by Gradio, allowing users to easily 
+upload images or use their camera for live feeding. A demo can be found 
+[here](https://nguyentoanle41-age-gender-detector.hf.space/).
+
+## 2. Setup
+### Prerequisites
+- Python 3.8 or higher.
+- `pip` package manager.
+
+### Installation
+1. Clone the repository:
+```
+git clone https://github.com/NguyenToanLe/Age-Gender-Detection-YOLO.git
+cd Age-Gender-Detection-YOLO
+```
+
+2. Install the required Python packages
+```
+pip install -r requirements.txt
+```
+
+## 3. How to Run
+
+If you don't want to use web interface, you can directly run `predictor.py` script. This will make the detection via 
+live camera usage smoother.
+```python
+python predictor.py
+```
+
+To start the application via web interface locally, simply run the `app.py` script from your terminal. Either use on of
+these two commands:
+```python
+python app.py
+gradio app.py
+```
+This will launch a Gradio server. You can access the application by navigating to the local URL provided in the terminal 
+output (e.g., `http://127.0.0.1:7860`). With the second command, the web-app will be automatically updated when you make 
+change in `app.py` script.
+
+## 4. Model Training and Datasets
+
+The age and gender classification models were fine-tuned separately. The notebooks used for training are available in 
+the `notebooks/` directory.
+
+### Datasets
+#### Age Classification
+The model for age prediction was fine-tuned on 
+[Age-Classification-Set](https://huggingface.co/datasets/prithivMLmods/Age-Classification-Set) dataset, which consists 
+of images of faces with corresponding age range labels. There are five age groups: `0-12, 13-20, 21-44, 45-64, 65+`. 
+
+There are `19016` images, with the distribution as following:
+
+- `0-12`: 2193 samples
+- `13-20`: 1779 samples
+- `21-44`: 9999 samples
+- `45-64`: 3785 samples
+- `65+`: 1260 samples
+
+Because the number of `21-44` group is exceeded, the number of these images is randomly reduced to `4000` samples 
+(comparable to the second most class in the dataset, `45-64`).
+
+Then these images were split with the ratios `train : eval : test = 8 : 1 : 1` evenly to ensure a balanced distribution 
+across different age groups, which is crucial for achieving high accuracy.
+
+#### Gender Classification
+The model for gender prediction was fined-tuned on 
+[gender-classification](https://huggingface.co/datasets/myvision/gender-classification) dataset, which consists of
+images of faces with corresponding gender, either `female` or `male`. 
+
+This dataset was already split into `train, eval, test` sets with the number of images in each set as following:
+
+- `train`: 5000 samples
+- `eval`: 1000 samples
+- `test`: 1000 samples
+
+## 5. Performance Results
+
+#### Age Classification Report
+
+This classifier was trained with `50` epochs and images were reduced to the size of `64`. This model reaches the overall
+accuracy of `79.14%`. The detailed performance is given by the table and confusion matrix below.
+
+<div style="margin-left: auto;
+            margin-right: auto;
+            width: 50%">
+
+| Age Groups | Precision | Recall | F1-score |
+|------------|----------:|-------:|---------:|
+| 0-12       |      0.89 |   0.95 |     0.92 |
+| 13-20      |      0.69 |   0.61 |     0.65 |
+| 21-44      |      0.77 |   0.75 |     0.76 |
+| 45-64      |      0.79 |   0.82 |     0.80 |
+| 65+        |      0.78 |   0.83 |     0.80 |
+</div>
+
+<div style="text-align: center;">
+
+![](./src/age_cls_confusion_matrix.png)
+</div>
+
+The metrics show that the model still confuse between two adjacent groups, except for the youngest group. This can be 
+improve through hyperparameter tuning or through the enhancement of the dataset.
+
+#### Gender Classification Report
+
+This classifier was trained with `10` epochs and images were reduced to the size of `64`. This model reaches the overall
+accuracy of `92.50%`. The detailed performance is given by the table and confusion matrix below.
+
+<div style="margin-left: auto;
+            margin-right: auto;
+            width: 50%">
+
+| Gender | Precision | Recall | F1-score |
+|--------|----------:|-------:|---------:|
+| female |      0.94 |   0.91 |     0.92 |
+| male   |      0.91 |   0.94 |     0.93 |
+</div>
+
+<div style="text-align: center;">
+
+![](./src/gender_cls_confusion_matrix.png)
+</div>
+
+The classifier can improve in performance through hyperparameter tuning (e.g., increasing epochs because the training
+process did not reach the overfitting point).