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:

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.