| --- |
| 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. |
