SlimFace: Efficient Face Recognition 🚀

Credits and Citation

ℹ️ This project leverages code from by , with our own bug fixes and enhancements available at . Explore additional EdgeFace models on the Hugging Face Hub: .

If this project is helpful for your research, please consider citing the original paper:

Edgeface: Efficient face recognition model for edge devices
George, Anjith and Ecabert, Christophe and Shahreza, Hatef Otroshi and Kotwal, Ketan and Marcel, Sebastien
IEEE Transactions on Biometrics, Behavior, and Identity Science (2024)

If you use this work in your research, please cite the original paper:

@article{edgeface,
  title={Edgeface: Efficient face recognition model for edge devices},
  author={George, Anjith and Ecabert, Christophe and Shahreza, Hatef Otroshi and Kotwal, Ketan and Marcel, Sebastien},
  journal={IEEE Transactions on Biometrics, Behavior, and Identity Science},
  year={2024}
}

Introduction

SlimFace is a robust and efficient framework for face recognition, designed to enable developers to build high-accuracy models using transfer learning with pre-trained TorchVision architectures. Optimized for edge devices, SlimFace delivers a scalable solution with minimal computational overhead, supporting custom datasets for tailored applications and providing an interactive interface for seamless inference and testing.

Key Features

• High Accuracy: Utilizes pre-trained TorchVision models fine-tuned for precise face classification.
• Efficient Pipeline: Optimized for edge devices to ensure low computational requirements.
• Flexible Training: Supports custom datasets, enabling tailored face recognition solutions.
• Gradio Demo: Provides an interactive interface for easy model inference and testing.

Datasets

You can explore more in this Kaggle Dataset available at the given link for further details: .

The dataset preparation script is located at scripts/process_dataset.py.

Base Model

SlimFace leverages pre-trained TorchVision models fine-tuned for face recognition. Follow this scripts/download_ckpts.py to download model checkpoints.

For more details on Base Models, refer to the PyTorch Pretrained Model Documentation: .

Demonstration

Interactive Demo

Explore the interactive demo hosted on HuggingFace:

Below is a screenshot of the SlimFace Demo GUI:

Run Locally

To run the Gradio application locally at the default address localhost:7860, execute:

python apps/gradio_app.py

Installation

Step 1: Clone the Repository

To begin, clone the SlimFace repository to your local machine:

git clone https://github.com/danhtran2mind/SlimFace
cd SlimFace

Step 2: Install Dependencies

Install the required dependencies using the provided requirements file:

pip install -r requirements/requirements.txt

For specific use cases, alternative dependency configurations are available:

• Compatible Dependencies:

  pip install -r requirements/requirements_compatible.txt

• End-to-End Inference:

  pip install -r requirements/requirements_inference.txt

Troubleshooting OpenCV

If you encounter issues with OpenCV, ensure the following dependencies are installed:

sudo apt update
sudo apt install -y libglib2.0-0 libgl1-mesa-dev

Third-Party Dependencies

Set up third-party dependencies by running:

python scripts/setup_third_party.py

Usage

Dataset Preparation

Prepare your dataset by following the Data Processing Guide. For a quick setup, execute:

python scripts/process_dataset.py

Reference Data Setup

1. Place reference images in data/reference_data/images and ensure they are mapped to index_to_class_mapping.json.
2. Generate the reference dictionary with:

python scripts/create_reference_image_path.py

For custom paths, use:

python scripts/create_reference_image_path.py \
    --input <path_to_index_to_class_mapping.json> \
    --output <path_to_reference_image_data.json>

Training

1. Configure Accelerate for distributed training:

accelerate config default

2. Launch the training process:

accelerate launch src/slimface/training/accelerate_train.py

For detailed instructions, refer to the Training Documentation.

Training Hyperparameters

Default hyperparameters are optimized for performance and can be customized in src/slimface/training/accelerate_train.py. Refer to the Training Documentation for guidance.

Inference

Class Name Inference

To classify an image and retrieve its class name, run:

python src/slimface/inference/inference.py --input_path <path_to_image>

Class Name and Image Embedding Comparison

To perform class name inference and compare image embeddings, use:

python src/slimface/inference/end2end_inference.py \
    --unknown_image_path tests/test_images/dont_know.jpg \
    --similarity_threshold 0.3

Additional Arguments

For more details and available options, refer to the Inference Documentation.

Metrics

Model Evaluation Results: Table summarizing train/validation loss and accuracy for four models. For details you can see at Models Metric.

Environment

SlimFace requires the following environment:

• Python: 3.10 or higher
• Key Libraries: Refer to Requirements Compatible for compatible dependencies.

More Knowledge

For additional information on models and pre-trained weights, please refer to the following resources:

The Documentation includes the torchvision.models subpackage, which offers pre-trained models for various image tasks. It provides metrics like Acc@1, Acc@5, Params, and GFLOPS for model evaluation.

Contact

For questions, issues, or support, please use the GitHub Issues tab or contact the maintainer via the HuggingFace Community.