stjordanis / retinaface

RetinaFace: Deep Face Detection Library in TensorFlow for Python

RetinaFace

RetinaFace is a deep learning based cutting-edge facial detector for Python coming with facial landmarks.

RetinaFace is the face detection module of insightface project. The original implementation is mainly based on mxnet. Then, its tensorflow based re-implementation is published by Stanislas Bertrand.

This repo is heavily inspired from the study of Stanislas Bertrand. Its source code is simplified and it is transformed to pip compatible but the main structure of the reference model and its pre-trained weights are same.

Installation

The easiest way to install retinaface is to download it from pypi.

pip install retina-face

Face Detection - Demo

RetinaFace offers a face detection function. It expects an exact path of an image as input.

from retinaface import RetinaFace
resp = RetinaFace.detect_faces("img1.jpg")

Then it returns the facial area coordinates and some landmarks (eyes, nose and mouth) with a confidence score.

{
    "face_1": {
        "score": 0.9993440508842468,
        "facial_area": [155, 81, 434, 443],
        "landmarks": {
          "right_eye": [257.82974, 209.64787],
          "left_eye": [374.93427, 251.78687],
          "nose": [303.4773, 299.91144],
          "mouth_right": [228.37329, 338.73193],
          "mouth_left": [320.21982, 374.58798]
        }
  }
}

Alignment

A modern face recognition pipeline consists of 4 common stages: detect, align, represent and verify. Experiments show that alignment increases the face recognition accuracy almost 1%. Here, retinaface can find the facial landmarks including eye coordinates. In this way, it can apply alignment to detected faces with its extract faces function.

import matplotlib.pyplot as plt
faces = RetinaFace.extract_faces(img_path = "img.jpg", align = True)
for face in faces:
  plt.imshow(face)
  plt.show()

Face Recognition - Demo

Notice that face recognition module of insightface project is ArcFace, and face detection module is RetinaFace. ArcFace and RetinaFace pair is wrapped in deepface framework. Consider to use deepface if you need an end-to-end face recognition pipeline.

#!pip install deepface
from deepface import DeepFace
obj = DeepFace.verify("img1.jpg", "img2.jpg"
          , model_name = 'ArcFace', detector_backend = 'retinaface')
print(obj["verified"])

Notice that ArcFace got 99.40% accuracy on LFW data set whereas human beings just got 97.53%.

FAQ and troubleshooting

Pre-trained weights of the retinaface model is going to be downloaded from Google Drive once. Download limit of my Google Drive account might be exceeded sometimes. In this case, you will have an exception like "too many users have viewed or downloaded this file recently. Please try accessing the file again later". Still, you can access the pre-trained weights on Google Drive. Please, download it here and copy to the HOME/.deepface/weights folder manually.

You can find out your HOME_FOLDER with python as shown below.

from pathlib import Path
home = str(Path.home())
print("HOME_FOLDER is ",home)

Support

There are many ways to support a project. Starring⭐️ the repo is just one🙏

Acknowledgements

This work is mainly based on the insightface project and retinaface paper; and it is heavily inspired from the re-implementation of retinaface-tf2 by Stanislas Bertrand. Finally, Bertrand's implemenation uses Fast R-CNN written by Ross Girshick in the background. All of those reference studies are licensed under MIT license.

Licence

This project is licensed under the MIT License - see LICENSE for more details.