Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,70 @@
+---
+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.