---
license: agpl-3.0
tags:
  - computer-vision
  - mouse
  - grimace-scale
  - animal-welfare
  - neuroscience
  - pain-assessment
  - pose-estimation
  - object-detection
  - vision-transformer
  - yolo
---

# GrimACE models

Model weights for the **GrimACE** application — automated scoring of the **Mouse Grimace Scale (MGS)**
from front-camera video, with optional overhead pose tracking.

These are the trained weights that power the GrimACE Recorder app. The application can record from the
GrimACE box cameras **or process existing video files**. See the application and full instructions here:

➡️ **Application & source:** https://github.com/ryanwitzman/GrimACE (the `GrimaceRecorder` directory)

## Files

| File | Purpose | Architecture |
|---|---|---|
| `frame_quality.pt` | Scores how suitable a frame is for grimace scoring (mouse facing the camera, in focus). | MobileNetV3 (1-channel) |
| `face_cropper.pt` | Detects and crops the mouse face from a frame. | YOLO (Ultralytics) |
| `grimace_scorer.pt` | Scores the 5 grimace action units (orbital tightening, nose bulge, cheek bulge, ear position, whisker change). | Vision Transformer (ViT-B/16) |
| `top_pose_estimator.pt` | Pose / keypoint tracking from the overhead (top) camera. | YOLO-Pose (Ultralytics) |
| `top_pose_estimator_l.pt` | Larger pose tracking model. | YOLO-Pose (Ultralytics) |
| `top_pose_keypoints.txt` | Keypoint names for the pose models. | text |

The models expect **grayscale** input (the GrimACE box uses monochrome cameras); the application
converts color video to grayscale automatically.

## How to use

1. Clone / download the GrimACE Recorder application (link above).
2. Download all the files in this repository.
3. Place them in the `models/` folder inside `GrimaceRecorder`:
   ```
   GrimaceRecorder/
   └── models/
       ├── frame_quality.pt
       ├── face_cropper.pt
       ├── grimace_scorer.pt
       ├── top_pose_estimator.pt
       ├── top_pose_estimator_l.pt
       └── top_pose_keypoints.txt
   ```
4. Follow the install and usage instructions in the application's README, then run `python main.py`.

You can download the whole repository with the `huggingface_hub` library:

```python
from huggingface_hub import snapshot_download

snapshot_download(
    repo_id="rwitz/GrimACE",
    local_dir="GrimaceRecorder/models",
)
```

### Note: mouse-face verification

The application has an optional **Mouse Face Check** that rejects detections which aren't actually a
mouse face (lab equipment, cage hardware, reflections). That feature uses a general SigLIP
vision-language model (`google/siglip2-so400m-patch16-384`), which is downloaded automatically from
Hugging Face the first time the check is enabled — it is **not** part of this repository.

## Intended use

These models are intended for research on the Mouse Grimace Scale. They were trained on GrimACE-box
front-camera footage; performance on footage that differs from that setup (different framing, lighting,
or coat color) may be reduced. The application provides adjustable thresholds and a contrast-enhancement
option to help adapt to such footage, and saves the chosen frames so results can be reviewed.

## License

Released under the **GNU Affero General Public License v3.0 (AGPL-3.0)**, matching the GrimACE
application.