mus-musculus-tracker 0.1.5

A YOLO-based tool for ROI cropping and movement tracking of Mus musculus.

Mus Musculus Tracker 🐁

A custom YOLO-based tool for automated mouse (Mus musculus) detection, movement tracking, and manual keypoint labeling.

📋 Features

• Automated Detection: Robust mouse tracking powered by YOLO (v12).
• Video Cropping and Compression: Automatically crops video borders to focus on the arena/cage and compresses them to 640x640 MP4.
• Trajectory Tracking: Extracts movement coordinates and trajectory data.
• Keypoints Labeling: Interactive script to label points p0..p9 on the first frame.
• CLI: Command-line interface.

🚀 Installation

Via Pip (Recommended)

pip install mus-musculus-tracker

Via Conda (Development)

gh repo clone juancolonna/mouse-tracker
cd mouse-tracker
conda env create -f environment.yml
conda activate mouse-tracker
pip install -e .

🛠 Usage

1) Mouse tracking (mouse-track)

mouse-track path/to/video.mp4

2) Keypoints labeling (keypoints-labeler)

The keypoints_labeler.py script reads a CSV list of videos, opens the first frame of each video, and requests manual selection of the 10 keypoints (p0 to p9).

keypoints-labeler path/to/video_list.csv path/to/output_keypoints.csv

Expected video_list.csv format:

• No header.
• One video path per line.
• Only one column is used.

Example video_list.csv:

/data/exp01/video_001.mp4
/data/exp01/video_002.mp4

Output (output_keypoints.csv):

• path_and_file column with the original video path.
• p0_x,p0_y,...,p9_x,p9_y columns.

Labeling behavior:

• Left-click to select the current point.
• Any key (e.g. ESC) other than q/Q moves to the next point.
• If you advance without clicking (e.g. press ESC twice without a mouse click), the current video is skipped.
• q or Q aborts the batch process.

Point order:

• p0 is the center.
• Points p0 -> p1 -> p2 go from the center toward the lid.
• p3..p9 follow a counter-clockwise order according to the figure.

📑 Requirements

• Python >= 3.13
• ultralytics
• opencv-python
• moviepy
• tqdm
• numpy

✍️ Authors

Juan G. Colonna [e-mail]
Instituto de Computação
Universidade Federal do Amazonas

📄 License

This project is licensed under the MIT License. See LICENSE for details.