Metadata-Version: 2.4
Name: pyclnf
Version: 0.2.6
Summary: Pure Python implementation of CLNF (Constrained Local Neural Fields) facial landmark detector
Author-email: John Wilson IV <your.email@example.com>
License: CC BY-NC 4.0
Project-URL: Homepage, https://github.com/johnwilsoniv/pyclnf
Project-URL: Repository, https://github.com/johnwilsoniv/pyclnf
Project-URL: Bug Tracker, https://github.com/johnwilsoniv/pyclnf/issues
Keywords: clnf,facial-landmarks,face-alignment,openface,computer-vision,pure-python,mtcnn
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.19.0
Requires-Dist: opencv-python>=4.5.0
Requires-Dist: pymtcnn>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Dynamic: license-file

# pyclnf

Pure Python implementation of OpenFace's CLNF (Constrained Local Neural Fields) facial landmark detector.

## Installation

```bash
pip install pyclnf
```

## Usage

```python
from pyclnf import CLNF

clnf = CLNF()
landmarks, pose = clnf.fit(image)  # 68 facial landmarks + head pose
```

For video, use `clnf.fit()` on consecutive frames—it automatically tracks faces across frames.

## What it does

- Detects 68 facial landmarks
- Estimates 3D head pose (pitch, yaw, roll)
- Uses OpenFace's trained CEN patch experts
- Built-in face detection via [pymtcnn](https://github.com/johnwilsoniv/pymtcnn)

## Citation

If you use this in research, please cite:

> Wilson IV, J., Rosenberg, J., Gray, M. L., & Razavi, C. R. (2025). A split-face computer vision/machine learning assessment of facial paralysis using facial action units. *Facial Plastic Surgery & Aesthetic Medicine*. https://doi.org/10.1177/26893614251394382

## License

CC BY-NC 4.0 — free for non-commercial use with attribution.
