# Face Recognition
Detect facial landmarks from Python using the world's most accurate face alignment network, capable of detecting points in both 2D and 3D coordinates.
Build using [FAN](https://www.adrianbulat.com)'s state-of-the-art deep learning based face alignment method.
<p align="center"><img src="docs/images/face-alignment-adrian.gif" /></p>
**Note:** The lua version is available [here](https://github.com/1adrianb/2D-and-3D-face-alignment).
For numerical evaluations it is highly recommended to use the lua version which uses indentical models with the ones evaluated in the paper. More models will be added soon.
[](https://opensource.org/licenses/BSD-3-Clause) [](https://github.com/1adrianb/face-alignment/actions?query=workflow%3A%22Test+Face+alignmnet%22) [](https://anaconda.org/1adrianb/face_alignment)
[](https://pypi.org/project/face-alignment/)
## Features
#### Detect 2D facial landmarks in pictures
<p align='center'>
<img src='docs/images/2dlandmarks.png' title='3D-FAN-Full example' style='max-width:600px'></img>
</p>
```python
import face_alignment
from skimage import io
fa = face_alignment.FaceAlignment(face_alignment.LandmarksType.TWO_D, flip_input=False)
input = io.imread('../test/assets/aflw-test.jpg')
preds = fa.get_landmarks(input)
```
#### Detect 3D facial landmarks in pictures
<p align='center'>
<img src='https://www.adrianbulat.com/images/image-z-examples.png' title='3D-FAN-Full example' style='max-width:600px'></img>
</p>
```python
import face_alignment
from skimage import io
fa = face_alignment.FaceAlignment(face_alignment.LandmarksType.THREE_D, flip_input=False)
input = io.imread('../test/assets/aflw-test.jpg')
preds = fa.get_landmarks(input)
```
#### Process an entire directory in one go
```python
import face_alignment
from skimage import io
fa = face_alignment.FaceAlignment(face_alignment.LandmarksType.TWO_D, flip_input=False)
preds = fa.get_landmarks_from_directory('../test/assets/')
```
#### Detect the landmarks using a specific face detector.
By default the package will use the SFD face detector. However the users can alternatively use dlib, BlazeFace, or pre-existing ground truth bounding boxes.
```python
import face_alignment
# sfd for SFD, dlib for Dlib and folder for existing bounding boxes.
fa = face_alignment.FaceAlignment(face_alignment.LandmarksType.TWO_D, face_detector='sfd')
```
#### Running on CPU/GPU
In order to specify the device (GPU or CPU) on which the code will run one can explicitly pass the device flag:
```python
import torch
import face_alignment
# cuda for CUDA, mps for Apple M1/2 GPUs.
fa = face_alignment.FaceAlignment(face_alignment.LandmarksType.TWO_D, device='cpu')
# running using lower precision
fa = fa = face_alignment.FaceAlignment(face_alignment.LandmarksType.TWO_D, dtype=torch.bfloat16, device='cuda')
```
Please also see the ``examples`` folder
#### Supported face detectors
```python
# dlib (fast, may miss faces)
model = FaceAlignment(landmarks_type= LandmarksType.TWO_D, face_detector='dlib')
# SFD (likely best results, but slowest)
model = FaceAlignment(landmarks_type= LandmarksType.TWO_D, face_detector='sfd')
# Blazeface (front camera model)
model = FaceAlignment(landmarks_type= LandmarksType.TWO_D, face_detector='blazeface')
# Blazeface (back camera model)
model = FaceAlignment(landmarks_type= LandmarksType.TWO_D, face_detector='blazeface', face_detector_kwargs={'back_model': True})
```
## Installation
### Requirements
* Python 3.5+ (it may work with other versions too). Last version with support for python 2.7 was v1.1.1
* Linux, Windows or macOS
* pytorch (>=1.5)
While not required, for optimal performance(especially for the detector) it is **highly** recommended to run the code using a CUDA enabled GPU.
### Binaries
The easiest way to install it is using either pip or conda:
| **Using pip** | **Using conda** |
|------------------------------|--------------------------------------------|
| `pip install face-alignment` | `conda install -c 1adrianb face_alignment` |
| | |
Alternatively, bellow, you can find instruction to build it from source.
### From source
Install pytorch and pytorch dependencies. Please check the [pytorch readme](https://github.com/pytorch/pytorch) for this.
#### Get the Face Alignment source code
```bash
git clone https://github.com/1adrianb/face-alignment
```
#### Install the Face Alignment lib
```bash
pip install -r requirements.txt
python setup.py install
```
### Docker image
A Dockerfile is provided to build images with cuda support and cudnn. For more instructions about running and building a docker image check the orginal Docker documentation.
```
docker build -t face-alignment .
```
## How does it work?
While here the work is presented as a black-box, if you want to know more about the intrisecs of the method please check the original paper either on arxiv or my [webpage](https://www.adrianbulat.com).
## Contributions
All contributions are welcomed. If you encounter any issue (including examples of images where it fails) feel free to open an issue. If you plan to add a new features please open an issue to discuss this prior to making a pull request.
## Citation
```
@inproceedings{bulat2017far,
title={How far are we from solving the 2D \& 3D Face Alignment problem? (and a dataset of 230,000 3D facial landmarks)},
author={Bulat, Adrian and Tzimiropoulos, Georgios},
booktitle={International Conference on Computer Vision},
year={2017}
}
```
For citing dlib, pytorch or any other packages used here please check the original page of their respective authors.
## Acknowledgements
* To the [pytorch](http://pytorch.org/) team for providing such an awesome deeplearning framework
* To [my supervisor](http://www.cs.nott.ac.uk/~pszyt/) for his patience and suggestions.
* To all other python developers that made available the rest of the packages used in this repository.
Raw data
{
"_id": null,
"home_page": "https://github.com/1adrianb/face-alignment",
"name": "face-alignment",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3",
"maintainer_email": "",
"keywords": "",
"author": "Adrian Bulat",
"author_email": "adrian@adrianbulat.com",
"download_url": "https://files.pythonhosted.org/packages/8e/a3/7b5f7f75f899560493c910beed3b9e436edf495ebdb7a018d90e8340fc19/face_alignment-1.4.1.tar.gz",
"platform": null,
"description": "# Face Recognition\n\nDetect facial landmarks from Python using the world's most accurate face alignment network, capable of detecting points in both 2D and 3D coordinates.\n\nBuild using [FAN](https://www.adrianbulat.com)'s state-of-the-art deep learning based face alignment method. \n\n<p align=\"center\"><img src=\"docs/images/face-alignment-adrian.gif\" /></p>\n\n**Note:** The lua version is available [here](https://github.com/1adrianb/2D-and-3D-face-alignment).\n\nFor numerical evaluations it is highly recommended to use the lua version which uses indentical models with the ones evaluated in the paper. More models will be added soon.\n\n[](https://opensource.org/licenses/BSD-3-Clause) [](https://github.com/1adrianb/face-alignment/actions?query=workflow%3A%22Test+Face+alignmnet%22) [](https://anaconda.org/1adrianb/face_alignment)\n[](https://pypi.org/project/face-alignment/)\n\n## Features\n\n#### Detect 2D facial landmarks in pictures\n\n<p align='center'>\n<img src='docs/images/2dlandmarks.png' title='3D-FAN-Full example' style='max-width:600px'></img>\n</p>\n\n```python\nimport face_alignment\nfrom skimage import io\n\nfa = face_alignment.FaceAlignment(face_alignment.LandmarksType.TWO_D, flip_input=False)\n\ninput = io.imread('../test/assets/aflw-test.jpg')\npreds = fa.get_landmarks(input)\n```\n\n#### Detect 3D facial landmarks in pictures\n\n<p align='center'>\n<img src='https://www.adrianbulat.com/images/image-z-examples.png' title='3D-FAN-Full example' style='max-width:600px'></img>\n</p>\n\n```python\nimport face_alignment\nfrom skimage import io\n\nfa = face_alignment.FaceAlignment(face_alignment.LandmarksType.THREE_D, flip_input=False)\n\ninput = io.imread('../test/assets/aflw-test.jpg')\npreds = fa.get_landmarks(input)\n```\n\n#### Process an entire directory in one go\n\n```python\nimport face_alignment\nfrom skimage import io\n\nfa = face_alignment.FaceAlignment(face_alignment.LandmarksType.TWO_D, flip_input=False)\n\npreds = fa.get_landmarks_from_directory('../test/assets/')\n```\n\n#### Detect the landmarks using a specific face detector.\n\nBy default the package will use the SFD face detector. However the users can alternatively use dlib, BlazeFace, or pre-existing ground truth bounding boxes.\n\n```python\nimport face_alignment\n\n# sfd for SFD, dlib for Dlib and folder for existing bounding boxes.\nfa = face_alignment.FaceAlignment(face_alignment.LandmarksType.TWO_D, face_detector='sfd')\n```\n\n#### Running on CPU/GPU\nIn order to specify the device (GPU or CPU) on which the code will run one can explicitly pass the device flag:\n\n```python\nimport torch\nimport face_alignment\n\n# cuda for CUDA, mps for Apple M1/2 GPUs.\nfa = face_alignment.FaceAlignment(face_alignment.LandmarksType.TWO_D, device='cpu')\n\n# running using lower precision\nfa = fa = face_alignment.FaceAlignment(face_alignment.LandmarksType.TWO_D, dtype=torch.bfloat16, device='cuda')\n```\n\nPlease also see the ``examples`` folder\n\n#### Supported face detectors\n\n```python\n\n# dlib (fast, may miss faces)\nmodel = FaceAlignment(landmarks_type= LandmarksType.TWO_D, face_detector='dlib')\n\n# SFD (likely best results, but slowest)\nmodel = FaceAlignment(landmarks_type= LandmarksType.TWO_D, face_detector='sfd')\n\n# Blazeface (front camera model)\nmodel = FaceAlignment(landmarks_type= LandmarksType.TWO_D, face_detector='blazeface')\n\n# Blazeface (back camera model)\nmodel = FaceAlignment(landmarks_type= LandmarksType.TWO_D, face_detector='blazeface', face_detector_kwargs={'back_model': True})\n\n```\n\n## Installation\n\n### Requirements\n\n* Python 3.5+ (it may work with other versions too). Last version with support for python 2.7 was v1.1.1\n* Linux, Windows or macOS\n* pytorch (>=1.5)\n\nWhile not required, for optimal performance(especially for the detector) it is **highly** recommended to run the code using a CUDA enabled GPU.\n\n### Binaries\n\nThe easiest way to install it is using either pip or conda:\n\n| **Using pip** | **Using conda** |\n|------------------------------|--------------------------------------------|\n| `pip install face-alignment` | `conda install -c 1adrianb face_alignment` |\n| | |\n\nAlternatively, bellow, you can find instruction to build it from source.\n\n### From source\n\n Install pytorch and pytorch dependencies. Please check the [pytorch readme](https://github.com/pytorch/pytorch) for this.\n\n#### Get the Face Alignment source code\n```bash\ngit clone https://github.com/1adrianb/face-alignment\n```\n#### Install the Face Alignment lib\n```bash\npip install -r requirements.txt\npython setup.py install\n```\n\n### Docker image\n\nA Dockerfile is provided to build images with cuda support and cudnn. For more instructions about running and building a docker image check the orginal Docker documentation.\n```\ndocker build -t face-alignment .\n```\n\n## How does it work?\n\nWhile here the work is presented as a black-box, if you want to know more about the intrisecs of the method please check the original paper either on arxiv or my [webpage](https://www.adrianbulat.com).\n\n## Contributions\n\nAll contributions are welcomed. If you encounter any issue (including examples of images where it fails) feel free to open an issue. If you plan to add a new features please open an issue to discuss this prior to making a pull request.\n\n## Citation\n\n```\n@inproceedings{bulat2017far,\n title={How far are we from solving the 2D \\& 3D Face Alignment problem? (and a dataset of 230,000 3D facial landmarks)},\n author={Bulat, Adrian and Tzimiropoulos, Georgios},\n booktitle={International Conference on Computer Vision},\n year={2017}\n}\n```\n\nFor citing dlib, pytorch or any other packages used here please check the original page of their respective authors.\n\n## Acknowledgements\n\n* To the [pytorch](http://pytorch.org/) team for providing such an awesome deeplearning framework\n* To [my supervisor](http://www.cs.nott.ac.uk/~pszyt/) for his patience and suggestions.\n* To all other python developers that made available the rest of the packages used in this repository.\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Detector 2D or 3D face landmarks from Python",
"version": "1.4.1",
"project_urls": {
"Homepage": "https://github.com/1adrianb/face-alignment"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a17e36e212aa11d227a6d9afae540e91f161a7db3ad28177804403fe45fda5e2",
"md5": "87e0609352efb8b1dd7d8e9f6b387164",
"sha256": "e153254a1162cedae593c085b4ff7eea2cac4e2be821cdc4a90ce04ff71d5c52"
},
"downloads": -1,
"filename": "face_alignment-1.4.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "87e0609352efb8b1dd7d8e9f6b387164",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3",
"size": 30642,
"upload_time": "2023-08-17T14:43:11",
"upload_time_iso_8601": "2023-08-17T14:43:11.107160Z",
"url": "https://files.pythonhosted.org/packages/a1/7e/36e212aa11d227a6d9afae540e91f161a7db3ad28177804403fe45fda5e2/face_alignment-1.4.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8ea37b5f7f75f899560493c910beed3b9e436edf495ebdb7a018d90e8340fc19",
"md5": "ecef64db3ac01dc14fb8c9fa81890c73",
"sha256": "90e47b827a7913de19de99d0df0bf0ab539fb29ed674aeaec0ac27666cafbed9"
},
"downloads": -1,
"filename": "face_alignment-1.4.1.tar.gz",
"has_sig": false,
"md5_digest": "ecef64db3ac01dc14fb8c9fa81890c73",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3",
"size": 29039,
"upload_time": "2023-08-17T14:43:13",
"upload_time_iso_8601": "2023-08-17T14:43:13.408437Z",
"url": "https://files.pythonhosted.org/packages/8e/a3/7b5f7f75f899560493c910beed3b9e436edf495ebdb7a018d90e8340fc19/face_alignment-1.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-17 14:43:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "1adrianb",
"github_project": "face-alignment",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "face-alignment"
}
JSON
