mus-musculus-tracker 0.1.6

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) Basic Use of Mouse tracking (mouse-track)

Run mouse-track with a single video file:

mouse-track path/to/video.mp4

For batch mode, provide a CSV file containing the list of videos (one video per row):

mouse-track path/to/list_of_videos.csv

Use the -y flag to automatically accept confirmation prompts:

mouse-track -y path/to/video.mp4

or, in batch mode:

mouse-track -y path/to/list_of_videos.csv

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.

3) Batch Tracking Mode (mouse-track)

For processing multiple videos with pre-labeled keypoints, use a CSV file containing video paths and their keypoints:

mouse-track -y path/to/keypoints_list.csv

Expected keypoints_list.csv format:

• Header row: path_and_file,p0_x,p0_y,p1_x,p1_y,...,p9_x,p9_y
• Each subsequent row: video path followed by 20 numeric values (x,y pairs for p0-p9)

Example keypoints_list.csv:

path_and_file,p0_x,p0_y,p1_x,p1_y,p2_x,p2_y,p3_x,p3_y,p4_x,p4_y,p5_x,p5_y,p6_x,p6_y,p7_x,p7_y,p8_x,p8_y,p9_x,p9_y
/data/exp01/video_001.mp4,320,240,315,235,310,230,325,245,330,250,335,255,340,260,345,265,350,270,355,275
/data/exp01/video_002.mp4,320,240,315,235,310,230,325,245,330,250,335,255,340,260,345,265,350,270,355,275

This mode automatically crops and tracks all videos in the list without manual interaction. The script will prompt for confirmation before starting the batch process.

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