# Dynaface Python Library
[](https://badge.fury.io/py/dynaface)
[](LICENSE)
[](https://colab.research.google.com/github/jeffheaton/dynaface/blob/main/dynaface-lib/examples/dynaface_intro.ipynb)
Dynaface is an AI-driven facial tracking Python Library utilizing computer vision techniques that integrate Convolutional Neural Networks (CNNs) with cascaded Graph Attention Network (GAT) regressors to enhance facial landmark detection by capturing both local appearance and global structural relationships ([Prados-Torreblanca1, A & Buenaposada, J](https://bmvc2022.mpi-inf.mpg.de/0155.pdf)). This approach encodes both the appearance and spatial positioning of facial landmarks while employing an attention mechanism to prioritize reliable information. Such a method is particularly advantageous for assessing facial asymmetry in patients with facial paralysis, where conventional landmarking algorithms are often biased toward symmetric faces. By leveraging a global representation of facial structure, Dynaface enables precise detection of key landmarks despite asymmetries, facilitating the objective quantification of facial movement and asymmetry. These measurements, including the Facial Asymmetry Index (FAI) and Oral Commissure Excursion (OCE), serve as critical indicators of facial function and can be correlated with patient-reported outcomes to evaluate recovery and patient satisfaction.
# Sample Code
Install from [pypi](https://pypi.org/project/dynaface/).
```
pip install dynaface
```
Calculate measures on a face.
```
import cv2
from dynaface import facial, measures, models
all_measures = measures.all_measures()
face = facial.AnalyzeFace(measures = all_measures)
face.load_image(image_rgb,crop=True)
face.analyze()
```
# Helpful Links
- [Dynaface Application](https://github.com/jeffheaton/dynaface/tree/main/dynaface-app)
# Helpful Python Commands
**Activate Environment**
```
source venv/bin/activate
.\venv\Scripts\activate.bat
.\venv\Scripts\Activate.ps1
```
**Allow Windows to Use Environment**
```
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
```
**Run Unit Tests**
For Mac/Linux:
```
cd dynaface-lib
python3.11 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
python -m unittest discover -s tests
```
For Windows:
```
cd dynaface-lib
python3.11 -m venv venv
.\venv\Scripts\Activate.ps1
pip install -e ".[dev]"
python -m unittest discover -s tests
```
⚠️ Note for Windows users:
If you get an error like execution of scripts is disabled on this system when activating the virtual environment, you can temporarily bypass it with:
```
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\venv\Scripts\Activate.ps1
```
# Running Examples
- [Dynaface Examples]()
```
python ./examples/process_media.py /Users/jeff/data/facial/samples/tracy-ref-blink.mp4
python ./examples/process_media.py --crop /Users/jeff/data/facial/samples/2021-8-19.png
python ./examples/process_media.py --crop /Users/jeff/data/facial/samples/tracy_frame.png
python ./examples/process_media.py --crop /Users/jeff/data/facial/samples/tracy-blink-single.mp4
```
Raw data
{
"_id": null,
"home_page": "https://github.com/jeffheaton/dynaface",
"name": "dynaface",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "facial landmarks, symmetry, paralysis, face detection, image analysis",
"author": "Jeff Heaton",
"author_email": "jeff@jeffheaton.com",
"download_url": null,
"platform": null,
"description": "\n\n# Dynaface Python Library\n\n[](https://badge.fury.io/py/dynaface)\n[](LICENSE)\n[](https://colab.research.google.com/github/jeffheaton/dynaface/blob/main/dynaface-lib/examples/dynaface_intro.ipynb)\n\nDynaface is an AI-driven facial tracking Python Library utilizing computer vision techniques that integrate Convolutional Neural Networks (CNNs) with cascaded Graph Attention Network (GAT) regressors to enhance facial landmark detection by capturing both local appearance and global structural relationships ([Prados-Torreblanca1, A & Buenaposada, J](https://bmvc2022.mpi-inf.mpg.de/0155.pdf)). This approach encodes both the appearance and spatial positioning of facial landmarks while employing an attention mechanism to prioritize reliable information. Such a method is particularly advantageous for assessing facial asymmetry in patients with facial paralysis, where conventional landmarking algorithms are often biased toward symmetric faces. By leveraging a global representation of facial structure, Dynaface enables precise detection of key landmarks despite asymmetries, facilitating the objective quantification of facial movement and asymmetry. These measurements, including the Facial Asymmetry Index (FAI) and Oral Commissure Excursion (OCE), serve as critical indicators of facial function and can be correlated with patient-reported outcomes to evaluate recovery and patient satisfaction.\n\n# Sample Code\n\nInstall from [pypi](https://pypi.org/project/dynaface/).\n\n```\npip install dynaface\n```\n\nCalculate measures on a face.\n\n```\nimport cv2\nfrom dynaface import facial, measures, models\n\nall_measures = measures.all_measures()\nface = facial.AnalyzeFace(measures = all_measures)\nface.load_image(image_rgb,crop=True)\nface.analyze()\n```\n\n# Helpful Links\n\n- [Dynaface Application](https://github.com/jeffheaton/dynaface/tree/main/dynaface-app)\n\n# Helpful Python Commands\n\n**Activate Environment**\n\n```\nsource venv/bin/activate\n.\\venv\\Scripts\\activate.bat\n.\\venv\\Scripts\\Activate.ps1\n```\n\n**Allow Windows to Use Environment**\n\n```\nSet-ExecutionPolicy RemoteSigned -Scope CurrentUser\n```\n\n**Run Unit Tests**\n\nFor Mac/Linux:\n\n```\ncd dynaface-lib\npython3.11 -m venv venv\nsource venv/bin/activate\npip install -e \".[dev]\"\npython -m unittest discover -s tests\n```\n\nFor Windows:\n\n```\ncd dynaface-lib\npython3.11 -m venv venv\n.\\venv\\Scripts\\Activate.ps1\npip install -e \".[dev]\"\npython -m unittest discover -s tests\n```\n\n\u26a0\ufe0f Note for Windows users:\nIf you get an error like execution of scripts is disabled on this system when activating the virtual environment, you can temporarily bypass it with:\n\n```\nSet-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass\n.\\venv\\Scripts\\Activate.ps1\n```\n\n# Running Examples\n\n- [Dynaface Examples]()\n\n```\npython ./examples/process_media.py /Users/jeff/data/facial/samples/tracy-ref-blink.mp4\n\npython ./examples/process_media.py --crop /Users/jeff/data/facial/samples/2021-8-19.png\n\npython ./examples/process_media.py --crop /Users/jeff/data/facial/samples/tracy_frame.png\n\npython ./examples/process_media.py --crop /Users/jeff/data/facial/samples/tracy-blink-single.mp4\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Facial landmark analysis and symmetry measurement tool for facial paralysis.",
"version": "0.2.3",
"project_urls": {
"Bug Tracker": "https://github.com/jeffheaton/dynaface/issues",
"Documentation": "https://github.com/jeffheaton/dynaface",
"Homepage": "https://github.com/jeffheaton/dynaface",
"Source": "https://github.com/jeffheaton/dynaface"
},
"split_keywords": [
"facial landmarks",
" symmetry",
" paralysis",
" face detection",
" image analysis"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "289d26aa1373c263cbea3f81a04087024ec430524c5285cd17ec8e516f35dac5",
"md5": "34f1ee266fc5bab09839cde7c186d744",
"sha256": "f86aba9d5743c802db23a4cdf207f8ac65c97089e91840335813d23e81f1112e"
},
"downloads": -1,
"filename": "dynaface-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "34f1ee266fc5bab09839cde7c186d744",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 36476414,
"upload_time": "2025-07-20T21:37:23",
"upload_time_iso_8601": "2025-07-20T21:37:23.462960Z",
"url": "https://files.pythonhosted.org/packages/28/9d/26aa1373c263cbea3f81a04087024ec430524c5285cd17ec8e516f35dac5/dynaface-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-20 21:37:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jeffheaton",
"github_project": "dynaface",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "dynaface"
}
JSON
