Merge pull request #10 from felipe-parodi/main

feat: PrimateFace Python package, CLI, tutorials, and docs

Author: felipe-parodi

.gitignore

@@ -58,6 +58,14 @@ demos/mmdet_checkpoint.pth
 demos/mmpose_checkpoint.pth
 demos/test_output/
 demos/results/
+demos/notebooks/*_output/
+demos/notebooks/*_demo/
+demos/notebooks/*_results/
+demos/notebooks/embeddings*.npz
+demos/notebooks/figures_*
+
+# Temp demo images
+*_demo.jpg
 
 # Downloaded YOLO models
 yolov*.pt
@@ -127,3 +135,5 @@ docs/gradio/primateface_server.py
 AGENTS.md
 
 
+results/
+analysis/

README.md

@@ -18,6 +18,10 @@
   <a href="https://huggingface.co/datasets/fparodi/PrimateFace">
     <img src="https://img.shields.io/badge/🤗%20Hugging%20Face-Dataset-blue" alt="Hugging Face Dataset">
   </a>
+  &nbsp;&nbsp;
+  <a href="https://huggingface.co/fparodi/primateface-models">
+    <img src="https://img.shields.io/badge/🤗%20Hugging%20Face-Models-blue" alt="Hugging Face Models">
+  </a>
 </p>
 
 PrimateFace contains data, models, and tutorials for analyzing facial behavior across primates ([Parodi et al., 2025](https://www.biorxiv.org/content/10.1101/2025.08.12.669927)). 
@@ -37,24 +41,25 @@ Most of the PrimateFace modules require GPU access. If you don't have access to
 
 2. Run through the [Google Colab Notebook tutorials](https://docs.primateface.studio/tutorials/) to explore several applications of PrimateFace.
 
-3. Clone this repository, install the dependencies, and run through the different modules (e.g., DINOv2, image and video demos, pseudo-labeling GUI, etc.) to fully utilize PrimateFace.
+3. Clone this repository, install the dependencies, download the pretrained models (`python demos/download_models.py`), and run through the different modules (e.g., DINOv2, image and video demos, pseudo-labeling GUI, etc.) to fully utilize PrimateFace.
 
 
 #### Structure
 This repository contains the code for PrimateFace, an ecosystem for facilitating cross-species primate face analysis.
 
 ```
-|--- dataset            # Explore PrimateFace data
-|--- demos              # Test models on your own data
-   |--- notebooks       # Google Colab notebooks for tutorials
-|--- dinov2             # Run and visualize DINOv2 features
-|--- docs               # Documentation for PrimateFace
-|--- evals              # Evaluate models across frameworks & datasets
-|--- gui                # Run pseudo-labeling GUI on your own data
-|--- landmark-converter # Train & apply keypoint landmark converters (68 -> 48 kpts)
-|--- pyproject.toml
-|--- README.md
-|--- environment.yml    # Unified conda environment for modules
+|--- primateface        # Core library (pip install primateface)
+   |--- analysis        #   Facial analysis (kinematics, symmetry, head pose, quality)
+   |--- io.py           #   Export to CSV, COCO, DLC, SLEAP, NWB
+   |--- cli.py          #   CLI: primateface analyze, primateface models
+|--- demos              # Demo scripts and tutorial notebooks
+   |--- notebooks       #   7 Jupyter notebooks (Quick Start, face rec, etc.)
+|--- dinov2             # DINOv2 feature extraction and visualization
+|--- docs               # Documentation
+|--- evals              # Model evaluation across frameworks & datasets
+|--- gui                # Pseudo-labeling GUI
+|--- landmark-converter # Keypoint landmark converters (68 <-> 48 kpts)
+|--- tests              # Unit tests (121 passing)
 ```
 
 
@@ -120,14 +125,15 @@ Note: You may see a harmless `RequestsDependencyWarning` about urllib3 versions
 - [Documentation Homepage](https://docs.primateface.studio)
 - [Notebook Tutorials](https://docs.primateface.studio/tutorials/)
 
-| Tutorial | Open in Colab |
-|---------|----------------|
-| **1. Lemur Face Visibility Time-Stamping** | [![Open](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/KordingLab/PrimateFace/blob/main/demos/notebooks/App1_Lemur_time_stamping.ipynb) |
-| **2. Rapid Macaque Face Recognition** | [![Open](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/KordingLab/PrimateFace/blob/main/demos/notebooks/App2_Macaque_Face_Recognition.ipynb) |
-| **4. Human Infant Social Gaze Tracking** | [![Open](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/KordingLab/PrimateFace/blob/main/demos/notebooks/App4_Gaze_following.ipynb) |
-| **3. Howler Vocal-Motor Coupling** | Coming soon |
-| **5. Data-Driven Discovery of Facial Actions** | Coming soon |
-| **6. Cross-Subject Neural Decoding of Facial Actions** | Coming soon |
+| Tutorial | Description |
+|----------|-------------|
+| [`quickstart`](demos/notebooks/quickstart.ipynb) | **Start here** — 3-line API, Face object, visualization, export |
+| [`lemur_video_timestamping`](demos/notebooks/lemur_video_timestamping.ipynb) | Detect and timestamp primate faces in video |
+| [`macaque_face_recognition`](demos/notebooks/macaque_face_recognition.ipynb) | Face recognition: ArcFace vs MegaDescriptor vs DINOv2 |
+| [`howler_vocal_motor_coupling`](demos/notebooks/howler_vocal_motor_coupling.ipynb) | Correlate facial kinematics with vocalizations |
+| [`macaque_gaze_following`](demos/notebooks/macaque_gaze_following.ipynb) | Gaze-following heuristic with Gazelle |
+| [`landmark_demographics`](demos/notebooks/landmark_demographics.ipynb) | Predict age and sex from facial landmarks |
+| [`facial_action_discovery`](demos/notebooks/facial_action_discovery.ipynb) | Unsupervised facial action discovery (MotionMapper-inspired) |
 
 
 #### References

demos/README.md

@@ -25,11 +25,20 @@ mim install "mmpose==1.3.2" --trusted-host download.openmmlab.com --trusted-host
 
 ### 2. Download pretrained models
 
+Models are hosted on [HuggingFace](https://huggingface.co/fparodi/primateface-models) and download automatically in notebooks. To download manually:
+
 ```bash
 cd demos
 python download_models.py  # Downloads to current directory
-# Or specify output directory:
-python download_models.py ./models
+python download_models.py --force  # Re-download existing files
+```
+
+Or from Python:
+
+```python
+from demos.notebooks.notebook_utils import download_models_hf
+from pathlib import Path
+download_models_hf(Path("demos/"))
 ```
 
 ### 3. Run face detection and face landmark estimation examples
@@ -145,18 +154,19 @@ pytest test_demos.py
 
 ```
 demos/
-├── primateface_demo.py      # Main CLI interface
-├── process.py               # Core processing pipeline  
-├── classify_genus.py        # Species classification
-├── viz_utils.py            # Visualization utilities
-├── smooth_utils.py         # Temporal smoothing
-├── demo_docs.md           # Technical documentation
-└── notebooks/             # Interactive tutorials
+├── primateface_demo.py      # Demo CLI (low-level, manual config paths)
+├── download_models.py       # Model download from HuggingFace
+├── classify_genus.py        # Species classification via VLM
+├── test_demos.py            # Unit tests
+└── notebooks/               # 7 interactive tutorial notebooks
+    ├── quickstart.ipynb
+    ├── lemur_video_timestamping.ipynb
+    ├── macaque_face_recognition.ipynb
+    ├── howler_vocal_motor_coupling.ipynb
+    ├── infant_gaze_following.ipynb
+    ├── landmark_demographics.ipynb
+    └── facial_action_discovery.ipynb
 ```
 
-## Next Steps
-
-- Explore [notebooks/](notebooks/) for hands-on tutorials
-- Check [evals/](../evals/) for model evaluation
-- Use [gui/](../gui/) for interactive annotation
-- Try [dinov2/](../dinov2/) for feature extraction
+**Note:** Core modules (processor, model registry, constants, viz, smoothing) have moved
+to the `primateface/` package. Backward-compatible imports from `demos` still work.

demos/__init__.py

@@ -1,37 +1,14 @@
-"""PrimateFace demonstration and example scripts.
+"""PrimateFace demonstration scripts and notebooks.
 
-This package contains demo scripts and utilities for PrimateFace:
-- Unified processing for videos and images
-- Primate genus classification 
-- COCO annotation visualization
-- Utility modules for smoothing and visualization
-"""
+Core functionality has moved to the ``primateface`` package::
 
-from .constants import (
-    DEFAULT_BBOX_THR,
-    DEFAULT_KPT_THR,
-    DEFAULT_NMS_THR,
-    IMAGE_EXTENSIONS,
-    PRIMATE_GENERA,
-    VIDEO_EXTENSIONS,
-)
-from .process import PrimateFaceProcessor
-from .smooth_utils import MedianSavgolSmoother
-from .viz_utils import FastPoseVisualizer
+    import primateface
+    pf = primateface.PrimateFace()
+    faces = pf.analyze("image.jpg")
 
-__all__ = [
-    # Main processor
-    'PrimateFaceProcessor',
-    # Utilities
-    'MedianSavgolSmoother',
-    'FastPoseVisualizer',
-    # Constants
-    'DEFAULT_BBOX_THR',
-    'DEFAULT_KPT_THR',
-    'DEFAULT_NMS_THR',
-    'IMAGE_EXTENSIONS',
-    'VIDEO_EXTENSIONS',
-    'PRIMATE_GENERA',
-]
+For low-level access to the processor, smoother, or visualizer::
 
-__version__ = '0.1.0'
+    from primateface._processor import PrimateFaceProcessor
+    from primateface._smooth import MedianSavgolSmoother
+    from primateface._viz import FastPoseVisualizer
+"""

demos/download_models.py

@@ -1,83 +1,116 @@
 #!/usr/bin/env python
-"""
-Download PrimateFace models from Google Drive.
-Models include detection (MMDetection) and pose estimation (MMPose) checkpoints.
+"""Download PrimateFace models from Hugging Face Hub.
+
+Models include detection (MMDetection) and pose estimation (MMPose) checkpoints
+hosted at https://huggingface.co/fparodi/primateface-models.
 """
 
-import os
+import shutil
 import sys
 import argparse
 from pathlib import Path
 
 try:
-    import gdown
+    from primateface._model_registry import (
+        HF_REPO_ID, HF_REPO_URL, MODELS, LIBRARY_NAME, LIBRARY_VERSION,
+    )
 except ImportError:
-    print("Installing gdown...")
-    import subprocess
-    subprocess.check_call([sys.executable, "-m", "pip", "install", "gdown"])
-    import gdown
-
-
-def download_models(output_dir="."):
-    """Download all PrimateFace models to the specified directory."""
-    
-    # Model IDs from Google Drive
-    models = {
-        "mmdet_config.py": "1Y_YFdIDRcWQLI-gRiCnOrDxCptzCiiNp",
-        "mmdet_checkpoint.pth": "1zZ8S31zPHX5BWYKbnHxI1QOqP-fPnVFO",
-        "mmpose_config.py": "1sG2lLybRkLwmC0IkEqtEGuT1OxwXomju",
-        "mmpose_checkpoint.pth": "1Oa18Ty90bNE8fud0cuK3gZmPY_LAQo3Y",
-    }
-    
-    # Create output directory if needed
+    # Fallback for standalone script execution
+    from model_registry import (  # type: ignore[no-redef]
+        HF_REPO_ID, HF_REPO_URL, MODELS, LIBRARY_NAME, LIBRARY_VERSION,
+    )
+
+
+def download_models(output_dir: str = ".", force: bool = False) -> bool:
+    """Download all PrimateFace models to the specified directory.
+
+    Args:
+        output_dir: Directory to save model files.
+        force: If True, re-download even if files already exist.
+
+    Returns:
+        True if all downloads succeeded.
+    """
+    try:
+        from huggingface_hub import hf_hub_download
+    except ImportError:
+        print(
+            "ERROR: huggingface_hub is required to download models.\n"
+            "Install with:  uv pip install huggingface-hub\n"
+            "  or:          pip install huggingface-hub",
+            file=sys.stderr,
+        )
+        return False
+
     output_path = Path(output_dir)
     output_path.mkdir(parents=True, exist_ok=True)
-    
-    print(f"Downloading models to: {output_path.absolute()}")
+
+    print(f"Downloading PrimateFace models to: {output_path.absolute()}")
+    print(f"Source: {HF_REPO_URL}")
+    print()
+
+    for local_name, (subfolder, hf_filename) in MODELS.items():
+        output_file = output_path / local_name
+        model_type = "MMDetection" if "mmdet" in local_name else "MMPose"
+        file_type = "config" if local_name.endswith(".py") else "checkpoint"
+
+        if output_file.exists() and not force:
+            size_mb = output_file.stat().st_size / (1024 * 1024)
+            print(f"  Already exists: {local_name} ({size_mb:.1f} MB)")
+            continue
+
+        print(f"  Downloading {model_type} {file_type}: {local_name} ...")
+        cached_path = hf_hub_download(
+            repo_id=HF_REPO_ID,
+            filename=hf_filename,
+            subfolder=subfolder,
+            library_name=LIBRARY_NAME,
+            library_version=LIBRARY_VERSION,
+        )
+
+        # Copy from HF cache to the requested output directory
+        shutil.copy2(cached_path, str(output_file))
+
+        size_mb = output_file.stat().st_size / (1024 * 1024)
+        print(f"    Saved: {local_name} ({size_mb:.1f} MB)")
+
     print()
-    
-    # Download each model
-    for filename, file_id in models.items():
-        output_file = output_path / filename
-        model_type = "MMDetection" if "mmdet" in filename else "MMPose"
-        file_type = "config" if filename.endswith(".py") else "checkpoint"
-        
-        print(f"Downloading {model_type} {file_type}...")
-        url = f"https://drive.google.com/uc?id={file_id}"
-        gdown.download(url, str(output_file), quiet=False)
-        print()
-    
-    # List downloaded files
-    print("✓ All models downloaded successfully!")
-    print("\nFiles downloaded:")
-    for filename in models.keys():
-        file_path = output_path / filename
+    print("All models downloaded successfully!")
+    print("\nFiles:")
+    for local_name in MODELS:
+        file_path = output_path / local_name
         if file_path.exists():
             size_mb = file_path.stat().st_size / (1024 * 1024)
-            print(f"  - {filename} ({size_mb:.1f} MB)")
-    
+            print(f"  - {local_name} ({size_mb:.1f} MB)")
+
     return True
 
 
-def main():
-    parser = argparse.ArgumentParser(description="Download PrimateFace models from Google Drive")
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Download PrimateFace models from Hugging Face Hub"
+    )
     parser.add_argument(
         "output_dir",
         nargs="?",
         default=".",
-        help="Directory to save models (default: current directory)"
+        help="Directory to save models (default: current directory)",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Re-download even if files already exist",
     )
-    
+
     args = parser.parse_args()
-    
+
     try:
-        download_models(args.output_dir)
+        success = download_models(args.output_dir, force=args.force)
+        return 0 if success else 1
     except Exception as e:
         print(f"Error downloading models: {e}", file=sys.stderr)
         return 1
-    
-    return 0
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    sys.exit(main())

demos/model_registry.py

@@ -0,0 +1,2 @@
+"""Backward compatibility."""
+from primateface._model_registry import *  # noqa: F401,F403