{"id":13400039,"url":"https://github.com/1adrianb/face-alignment","last_synced_at":"2025-05-12T15:26:05.137Z","repository":{"id":37334554,"uuid":"103698763","full_name":"1adrianb/face-alignment","owner":"1adrianb","description":":fire: 2D and 3D Face alignment library build using pytorch ","archived":false,"fork":false,"pushed_at":"2024-08-30T14:19:26.000Z","size":6422,"stargazers_count":7279,"open_issues_count":84,"forks_count":1362,"subscribers_count":173,"default_branch":"master","last_synced_at":"2025-04-23T17:13:13.324Z","etag":null,"topics":["deep-learning","face-alignment","face-detection","face-detector","python","pytorch"],"latest_commit_sha":null,"homepage":"https://www.adrianbulat.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/1adrianb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-15T20:32:44.000Z","updated_at":"2025-04-23T10:48:22.000Z","dependencies_parsed_at":"2022-07-12T11:54:58.545Z","dependency_job_id":"674b361b-f6b9-4dff-8084-81a23f6a3f5b","html_url":"https://github.com/1adrianb/face-alignment","commit_stats":{"total_commits":186,"total_committers":28,"mean_commits":6.642857142857143,"dds":0.6129032258064516,"last_synced_commit":"c94dd024b1f5410ef160ff82a8423141e2bbb6b4"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1adrianb%2Fface-alignment","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1adrianb%2Fface-alignment/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1adrianb%2Fface-alignment/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1adrianb%2Fface-alignment/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/1adrianb","download_url":"https://codeload.github.com/1adrianb/face-alignment/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253764703,"owners_count":21960611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deep-learning","face-alignment","face-detection","face-detector","python","pytorch"],"created_at":"2024-07-30T19:00:47.094Z","updated_at":"2025-05-12T15:26:05.111Z","avatar_url":"https://github.com/1adrianb.png","language":"Python","readme":"# 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\u003cp align=\"center\"\u003e\u003cimg src=\"docs/images/face-alignment-adrian.gif\" /\u003e\u003c/p\u003e\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[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)  [![Test Face alignmnet](https://github.com/1adrianb/face-alignment/workflows/Test%20Face%20alignmnet/badge.svg)](https://github.com/1adrianb/face-alignment/actions?query=workflow%3A%22Test+Face+alignmnet%22) [![Anaconda-Server Badge](https://anaconda.org/1adrianb/face_alignment/badges/version.svg)](https://anaconda.org/1adrianb/face_alignment)\n[![PyPI version](https://badge.fury.io/py/face-alignment.svg)](https://pypi.org/project/face-alignment/)\n\n## Features\n\n#### Detect 2D facial landmarks in pictures\n\n\u003cp align='center'\u003e\n\u003cimg src='docs/images/2dlandmarks.png' title='3D-FAN-Full example' style='max-width:600px'\u003e\u003c/img\u003e\n\u003c/p\u003e\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\u003cp align='center'\u003e\n\u003cimg src='https://www.adrianbulat.com/images/image-z-examples.png' title='3D-FAN-Full example' style='max-width:600px'\u003e\u003c/img\u003e\n\u003c/p\u003e\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 (\u003e=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 \\\u0026 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.","funding_links":[],"categories":["Face detection and alignment","Python","Face landmarks","图像数据与CV","Pytorch \u0026 related libraries｜Pytorch \u0026 相关库","Pytorch \u0026 related libraries","CV\u0026PyTorch实战","Table of Contents","Face Perception"],"sub_categories":["CV｜计算机视觉:","CV:","Facial Landmark"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F1adrianb%2Fface-alignment","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F1adrianb%2Fface-alignment","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F1adrianb%2Fface-alignment/lists"}