retina-face


Nameretina-face JSON
Version 0.0.12 PyPI version JSON
download
home_pagehttps://github.com/serengil/retinaface
SummaryRetinaFace: Deep Face Detection Framework in TensorFlow for Python
upload_time2022-05-22 20:12:33
maintainer
docs_urlNone
authorSefik Ilkin Serengil
requires_python>=3.5.5
license
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # RetinaFace

[![Downloads](https://pepy.tech/badge/retina-face)](https://pepy.tech/project/retina-face)
[![Stars](https://img.shields.io/github/stars/serengil/retinaface?color=yellow)](https://github.com/serengil/retinaface)
[![License](http://img.shields.io/:license-MIT-green.svg?style=flat)](https://github.com/serengil/retinaface/blob/master/LICENSE)
[![Support me on Patreon](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fshieldsio-patreon.vercel.app%2Fapi%3Fusername%3Dserengil%26type%3Dpatrons&style=flat)](https://www.patreon.com/serengil?repo=retinaface)
[![Twitter](https://img.shields.io/twitter/follow/serengil?color=blue&logo=twitter&style=flat)](https://twitter.com/serengil)
[![DOI](http://img.shields.io/:DOI-10.1109/ICEET53442.2021.9659697-blue.svg?style=flat)](https://doi.org/10.1109/ICEET53442.2021.9659697)

RetinaFace is a deep learning based cutting-edge facial detector for Python coming with facial landmarks. Its detection performance is amazing even in the crowd as shown in the following illustration.

RetinaFace is the face detection module of [insightface](https://github.com/deepinsight/insightface) project. The original implementation is mainly based on mxnet. Then, its tensorflow based [re-implementation](https://github.com/StanislasBertrand/RetinaFace-tf2) is published by [Stanislas Bertrand](https://github.com/StanislasBertrand). So, 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.

<p align="center"><img src="https://raw.githubusercontent.com/serengil/retinaface/master/tests/outputs/img3.jpg" width="90%" height="90%"></p>

## Installation

The easiest way to install retinaface is to download it from [PyPI](https://pypi.org/project/retina-face/). It's going to install the library itself and its prerequisites as well.

```
pip install retina-face
```

Then, you will be able to import the library and use its functionalities.

```python
from retinaface import RetinaFace
```

**Face Detection** - [`Demo`](https://youtu.be/Wm1DucuQk70)

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

```python
resp = RetinaFace.detect_faces("img1.jpg")
```

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

```json
{
    "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** - [`Tutorial`](https://sefiks.com/2020/02/23/face-alignment-for-face-recognition-in-python-within-opencv/), [`Demo`](https://youtu.be/WA9i68g4meI)

A modern face recognition [pipeline](https://sefiks.com/2020/05/01/a-gentle-introduction-to-face-recognition-in-deep-learning/) consists of 4 common stages: detect, [align](https://sefiks.com/2020/02/23/face-alignment-for-face-recognition-in-python-within-opencv/), [normalize](https://sefiks.com/2020/11/20/facial-landmarks-for-face-recognition-with-dlib/), [represent](https://sefiks.com/2020/12/14/deep-face-recognition-with-arcface-in-keras-and-python/) and [verify](https://sefiks.com/2020/05/22/fine-tuning-the-threshold-in-face-recognition/). 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 extracting faces function.

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

<p align="center"><img src="https://raw.githubusercontent.com/serengil/retinaface/master/tests/outputs/alignment-procedure.png" width="80%" height="80%"></p>

**Face Recognition** - [`Demo`](https://youtu.be/WnUVYQP4h44)

Notice that face recognition module of insightface project is [ArcFace](https://sefiks.com/2020/12/14/deep-face-recognition-with-arcface-in-keras-and-python/), and face detection module is RetinaFace. ArcFace and RetinaFace pair is wrapped in [deepface](https://github.com/serengil/deepface) library for Python. Consider to use deepface if you need an end-to-end face recognition pipeline.

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

<p align="center"><img src="https://raw.githubusercontent.com/serengil/retinaface/master/tests/outputs/retinaface-arcface.png" width="100%" height="100%"></p>

Notice that ArcFace got 99.40% accuracy on [LFW data set](https://sefiks.com/2020/08/27/labeled-faces-in-the-wild-for-face-recognition/) whereas human beings just have 97.53% confidence.

## Support

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

You can also support this work on [Patreon](https://www.patreon.com/serengil?repo=retinaface)

<a href="https://www.patreon.com/serengil?repo=retinaface">
<img src="https://raw.githubusercontent.com/serengil/retinaface/master/icons/patreon.png" width="30%" height="30%">
</a>

## Acknowledgements

This work is mainly based on the [insightface](https://github.com/deepinsight/insightface) project and [retinaface](https://arxiv.org/pdf/1905.00641.pdf) paper; and it is heavily inspired from the re-implementation of [retinaface-tf2](https://github.com/StanislasBertrand/RetinaFace-tf2) by [Stanislas Bertrand](https://github.com/StanislasBertrand). Finally, Bertrand's [implemenation](https://github.com/StanislasBertrand/RetinaFace-tf2/blob/master/rcnn/cython/cpu_nms.pyx) uses [Fast R-CNN](https://arxiv.org/abs/1504.08083) written by [Ross Girshick](https://github.com/rbgirshick/fast-rcnn) in the background. All of those reference studies are licensed under MIT license.

## Citation

If you are using RetinaFace in your research, please consider to cite its [original research paper](https://arxiv.org/abs/1905.00641). Besides, if you are using this re-implementation of retinaface, please consider to cite the following research paper as well. Here is an example of BibTeX entry:

```BibTeX
@inproceedings{serengil2021lightface,
  title        = {HyperExtended LightFace: A Facial Attribute Analysis Framework},
  author       = {Serengil, Sefik Ilkin and Ozpinar, Alper},
  booktitle    = {2021 International Conference on Engineering and Emerging Technologies (ICEET)},
  pages        = {1-4},
  year         = {2021},
  doi          = {10.1109/ICEET53442.2021.9659697},
  url          = {https://doi.org/10.1109/ICEET53442.2021.9659697},
  organization = {IEEE}
}
```

Finally, if you use this RetinaFace re-implementation in your GitHub projects, please add retina-face dependency in the requirements.txt.

## Licence

This project is licensed under the MIT License - see [`LICENSE`](https://github.com/serengil/retinaface/blob/master/LICENSE) for more details.



            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/serengil/retinaface",
    "name": "retina-face",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.5.5",
    "maintainer_email": "",
    "keywords": "",
    "author": "Sefik Ilkin Serengil",
    "author_email": "serengil@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/8d/12/41c77584e8285be06e9ce5d918793e65711b08bcbec3c610ce4f70f45398/retina-face-0.0.12.tar.gz",
    "platform": null,
    "description": "# RetinaFace\n\n[![Downloads](https://pepy.tech/badge/retina-face)](https://pepy.tech/project/retina-face)\n[![Stars](https://img.shields.io/github/stars/serengil/retinaface?color=yellow)](https://github.com/serengil/retinaface)\n[![License](http://img.shields.io/:license-MIT-green.svg?style=flat)](https://github.com/serengil/retinaface/blob/master/LICENSE)\n[![Support me on Patreon](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fshieldsio-patreon.vercel.app%2Fapi%3Fusername%3Dserengil%26type%3Dpatrons&style=flat)](https://www.patreon.com/serengil?repo=retinaface)\n[![Twitter](https://img.shields.io/twitter/follow/serengil?color=blue&logo=twitter&style=flat)](https://twitter.com/serengil)\n[![DOI](http://img.shields.io/:DOI-10.1109/ICEET53442.2021.9659697-blue.svg?style=flat)](https://doi.org/10.1109/ICEET53442.2021.9659697)\n\nRetinaFace is a deep learning based cutting-edge facial detector for Python coming with facial landmarks. Its detection performance is amazing even in the crowd as shown in the following illustration.\n\nRetinaFace is the face detection module of [insightface](https://github.com/deepinsight/insightface) project. The original implementation is mainly based on mxnet. Then, its tensorflow based [re-implementation](https://github.com/StanislasBertrand/RetinaFace-tf2) is published by [Stanislas Bertrand](https://github.com/StanislasBertrand). So, 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.\n\n<p align=\"center\"><img src=\"https://raw.githubusercontent.com/serengil/retinaface/master/tests/outputs/img3.jpg\" width=\"90%\" height=\"90%\"></p>\n\n## Installation\n\nThe easiest way to install retinaface is to download it from [PyPI](https://pypi.org/project/retina-face/). It's going to install the library itself and its prerequisites as well.\n\n```\npip install retina-face\n```\n\nThen, you will be able to import the library and use its functionalities.\n\n```python\nfrom retinaface import RetinaFace\n```\n\n**Face Detection** - [`Demo`](https://youtu.be/Wm1DucuQk70)\n\nRetinaFace offers a face detection function. It expects an exact path of an image as input.\n\n```python\nresp = RetinaFace.detect_faces(\"img1.jpg\")\n```\n\nThen, it will return the facial area coordinates and some landmarks (eyes, nose and mouth) with a confidence score.\n\n```json\n{\n    \"face_1\": {\n        \"score\": 0.9993440508842468,\n        \"facial_area\": [155, 81, 434, 443],\n        \"landmarks\": {\n          \"right_eye\": [257.82974, 209.64787],\n          \"left_eye\": [374.93427, 251.78687],\n          \"nose\": [303.4773, 299.91144],\n          \"mouth_right\": [228.37329, 338.73193],\n          \"mouth_left\": [320.21982, 374.58798]\n        }\n  }\n}\n```\n\n**Alignment** - [`Tutorial`](https://sefiks.com/2020/02/23/face-alignment-for-face-recognition-in-python-within-opencv/), [`Demo`](https://youtu.be/WA9i68g4meI)\n\nA modern face recognition [pipeline](https://sefiks.com/2020/05/01/a-gentle-introduction-to-face-recognition-in-deep-learning/) consists of 4 common stages: detect, [align](https://sefiks.com/2020/02/23/face-alignment-for-face-recognition-in-python-within-opencv/), [normalize](https://sefiks.com/2020/11/20/facial-landmarks-for-face-recognition-with-dlib/), [represent](https://sefiks.com/2020/12/14/deep-face-recognition-with-arcface-in-keras-and-python/) and [verify](https://sefiks.com/2020/05/22/fine-tuning-the-threshold-in-face-recognition/). 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 extracting faces function.\n\n```python\nimport matplotlib.pyplot as plt\nfaces = RetinaFace.extract_faces(img_path = \"img.jpg\", align = True)\nfor face in faces:\n  plt.imshow(face)\n  plt.show()\n```\n\n<p align=\"center\"><img src=\"https://raw.githubusercontent.com/serengil/retinaface/master/tests/outputs/alignment-procedure.png\" width=\"80%\" height=\"80%\"></p>\n\n**Face Recognition** - [`Demo`](https://youtu.be/WnUVYQP4h44)\n\nNotice that face recognition module of insightface project is [ArcFace](https://sefiks.com/2020/12/14/deep-face-recognition-with-arcface-in-keras-and-python/), and face detection module is RetinaFace. ArcFace and RetinaFace pair is wrapped in [deepface](https://github.com/serengil/deepface) library for Python. Consider to use deepface if you need an end-to-end face recognition pipeline.\n\n```python\n#!pip install deepface\nfrom deepface import DeepFace\nobj = DeepFace.verify(\"img1.jpg\", \"img2.jpg\"\n          , model_name = 'ArcFace', detector_backend = 'retinaface')\nprint(obj[\"verified\"])\n```\n\n<p align=\"center\"><img src=\"https://raw.githubusercontent.com/serengil/retinaface/master/tests/outputs/retinaface-arcface.png\" width=\"100%\" height=\"100%\"></p>\n\nNotice that ArcFace got 99.40% accuracy on [LFW data set](https://sefiks.com/2020/08/27/labeled-faces-in-the-wild-for-face-recognition/) whereas human beings just have 97.53% confidence.\n\n## Support\n\nThere are many ways to support a project. Starring\u2b50\ufe0f the repo is just one \ud83d\ude4f\n\nYou can also support this work on [Patreon](https://www.patreon.com/serengil?repo=retinaface)\n\n<a href=\"https://www.patreon.com/serengil?repo=retinaface\">\n<img src=\"https://raw.githubusercontent.com/serengil/retinaface/master/icons/patreon.png\" width=\"30%\" height=\"30%\">\n</a>\n\n## Acknowledgements\n\nThis work is mainly based on the [insightface](https://github.com/deepinsight/insightface) project and [retinaface](https://arxiv.org/pdf/1905.00641.pdf) paper; and it is heavily inspired from the re-implementation of [retinaface-tf2](https://github.com/StanislasBertrand/RetinaFace-tf2) by [Stanislas Bertrand](https://github.com/StanislasBertrand). Finally, Bertrand's [implemenation](https://github.com/StanislasBertrand/RetinaFace-tf2/blob/master/rcnn/cython/cpu_nms.pyx) uses [Fast R-CNN](https://arxiv.org/abs/1504.08083) written by [Ross Girshick](https://github.com/rbgirshick/fast-rcnn) in the background. All of those reference studies are licensed under MIT license.\n\n## Citation\n\nIf you are using RetinaFace in your research, please consider to cite its [original research paper](https://arxiv.org/abs/1905.00641). Besides, if you are using this re-implementation of retinaface, please consider to cite the following research paper as well. Here is an example of BibTeX entry:\n\n```BibTeX\n@inproceedings{serengil2021lightface,\n  title        = {HyperExtended LightFace: A Facial Attribute Analysis Framework},\n  author       = {Serengil, Sefik Ilkin and Ozpinar, Alper},\n  booktitle    = {2021 International Conference on Engineering and Emerging Technologies (ICEET)},\n  pages        = {1-4},\n  year         = {2021},\n  doi          = {10.1109/ICEET53442.2021.9659697},\n  url          = {https://doi.org/10.1109/ICEET53442.2021.9659697},\n  organization = {IEEE}\n}\n```\n\nFinally, if you use this RetinaFace re-implementation in your GitHub projects, please add retina-face dependency in the requirements.txt.\n\n## Licence\n\nThis project is licensed under the MIT License - see [`LICENSE`](https://github.com/serengil/retinaface/blob/master/LICENSE) for more details.\n\n\n",
    "bugtrack_url": null,
    "license": "",
    "summary": "RetinaFace: Deep Face Detection Framework in TensorFlow for Python",
    "version": "0.0.12",
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "06d4806d6982165a25368d5b1aa1a914",
                "sha256": "af05a23389ec3d817bddd333ea5c8fe05ec47f43ba807e16597d0daa5b7b93c6"
            },
            "downloads": -1,
            "filename": "retina_face-0.0.12-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "06d4806d6982165a25368d5b1aa1a914",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.5.5",
            "size": 15709,
            "upload_time": "2022-05-22T20:12:31",
            "upload_time_iso_8601": "2022-05-22T20:12:31.579894Z",
            "url": "https://files.pythonhosted.org/packages/9f/ed/2e5640fe4f99f3e0d91869cff04513f96f7f0e25253179dd2e0a8c4c8cce/retina_face-0.0.12-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "8ab37313e0478f0207a1490a74c5c162",
                "sha256": "9cd335460390960671343e021b697d88b1623e9ffb0c398573d486a64e3054d2"
            },
            "downloads": -1,
            "filename": "retina-face-0.0.12.tar.gz",
            "has_sig": false,
            "md5_digest": "8ab37313e0478f0207a1490a74c5c162",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.5.5",
            "size": 14679,
            "upload_time": "2022-05-22T20:12:33",
            "upload_time_iso_8601": "2022-05-22T20:12:33.530863Z",
            "url": "https://files.pythonhosted.org/packages/8d/12/41c77584e8285be06e9ce5d918793e65711b08bcbec3c610ce4f70f45398/retina-face-0.0.12.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2022-05-22 20:12:33",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "github_user": "serengil",
    "github_project": "retinaface",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "retina-face"
}
        
Elapsed time: 0.37490s