# Facer
Face detection, alignment, and averaging using OpenCV and `dlib`.
Facer draws heavily on [this tutorial](https://www.learnopencv.com/average-face-opencv-c-python-tutorial/) from [Satya Mallick](https://github.com/spmallick). I had to update the code pretty heavily to get the project to work, so I thought I'd share my modifications.
## Example
The image below is an example of Facer's output for one of my posts on [`r/dataisbeautiful`](https://www.reddit.com/r/dataisbeautiful/comments/crxrud/the_average_faces_of_rap_rock_and_country/).
[](https://www.reddit.com/r/dataisbeautiful/comments/crxrud/the_average_faces_of_rap_rock_and_country/)
## Installation
You have my 100% money-back guarantee that the most difficult part of using this package is installing its requirements. Once you've got OpenCV installed, the rest ~~will~~ should be smooth sailing. I've had the best luck with the OpenCV using the `opencv-python` package from PyPI.
Install `facer` using `pip`:
```bash
pip install -U average-facer
```
### Pre-trained detection model
The face landmark detection relies on a pre-trained model that must be downloaded separately from the `dlib` package itself.
```shell
wget http://dlib.net/files/shape_predictor_68_face_landmarks.dat.bz2
```
Unzip the compressed file after it finishes downloading and move it into a `./model` directory.
If you store the downloaded file somewhere other than `./model` (or if you use an entirely different model name), you can set a custom model path as an environment variable:
```bash
export FACER_PREDICTOR_PATH="./custom/path/to/your/model.dat"
```
## Usage
```python
from facer import facer
import matplotlib.pyplot as plt
# Load face images
path_to_images = "./face_images" # Put your images here
images = facer.load_images(path_to_images)
# Detect landmarks for each face
landmarks, faces = facer.detect_face_landmarks(images)
# Use the detected landmarks to create an average face
average_face = facer.create_average_face(faces, landmarks, save_image=True)
# View the composite image
plt.imshow(average_face)
plt.show()
```
Facer also supports creating animated GIFs of the averaging process:
```python
from facer import facer
path_to_images = "./face_images"
gif, average_face = facer.create_animated_gif(path_to_images)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/johnwmillr/Facer",
"name": "average-facer",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "opencv, image-processing, face-detection, dlib, face-average, facer, face-averaging, average-facer",
"author": "John William Ruth Miller",
"author_email": "john.w.millr@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/72/41/2a567232176b7b8399ed8d4ee119ecd2f5af49ba3a9d1ffac29df0711d9d/average_facer-0.7.6.tar.gz",
"platform": null,
"description": "# Facer\n\nFace detection, alignment, and averaging using OpenCV and `dlib`.\n\nFacer draws heavily on [this tutorial](https://www.learnopencv.com/average-face-opencv-c-python-tutorial/) from [Satya Mallick](https://github.com/spmallick). I had to update the code pretty heavily to get the project to work, so I thought I'd share my modifications.\n\n## Example\n\nThe image below is an example of Facer's output for one of my posts on [`r/dataisbeautiful`](https://www.reddit.com/r/dataisbeautiful/comments/crxrud/the_average_faces_of_rap_rock_and_country/).\n\n[](https://www.reddit.com/r/dataisbeautiful/comments/crxrud/the_average_faces_of_rap_rock_and_country/)\n\n## Installation\n\nYou have my 100% money-back guarantee that the most difficult part of using this package is installing its requirements. Once you've got OpenCV installed, the rest ~~will~~ should be smooth sailing. I've had the best luck with the OpenCV using the `opencv-python` package from PyPI.\n\nInstall `facer` using `pip`:\n\n```bash\npip install -U average-facer\n```\n\n### Pre-trained detection model\n\nThe face landmark detection relies on a pre-trained model that must be downloaded separately from the `dlib` package itself.\n\n```shell\nwget http://dlib.net/files/shape_predictor_68_face_landmarks.dat.bz2\n```\n\nUnzip the compressed file after it finishes downloading and move it into a `./model` directory.\n\nIf you store the downloaded file somewhere other than `./model` (or if you use an entirely different model name), you can set a custom model path as an environment variable:\n\n```bash\nexport FACER_PREDICTOR_PATH=\"./custom/path/to/your/model.dat\"\n```\n\n## Usage\n\n```python\nfrom facer import facer\nimport matplotlib.pyplot as plt\n\n\n# Load face images\npath_to_images = \"./face_images\" # Put your images here\nimages = facer.load_images(path_to_images)\n\n# Detect landmarks for each face\nlandmarks, faces = facer.detect_face_landmarks(images)\n\n# Use the detected landmarks to create an average face\naverage_face = facer.create_average_face(faces, landmarks, save_image=True)\n\n# View the composite image\nplt.imshow(average_face)\nplt.show()\n```\n\nFacer also supports creating animated GIFs of the averaging process:\n\n```python\nfrom facer import facer\n\npath_to_images = \"./face_images\"\ngif, average_face = facer.create_animated_gif(path_to_images)\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Face averaging in Python made simple.",
"version": "0.7.6",
"project_urls": {
"Blog Post": "https://www.johnwmillr.com/average-faces-in-python/",
"Faces of Fortune": "https://www.johnwmillr.com/faces-of-fortune/",
"Homepage": "https://github.com/johnwmillr/Facer",
"PyPI": "https://pypi.org/project/average-facer/",
"Repository": "https://github.com/johnwmillr/Facer"
},
"split_keywords": [
"opencv",
" image-processing",
" face-detection",
" dlib",
" face-average",
" facer",
" face-averaging",
" average-facer"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1afa3850aff15913edfe6cde257677c14c2c772e770b3bcf7d19b4d9b1130821",
"md5": "67f514aaad60c45fde32432a2415404f",
"sha256": "1d23d50927f581c46b001d73b354acb839880fb67376d584e8b918276eee6ed5"
},
"downloads": -1,
"filename": "average_facer-0.7.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "67f514aaad60c45fde32432a2415404f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 11755,
"upload_time": "2024-12-11T06:28:43",
"upload_time_iso_8601": "2024-12-11T06:28:43.893572Z",
"url": "https://files.pythonhosted.org/packages/1a/fa/3850aff15913edfe6cde257677c14c2c772e770b3bcf7d19b4d9b1130821/average_facer-0.7.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "72412a567232176b7b8399ed8d4ee119ecd2f5af49ba3a9d1ffac29df0711d9d",
"md5": "ad70e3fe6e293bb90105bec269050751",
"sha256": "56898ed624ee6b9713e00b426132479e58e0c660d94eb9f1f906c8a3bdb7409e"
},
"downloads": -1,
"filename": "average_facer-0.7.6.tar.gz",
"has_sig": false,
"md5_digest": "ad70e3fe6e293bb90105bec269050751",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 11648,
"upload_time": "2024-12-11T06:28:46",
"upload_time_iso_8601": "2024-12-11T06:28:46.083110Z",
"url": "https://files.pythonhosted.org/packages/72/41/2a567232176b7b8399ed8d4ee119ecd2f5af49ba3a9d1ffac29df0711d9d/average_facer-0.7.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-11 06:28:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "johnwmillr",
"github_project": "Facer",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "average-facer"
}
JSON
