README.md

---
license: mit
tags:
  - primateface
  - face-detection
  - pose-estimation
  - primates
  - animal-behavior
  - computer-vision
library_name: primateface
---

# PrimateFace Models

Pre-trained models for [PrimateFace](https://github.com/KordingLab/PrimateFace) --- an open-source toolkit for primate face detection, landmark estimation, and facial behavior analysis across 60+ primate genera.

## Models

| Model | Task | Architecture | File | Size |
|---|---|---|---|---|
| **Face Detection** | Bounding box detection | Cascade R-CNN (ResNet-101 + FPN) | `detection/cascade_rcnn_r101_fpn.pth` | 340 MB |
| **Face Pose** | 68-keypoint landmark estimation | HRNetV2-W18-DARK | `pose/hrnetv2_w18_dark_68kpt.pth` | 38 MB |

Both models were trained on PrimateFace data spanning 60+ primate genera using the [MMDetection](https://github.com/open-mmlab/mmdetection) and [MMPose](https://github.com/open-mmlab/mmpose) frameworks.

## Keypoint Format

68-point facial landmarks following the dlib standard (COCO format: `[x, y, visibility] x 68`):
- Jaw contour (17 points)
- Eyebrows (10 points)
- Nose bridge + base (9 points)
- Eyes (12 points)
- Mouth outer + inner (20 points)

## Quick Start

```python
# Download models automatically
python demos/download_models.py

# Or use the Python API
from huggingface_hub import hf_hub_download

det_path = hf_hub_download(
    repo_id="fparodi/primateface-models",
    filename="cascade_rcnn_r101_fpn.pth",
    subfolder="detection",
)

pose_path = hf_hub_download(
    repo_id="fparodi/primateface-models",
    filename="hrnetv2_w18_dark_68kpt.pth",
    subfolder="pose",
)
```

## Citation

```bibtex
@article{parodi2025primateface,
  title={PrimateFace: A Machine Learning Resource for Automated Face Analysis in Human and Non-human Primates},
  author={Parodi, Felipe and Matelsky, Jordan and others},
  year={2025},
  url={https://www.biorxiv.org/content/10.1101/2025.08.12.669927}
}
```

## License

MIT --- same as the PrimateFace repository.