/opensphere

A hyperspherical face recognition library based on PyTorch

Primary LanguageJupyter NotebookMIT LicenseMIT

   

arxiv-link project-page made-with-pytorch License: MIT

OpenSphere is a hyperspherical face recognition library based on PyTorch. Check out the project homepage.

 

Introduction

OpenSphere provides a consistent and unified training and evaluation framework for hyperspherical face recognition research. The framework decouples the loss function from the other varying components such as network architecture, optimizer, and data augmentation. It can fairly compare different loss functions in hyperspherical face recognition on popular benchmarks, serving as a transparent platform to reproduce published results.

Table of Contents: - Key features - Setup - Get started - Pretrained models - Reproducible results - Citation -

Supported Projects

Update

  • 2022.4.28: added SphereFace-R, Glint360K, and more pretrained models.
  • 2022.4.22: added SphereFace+, MS1M, and config files on MS1M.
  • 2022.4.12: added SFNet (with BN) and IResNet.
  • 2022.4.9: added the download script for some datasets.
  • 2022.4.1: initial commit.

Key Features

Setup

  1. Clone the OpenSphere repository. We'll call the directory that you cloned OpenSphere as $OPENSPHERE_ROOT.

    git clone https://github.com/ydwen/opensphere.git

  2. Construct virtual environment in Anaconda:

    conda env create -f environment.yml

Get started

In this part, we assume you are in the directory $OPENSPHERE_ROOT. After successfully completing the Setup, you are ready to run all the following experiments.

  1. Download and process the datasets

  • Download the training set (VGGFace2), validation set (LFW, Age-DB, CA-LFW, CP-LFW), and test set (IJB-B and IJB-C) and place them in data/train, data/val amd data/test, respectively.

  • For convenience, we provide a script to automatically download the data. Simply run

    bash scripts/dataset_setup.sh

  • If you need the MS1M training set, please run the additional commend:

    bash scripts/dataset_setup_ms1m.sh

  • To download other datasets (e.g., WebFace or Glint360K), see the scripts folder and find what you need.

  1. Train a model (see the training config file for the detailed setup)

    We give a few examples for training on different datasets with different backbone architectures:

  • To train SphereFace2 with SFNet-20 on VGGFace2, run the following commend (with 2 GPUs):

    CUDA_VISIBLE_DEVICES=0,1 python train.py --config config/train/vggface2_sfnet20_sphereface2.yml

  • To train SphereFace with SFNet-20 on VGGFace2, run the following commend (with 2 GPUs):

    CUDA_VISIBLE_DEVICES=0,1 python train.py --config config/train/vggface2_sfnet20_sphereface.yml

  • To train SphereFace-R (v2,HFN) with SFNet-20 on VGGFace2, run the following commend (with 2 GPUs):

    CUDA_VISIBLE_DEVICES=0,1 python train.py --config config/train/vggface2_sfnet20_spherefacer.yml

  • To train SphereFace with SFNet-64 (with BN) on MS1M, run the following commend (with 4 GPUs):

    CUDA_VISIBLE_DEVICES=0,1,2,3 python train.py --config config/train/ms1m_sfnet64bn_sphereface.yml

  • To train SphereFace with IResNet-100 on MS1M, run the following commend (with 4 GPUs):

    CUDA_VISIBLE_DEVICES=0,1,2,3 python train.py --config config/train/ms1m_iresnet100_sphereface.yml

  • We provide many config files for training, see this folder for details.

  • After finishing training a model, you will see a project folder under $OPENSPHERE_ROOT. The trained model is saved in the folder named by the job starting time, eg, 20220422_031705 for 03:17:05 on 2022-04-22.

  • Our framework also re-implements some other popular hyperspherical face recognition methods such as ArcFace, AM-Softmax (CosFace) and CocoLoss (NormFace). Please check out the folder model/head and some examplar config files in the folder config/papers/SphereFace2/sec31.

  1. Test a model (see the testing config file for detailed setup)

  • To test on the combined validation dataset, simply run

    CUDA_VISIBLE_DEVICES=0,1 python test.py --config config/test/combined.yml --proj_dir project/##YourFolder##

  • To test on both IJB-B and IJB-C, simply run

    CUDA_VISIBLE_DEVICES=0,1 python test.py --config config/test/ijb.yml --proj_dir project/##YourFolder##

  • To test on IJB-B, simply run

    CUDA_VISIBLE_DEVICES=0,1 python test.py --config config/test/ijbb.yml --proj_dir project/##YourFolder##

  • To test on IJB-C, simply run

    CUDA_VISIBLE_DEVICES=0,1 python test.py --config config/test/ijbc.yml --proj_dir project/##YourFolder##

For more information about how to use training and testing config files, please see here.

Results and pretrained models

Loss Architecture Dataset Config & Training Log & Pretrained Model
SphereFace SFNet-20 (w/o BN) VGGFace2 Google Drive
SphereFace+ SFNet-20 (w/o BN) VGGFace2 Google Drive
SphereFace-R (HFN,v2) SFNet-20 (w/o BN) VGGFace2 Google Drive
SphereFace-R (SFN,v2) SFNet-20 (w/o BN) VGGFace2 To be added
SphereFace2 SFNet-20 (w/o BN) VGGFace2 Google Drive
SphereFace SFNet-64 (w/ BN) MS1M Google Drive
SphereFace+ SFNet-64 (w/ BN) MS1M Google Drive
SphereFace-R (HFN,v2) SFNet-64 (w/ BN) MS1M To be added
SphereFace2 SFNet-64 (w/ BN) MS1M To be added
SphereFace IResNet-100 MS1M Google Drive
SphereFace+ IResNet-100 MS1M Google Drive
SphereFace-R (HFN,v2) IResNet-100 MS1M Google Drive
SphereFace2 IResNet-100 MS1M To be added
SphereFace SFNet-64 (w/ BN) Glint360K To be added
SphereFace+ SFNet-64 (w/ BN) Glint360K To be added
SphereFace-R (HFN,v2) SFNet-64 (w/ BN) Glint360K To be added
SphereFace2 SFNet-64 (w/ BN) Glint360K To be added
SphereFace IResNet-100 Glint360K To be added
SphereFace+ IResNet-100 Glint360K To be added
SphereFace-R (HFN,v2) IResNet-100 Glint360K To be added
SphereFace2 IResNet-100 Glint360K To be added

Reproduce published results

We create an additional folder config/papers that is used to provide detailed config files and reproduce results in published papers. Currently we provide config files for the following papers:

  • SphereFace2: Binary Classification is All You Need for Deep Face Recognition, ICLR 2022

Citation

If you find OpenSphere useful in your research, please consider to cite:

For SphereFace:

@article{Liu2022SphereFaceR,
  title={SphereFace Revived: Unifying Hyperspherical Face Recognition},
  author={Liu, Weiyang and Wen, Yandong and Raj, Bhiksha and Singh, Rita and Weller, Adrian},
  journal = {IEEE Transactions on Pattern Analysis and Machine Intelligence},
  year={2022}
}
  
@InProceedings{Liu2017SphereFace,
  title = {SphereFace: Deep Hypersphere Embedding for Face Recognition},
  author = {Liu, Weiyang and Wen, Yandong and Yu, Zhiding and Li, Ming and Raj, Bhiksha and Song, Le},
  booktitle = {CVPR},
  year = {2017}
}

@inproceedings{Liu2016lsoftmax,
  title={Large-Margin Softmax Loss for Convolutional Neural Networks},
  author={Liu, Weiyang and Wen, Yandong and Yu, Zhiding and Yang, Meng},
  booktitle={ICML},
  year={2016}
}

For SphereFace+:

@InProceedings{Liu2018MHE,
  title={Learning towards Minimum Hyperspherical Energy},
  author={Liu, Weiyang and Lin, Rongmei and Liu, Zhen and Liu, Lixin and Yu, Zhiding and Dai, Bo and Song, Le},
  booktitle={NeurIPS},
  year={2018}
}

For SphereFace2:

@InProceedings{wen2021sphereface2,
  title = {SphereFace2: Binary Classification is All You Need for Deep Face Recognition},
  author = {Wen, Yandong and Liu, Weiyang and Weller, Adrian and Raj, Bhiksha and Singh, Rita},
  booktitle = {ICLR},
  year = {2022}
}

Contact

Yandong Wen and Weiyang Liu

Questions can also be left as issues in the repository. We will be happy to answer them.