retinaface-pytorch

📸 RetinaFace: Single-stage Dense Face Localisation in the Wild

This is a face detection model for high-precision facial localization based on RetinaFace: Single-stage Dense Face Localisation in the Wild. This model accurately detects facial landmarks and bounding boxes for faces in images. This repository provides custom training & inference code, and several new backbone models have been integrated for improved performance and flexibility.

[!NOTE]
We’ve updated the codebase with new trained models and a refactored structure, enhancing functionality and maintainability. These improvements include support for MobileNetV1 (including v1_025 and v1_050), MobileNetV2, and various ResNet versions (18, 34, 50), offering a cleaner and more reproducible experience.

In this implementation, we use several lightweight and powerful backbone architectures to provide flexibility between performance and accuracy.

📈 Results on WiderFace Eval

Results of RetinaFace (MXNet-based Image Size)

RetinaFace Backbones	Pretrained on ImageNet	Easy	Medium	Hard
MobileNetV1 (width mult=0.25)	True	88.48%	87.02%	80.61%
MobileNetV1 (width mult=0.50)	False	89.42%	87.97%	82.40%
MobileNetV1	False	90.59%	89.14%	84.13%
MobileNetV2	True	91.70%	91.03%	86.60%
ResNet18	True	92.50%	91.02%	86.63%
ResNet34	True	94.16%	93.12%	88.90%
ResNet50	True

Results of RetinaFace, based on Original Image Size

RetinaFace Backbones	Pretrained on ImageNet	Easy	Medium	Hard
MobileNetV1 (width mult=0.25)	True	90.70%	88.12%	73.82%
MobileNetV1 (width mult=0.50)	False	91.56%	89.46%	76.56%
MobileNetV1	False	92.19%	90.41%	79.56%
MobileNetV2	True	94.04%	92.26%	83.59%
ResNet18	True	94.28%	92.69%	82.95%
ResNet34	True	95.07%	93.48%	84.40%
ResNet50	True

✨ Features

• 🎥 Webcam Inference: Real-time inference capability using a webcam for direct application testing and live demos.
• 🔄 ONNX Export & Inference: Enables model export to ONNX format for versatile deployment and cross-platform inference.
• ✅ Cleaner & Reproducible Code: Refactored for simplicity and consistency, making it easier to use and maintain.
• 📱 MobileNetV1_0.25 & MobileNetV1_0.50: Lightweight versions for faster inference with reduced computational cost.
• 📲 MobileNetV1: Efficient Convolutional Neural Networks for Mobile Vision Applications - Optimized for mobile and low-power applications.
• 📈 MobileNetV2: Inverted Residuals and Linear Bottlenecks - Improved efficiency for mobile use-cases with advanced architecture.
• 🔍 ResNet Models (18, 34, 50): Deep Residual Networks - Enhanced accuracy with deeper residual connections, supporting a range of model complexities.

📅 Last Updated: November 5, 2024

⚙️ Installation

1. Clone the repository:

   git clone https://github.com/yakhyo/retinaface-pytorch.git
   cd retinaface-pytorch
   

2. Install dependencies:

   pip install -r requirements.txt
   

🔄 Backbones

This RetinaFace implementation supports the following feature extractor backbones:

• 🟢 MobileNetV1: Lightweight and fast, suitable for mobile and embedded devices.
• 🟠 MobileNetV1_0.25 & 0.50: Variants of MobileNetV1 with reduced width multipliers for faster inference.
• 🔵 MobileNetV2: Improved version of MobileNetV1 with better accuracy.
• 🟣 ResNet18/34/50: A range of ResNet models providing a balance between complexity and performance.

📂 Dataset

📥 Download the WIDERFACE Dataset

1. Download the Dataset:

   • Download the WIDERFACE dataset.
   • Download annotations (face bounding boxes & five facial landmarks) from Baidu Cloud (password: fstq) or Dropbox.

2. Organize the Dataset Directory:

   Structure your dataset directory as follows:

   data/
   └── widerface/
      ├── train/
      │   ├── images/
      │   └── label.txt
      └── val/
         ├── images/
         └── wider_val.txt
   

[!NOTE]
wider_val.txt only includes val file names but not label information.

There is also an organized dataset (as shown above): Link from Google Drive or Baidu Cloud (password: ruck). Thanks to biubug6 for the organized dataset.

🏋️‍♂️ Training

To train the RetinaFace model with a specific backbone, use the following command:

python train.py --network mobilenetv1  # Replace 'mobilenetv1' with your choice of backbone

Download mobilenetv1_0.25.pretrained (pre-trained weights on ImageNet, weights ported from @biubug6) to reproduce the results.

🎛️ Available Backbone Options:

• mobilenetv1_0.25
• mobilenetv1_0.50
• mobilenetv1
• mobilenetv2
• resnet18
• resnet34
• resnet50

⬇️ Get Pretrained Models

MobileNet-based models:

Model Name	PyTorch Weights	ONNX Weights Filename
MobileNetV1_025	retinaface_mv1_0.25.pth	retinaface_mv1_0.25.onnx
MobileNetV1_050	retinaface_mv1_0.50.pth	retinaface_mv1_0.50.onnx
MobileNetV1	retinaface_mv1.pth	retinaface_mv1.onnx
MobileNetV2	retinaface_mv2.pth	retinaface_mv2.onnx

ResNet-based models:

Model Name	PyTorch Weights	ONNX Weights Filename
ResNet18	retinaface_r18.pth	retinaface_r18.onnx
ResNet34	retinaface_r34.pth	retinaface_r34.onnx
ResNet50	not available	not available

📊 Inference

Inference the model using:

python detect.py --network mobilenetv1 --weights retinaface_mv1.pth

Using MobileNet v2 as a backbone, 632 faces found on large selfi image, see the `assets` folder.

🧪 Evaluating RetinaFace on WiderFace Dataset

1. Get and Install WiderFace Evaluation Tool

1. Clone the WiderFace evaluation repository inside the retinaface-pytorch folder:

   git clone https://github.com/yakhyo/widerface_evaluation
   

2. Navigate to the widerface_evaluation folder and build the required extension:

   cd widerface_evaluation
   python3 setup.py build_ext --inplace
   

3. Return to the retinaface-pytorch folder after installation is complete:

   cd ..
   

2. Generate Predictions

Run the following command to evaluate your RetinaFace model with WiderFace, specifying the model architecture (mobilenetv1 in this example) and the path to the trained weights. Predictions will be stored in widerface_txt inside the widerface_evaluation folder.

python evaluate_widerface.py --network mobilenetv1 --weights weights/mobilenetv1.pth

3. Run the Final Evaluation

After generating predictions, navigate to the widerface_evaluation folder and run the following command to compare predictions with the ground truth annotations:

cd widerface_evaluation
python evaluation.py -p widerface_txt -g ground_truth

[!NOTE]
Ensure ground_truth is the path to the WiderFace ground truth directory.

This will begin the evaluation process of your model on the WiderFace dataset.

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.

🔗 References

• https://github.com/biubug6/Pytorch_Retinaface
• https://github.com/yakhyo/faceboxes-pytorch

This site is open source. Improve this page.