Home

Awesome

CVLFace: High-Performance Face Recognition All-in-One Toolkit

πŸ–ΌοΈ Introduction

CVLFace is a powerful and versatile toolkit for achieving state-of-the-art performance in face recognition. Whether you're a researcher exploring new algorithms or a developer building real-world applications, CVLFace empowers you with:

CVLFace is created by MSU CVLab to foster innovation, collaboration, and accessibility in the field of face recognition. It is built upon a foundation of cutting-edge research and technology, offering a user-friendly experience for both beginners and seasoned practitioners.

Visit our Documentation for more details: Documentation Website

πŸ’ͺ Features

πŸš€ High-Performance Training and Evaluation:

πŸ“¦ Pre-trained Models:

πŸ† State-of-the-Art Performance:

ArchLossDatasetLinkAVGLFWCPFLWCFPFPCALFWAGEDBIJBB@0.01IJBC@0.01TinyFace R1TinyFace R5
ViT KPRPE [1]AdaFace [2]WebFace12MπŸ€—93.1399.8295.6599.3095.9398.1096.5597.8276.1078.92
ViT KPRPE [1]AdaFace [2]WebFace4MπŸ€—92.7699.8395.4099.0196.0097.6795.5697.1375.7578.49
ViT [1]AdaFace [2]WebFace4MπŸ€—92.4899.8094.9798.9496.0397.4895.6097.1474.7977.58
IR101 [3]AdaFace [2]WebFace12MπŸ€—92.1399.8294.5799.2496.1298.0096.4697.7272.4274.81
IR101 [3]AdaFace [2]WebFace4MπŸ€—91.9899.8394.6399.2796.0597.9096.1097.4672.1374.49
IR101 [3]Arc-Face [3]WebFace4MπŸ€—91.7699.7894.3599.2196.0097.9595.8397.3071.0374.41
IR101 [3]AdaFace [2]MS1MV3πŸ€—90.9999.8393.9299.0996.0298.1895.8297.0567.9571.03
IR101 [3]AdaFace [2]MS1MV2πŸ€—90.9099.8093.5398.6196.1298.0595.5996.8168.1171.49
IR50 [3]AdaFace [2]MS1MV2πŸ€—89.9699.8592.8598.0996.0797.8594.8696.2064.9968.88
IR50 [3]AdaFace [2]WebFace4MπŸ€—91.4899.7894.1798.9995.9897.7895.4997.0170.2073.93
IR50 [3]AdaFace [2]CASIAπŸ€—77.4399.3790.0297.0493.4394.4046.0452.9759.4464.14
IR18 [3]AdaFace [2]WebFace4MπŸ€—89.5599.5892.2897.8095.5296.4892.7594.7966.0770.71
IR18 [3]AdaFace [2]VGG2πŸ€—88.1299.5391.7397.6493.9094.0790.0792.4064.6269.15
IR18 [3]AdaFace [2]CASIAπŸ€—72.4099.2287.0094.9392.6592.6830.3637.1056.2061.43

πŸ“± Useful Apps:

CVLFace includes several practical apps to demonstrate and utilize the capabilities of the toolkit in real-world scenarios. Currently, there are two main applications:

1. Face Alignment App

The Face Alignment App processes facial images to align them to a canonical position suitable for face recognition. This app automatically resizes the images to 112x112 pixels, optimizing them for consistent input to face recognition models.

<table align="center"> <tr> <td><img src="cvlface/apps/face_alignment/example/images/3.png" alt="Image 1"></td> <td><img src="cvlface/apps/face_alignment/example/aligned_images/3.png" alt="Image 1"></td> <td><img src="cvlface/apps/face_alignment/example/aligned_images/3_ldmks.png" alt="Image 2"></td> </tr> </table>

2. Face Verification App

The Face Verification App verifies the identity of a person by comparing their facial image with a reference image. This app uses a pre-trained face recognition model to calculate the similarity between the two images and determine if they belong to the same person.

<table align="center"> <tr> <td><img src="cvlface/apps/verification/example/visualization/0.png" alt="Image 1"></td> </tr> </table>

πŸ’» Easy Installation

1. Install dependencies

conda create -n cvlface python=3.10 pytorch=2.1.2 torchvision=0.16.2 torchaudio=2.1.2 pytorch-cuda=12.1 -c pytorch -c nvidia
git clone https://github.com/mk-minchul/CVLface.git
cd CVLface
pip install -r requirements.txt

2. Set up environment variables at CVLface/cvlface/.env

Modify the following environment variables in the .env file:

cd cvlface
vim .env # edit the following environ variables

"""(content to add to .env)
DATA_ROOT="YOUR_PATH_TO_DATA"
HF_TOKEN="YOUR_HUGGINGFACE_HF_TOKEN"
WANDB_TOKEN="YOUR_WANDB_TOKEN"
"""

3. Easy Downloading of Evaluation Toolkit (Optional)

Download Evaluation Toolkit for evaluating models during training or after training. Take a look at README_EVAL_TOOLKIT.md for details.

4. Easy Downloading of Pretrained models (Optional)

Take a look at README_MODELS.md for details. We offer more than 10 pre-trained models.

5. Easy Downloading of Training Datasets (Optional)

Take a look at README_TRAIN_DATA.md for details. Documented datasets include

πŸƒβ€β™€οΈ Usage

Quick Test

Quickly test if the installation is successful by running the following command: (No training dataset needed for the mock run, only needs the eval toolkit)

# mock run to test the installation and evaluation toolkit
cd cvlface/research/recognition/code/run_v1
python train.py trainers.prefix=test_run \
      trainers.num_gpu=1 \
      trainers.batch_size=32 \
      trainers.limit_num_batch=128 \
      trainers.gradient_acc=1 \
      trainers.num_workers=8 \
      trainers.precision='32-true' \
      trainers.float32_matmul_precision='high' \
      dataset=configs/synthetic.yaml \
      data_augs=configs/basic_v1.yaml \
      models=iresnet/configs/v1_ir50.yaml \
      pipelines=configs/train_model_cls.yaml \
      evaluations=configs/base.yaml \
      classifiers=configs/fc.yaml \
      optims=configs/step_sgd.yaml \
      losses=configs/cosface.yaml

Multi-GPU Training

# mock run to test the installation and evaluation toolkit
cd cvlface/research/recognition/code/run_v1
LIGHTING_TESTING=1 CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6 lightning run model \
    --strategy=ddp \
    --devices=7 \
    --precision="32-true" \
      train.py trainers.prefix=ir101_WF4M_adaface \
      trainers.num_gpu=7 \
      trainers.batch_size=256 \
      trainers.gradient_acc=1 \
      trainers.num_workers=8 \
      trainers.precision='32-true' \
      trainers.float32_matmul_precision='high' \
      dataset=configs/webface4m.yaml \
      data_augs=configs/basic_v1.yaml \
      models=iresnet/configs/v1_ir101.yaml \
      pipelines=configs/train_model_cls.yaml \
      evaluations=configs/full.yaml \
      classifiers=configs/fc.yaml \
      optims=configs/step_sgd.yaml \
      losses=configs/adaface.yaml \
      trainers.skip_final_eval=False

More examples can be found at cvlface/research/recognition/code/run_v1/scripts/examples

🀝 Contributing

We encourage contributions to CVLFace, including:

πŸš€ Acknowledgments

We would like to express our gratitude for their contributions and support:

Join us in pushing the boundaries of face recognition technology with CVLFace!