retina-face 0.0.3

RetinaFace: Deep Face Detection Framework in TensorFlow for Python

RetinaFace

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

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

from retina-face 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"])

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 licensed are under MIT license.

Licence

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