A hyperspherical face recognition library based on PyTorch
OpenSphere is a hyperspherical face recognition library based on PyTorch. Check out the project homepage.
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 -
SphereFace: Deep Hypersphere Embedding for Face Recognition, CVPR 2017
(SphereFace+) Learning towards Minimum Hyperspherical Energy, NeurIPS 2018
SphereFace2: Binary Classification is All You Need for Deep Face Recognition, ICLR 2022
SphereFace Revived: Unifying Hyperspherical Face Recognition, TPAMI 2022
Implemented Loss Functions (folder)
Implemented Network Architectures (folder)
Available Datasets
TODO: more examplar config files for training, 2D/3D feature visualization tools
We welcome submissions of your loss functions or network architectures to OpenSphere!
Clone the OpenSphere repository. We'll call the directory that you cloned OpenSphere as $OPENSPHERE_ROOT
.
git clone https://github.com/ydwen/opensphere.git
Construct virtual environment in Anaconda:
conda env create -f environment.yml
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.
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.
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
.
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.
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 |
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:
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}
}
Questions can also be left as issues in the repository. We will be happy to answer them.