Metadata-Version: 2.4
Name: mus-musculus-tracker
Version: 0.1.3
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.88
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 professional **YOLO-based** tool designed for automated detection, Region of Interest (ROI) cropping, and movement tracking of mice (*Mus musculus*) in a circular arena.

## 📋 Features

- **Automated Detection:** Powered by YOLO (v.12) for robust mice tracking.
- **Smart ROI Cropping:** Automatically crops video borders to focus on the arena/cage.
- **Trajectory Tracking:** Extracts movement data and tracking coordinates.
- **CLI Ready:** Easy-to-use Command Line Interface.

## 🚀 Installation

### Via Pip (Recommended)
You can install the tracker directly from PyPI:

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

### Via Conda (For Development)
To set up a development environment, use the provided environment.yml:

```bash
gh repo clone juancolonna/mouse-tracker
cd mouse-tracker
conda env create -f environment.yml
conda activate mouse-tracker
pip install mus-musculus-tracker
```

## 🛠 Usage
Once installed, the mouse-track command will be available in your terminal. To start tracking on a video file, simply run:

```bash
mouse-track path/to/your/video.mp4
```

## 📑 Requirements
Python: >= 3.13

Main Dependencies:
- ultralytics (YOLO)
- opencv-python
- moviepy
- tqdm

## ✍️ 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 the LICENSE file for details.
