Metadata-Version: 2.4
Name: mus-musculus-tracker
Version: 0.1.5
Summary: A YOLO-based tool for ROI cropping and movement tracking of Mus musculus.
Author-email: "Juan G. Colonna" <juancolonna@icomp.ufam.edu.br>
License-Expression: MIT
Project-URL: Homepage, https://github.com/juancolonna/mouse-tracker
Project-URL: Repository, https://github.com/juancolonna/mouse-tracker.git
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ultralytics>=8.4.5
Requires-Dist: moviepy>=2.2.1
Requires-Dist: opencv-python>=4.12.0
Requires-Dist: tqdm>=4.67.1
Requires-Dist: numpy>=2.1.3
Dynamic: license-file

# Mus Musculus Tracker 🐁

[![PyPI version](https://img.shields.io/pypi/v/mus-musculus-tracker.svg)](https://pypi.org/project/mus-musculus-tracker/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)

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

<img src="assets/tracking.png" alt="Tracking" width="50%" />


## 📋 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)

```bash
pip install mus-musculus-tracker
```

### Via Conda (Development)

```bash
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`)

```bash
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`).

```bash
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`:

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


![Keypoints reference](assets/keypoints.png)

## 📑 Requirements

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

## ✍️ Authors

Juan G. Colonna <juancolonna@icomp.ufam.edu.br>  
Instituto de Computação  
Universidade Federal do Amazonas

## 📄 License

This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
