Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

Face Recognition (train/test/deploy)(tensorflow/tflite/keras/edgetpu)

Project description


Face recognition python library(tensorflow, opencv).

Usage (console)

try facelib --help to discover more


foo@bar:~$ python3 -m facelib train train_images/ lotr
Current pipeline: ssd_int8_cpu, mobilenetv2_fp32_cpu, densenet_fp32_cpu
Classifier named `lotr` succesfully trained and saved.
  • Folder structure:
Image Name Image
train_images/seanastin/0.jpg seanastin


foo@bar:~$ python3 -m facelib predict test_images/ -clf lotr -c -p
Current pipeline: ssd_int8_cpu, mobilenetv2_fp32_cpu, densenet_fp32_cpu
├───10 faces detected
├───['billy_boyd', 'sean_astin', 'viggo_mortensen', 'elijah_wood', 'liv_tyler', 'dominic_monaghan', 'sean_bean', 'ian_mckellen', 'peter_jackson', 'orlando_bloom']
├───5 faces detected
├───['dominic_monaghan', 'billy_boyd', 'elijah_wood', 'sean_astin', 'peter_jackson']
├───6 faces detected
├───['orlando_bloom', 'dominic_monaghan', 'john_rhys_davies', 'sean_astin', 'elijah_wood', 'billy_boyd']
├───5 faces detected
├───['dominic_monaghan', 'orlando_bloom', 'elijah_wood', 'liv_tyler', 'billy_boyd']
  • Folder structure:

  • Generated folders/files:

Image Name Image
test_images_facelib_cropped/billy_boyd/0_1.jpg billyboyd
test_images_facelib_cropped/liv_tyler/4_1.jpg livtyler
test_images_facelib_cropped/elijah_wood/3_1.jpg elijahwood
test_images_facelib_plotted/1.jpg 1

Usage (python)

from facelib import facerec
import cv2
# You can use face_detector, landmark_detector or feature_extractor individually using .predict method. e.g.(bboxes = facedetector.predict(img))
face_detector = facerec.SSDFaceDetector()
landmark_detector = facerec.LandmarkDetector()
feature_extractor = facerec.FeatureExtractor()

pipeline = facerec.Pipeline(face_detector, landmark_detector, feature_extractor)
path_img = './path_to_some_image.jpg'
img = cv2.imread(path_img)
img = img[...,::-1] # cv2 returns bgr format but every method inside this package takes rgb format
bboxes, landmarks, features = pipeline.predict(img)
# Note that values returned (bboxes and landmarks) are in fraction.[0,1]


Pip installation

pip3 install facelib

TFLite runtime installation

To use facelib.facerec package use the following bash command to install tflite-runtime pip package.

python3 -m facelib --install-tflite

or you can install from

Dev package

Tensorflow is required for package. If you wish you can download facelib with tensorflow using the following command.

pip3 install facelib[dev]



Feature extraction models are trained using insightfaces MS1M-Arcface.
Landmark Detection models are trained using VggFace2.


Image Augmentation

  • <input type="checkbox" checked="" disabled="" /> Random augmentation for landmark detection


  • <input type="checkbox" checked="" disabled="" /> DisturbLabel

Face Alignment

  • <input type="checkbox" checked="" disabled="" /> Insightface
  • <input type="checkbox" checked="" disabled="" /> GoldenRatio
  • <input type="checkbox" checked="" disabled="" /> Custom Implementations


  • <input type="checkbox" disabled="" /> Widerface to TFRecords converter
  • <input type="checkbox" disabled="" /> VggFace2 to TFRecords converter
  • <input type="checkbox" disabled="" /> COFW to TFRecords converter

Loss Functions

Feature Extraction

  • <input type="checkbox" checked="" disabled="" /> ArcFace
  • <input type="checkbox" checked="" disabled="" /> CombinedMargin
  • <input type="checkbox" checked="" disabled="" /> SphereFace(A-Softmax)
  • <input type="checkbox" disabled="" /> Center
  • <input type="checkbox" checked="" disabled="" /> CosFace

Landmark Detection

  • <input type="checkbox" checked="" disabled="" /> EuclideanDistance(with different norms)

Pretrained Models

Face Detection

  • <input type="checkbox" checked="" disabled="" /> SSD
  • <input type="checkbox" disabled="" /> MTCNN

Face Feature Extraction

  • <input type="checkbox" checked="" disabled="" /> MobileFaceNet
  • <input type="checkbox" checked="" disabled="" /> SqueezeNet
  • <input type="checkbox" checked="" disabled="" /> MobileNet
  • <input type="checkbox" checked="" disabled="" /> MobileNetV2
  • <input type="checkbox" checked="" disabled="" /> DenseNet
  • <input type="checkbox" checked="" disabled="" /> NasNetMobile


  • <input type="checkbox" disabled="" /> Feature extraction model training
  • <input type="checkbox" disabled="" /> Landmark detection model training
  • <input type="checkbox" disabled="" /> Chokepoint test on pipeline

Facial Landmark Detection

  • <input type="checkbox" disabled="" /> SqueezeNet
  • <input type="checkbox" checked="" disabled="" /> MobileNet
  • <input type="checkbox" checked="" disabled="" /> MobileNetV2
  • <input type="checkbox" disabled="" /> DenseNet


WiderFace Yang, Shuo, Ping Luo, Chen Change Loy, and Xiaoou Tang. “WIDER FACE: A Face Detection Benchmark.” ArXiv:1511.06523 [Cs], November 20, 2015.
ArcFace Deng, Jiankang, Jia Guo, Niannan Xue, and Stefanos Zafeiriou. “ArcFace: Additive Angular Margin Loss for Deep Face Recognition.” ArXiv:1801.07698 [Cs], January 23, 2018.
MobileFaceNet Chen, Sheng, Yang Liu, Xiang Gao, and Zhen Han. “MobileFaceNets: Efficient CNNs for Accurate Real-Time Face Verification on Mobile Devices.” CoRR abs/1804.07573 (2018).
VggFace2 Cao, Qiong, Li Shen, Weidi Xie, Omkar M. Parkhi, and Andrew Zisserman. “VGGFace2: A Dataset for Recognising Faces across Pose and Age.” ArXiv:1710.08092 [Cs], October 23, 2017.
DenseNet G. Huang, Z. Liu, L. van der Maaten, and K. Q. Weinberger, “Densely Connected Convolutional Networks,” arXiv:1608.06993 [cs], Jan. 2018.
GoldenRatio (face alignment) M. Hassaballah, K. Murakami, and S. Ido, “Face detection evaluation: a new approach based on the golden ratio,” SIViP, vol. 7, no. 2, pp. 307–316, Mar. 2013.
SqueezeNet F. N. Iandola, S. Han, M. W. Moskewicz, K. Ashraf, W. J. Dally, and K. Keutzer, “SqueezeNet: AlexNet-level accuracy with 50x fewer parameters and <0.5MB model size,” arXiv:1602.07360 [cs], Feb. 2016.
MobileNet A. G. Howard et al., “MobileNets: Efficient Convolutional Neural Networks for Mobile Vision Applications,” arXiv:1704.04861 [cs], Apr. 2017.
MobileNetV2 M. Sandler, A. Howard, M. Zhu, A. Zhmoginov, and L.-C. Chen, “MobileNetV2: Inverted Residuals and Linear Bottlenecks,” arXiv:1801.04381 [cs], Jan. 2018.
CosFace H. Wang et al., “CosFace: Large Margin Cosine Loss for Deep Face Recognition,” arXiv:1801.09414 [cs], Jan. 2018.
SphereFace W. Liu, Y. Wen, Z. Yu, M. Li, B. Raj, and L. Song, “SphereFace: Deep Hypersphere Embedding for Face Recognition,” arXiv:1704.08063 [cs], Apr. 2017.
Bottleneck Layer K. He, X. Zhang, S. Ren, and J. Sun, “Deep Residual Learning for Image Recognition,” arXiv:1512.03385 [cs], Dec. 2015.
MS-Celeb-1M Y. Guo, L. Zhang, Y. Hu, X. He, and J. Gao, “MS-Celeb-1M: A Dataset and Benchmark for Large-Scale Face Recognition,” arXiv:1607.08221 [cs], Jul. 2016.
DisturbLabel arXiv:1605.00055 [cs.CV]
Single Shot Detector [1]W. Liu et al., “SSD: Single Shot MultiBox Detector,” arXiv:1512.02325 [cs], Dec. 2016.


Cascade Data
TFLite Python

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for facelib, version 1.2.1
Filename, size File type Python version Upload date Hashes
Filename, size facelib-1.2.1-py3-none-any.whl (29.6 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size facelib-1.2.1.tar.gz (22.1 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page