🐁 feat(repro): add official implementation of DeepRodent

README.md

@@ -1,3 +1,169 @@
 ---
 license: apache-2.0
+tags:
+  - object-detection
+  - instance-segmentation
+  - oriented-bounding-box
+  - yolo
+  - computer-vision
+  - computational-biology
+  - rodent-monitoring
+  - experimental-biology
+library_name: ultralytics
+pipeline_tag: image-segmentation
 ---
+
+<div align="center">
+
+# 🐭 DeepRodent
+
+### A Robust and Generalizable Vision Framework for Automated Rodent Monitoring in Experimental Biology
+
+**Teerapong Panboonyuen** ([@kaopanboonyuen](https://github.com/kaopanboonyuen))
+
+Department of Computer Science, Khon Kaen University · PBYAIL · Chulalongkorn University
+
+📧 teerapong.panboonyuen@gmail.com
+
+[![GitHub](https://img.shields.io/badge/GitHub-Code-181717?style=for-the-badge&logo=github)](https://github.com/kaopanboonyuen/DeepRodent)
+[![Project Page](https://img.shields.io/badge/🌐-Project%20Page-blue?style=for-the-badge)](https://kaopanboonyuen.github.io/DeepRodent)
+[![Demo](https://img.shields.io/badge/🤗-Live%20Demo-yellow?style=for-the-badge)](https://huggingface.co/spaces/kaopanboonyuen/DeepRodent-Demo)
+[![License](https://img.shields.io/badge/License-Apache%202.0-green?style=for-the-badge)](LICENSE)
+
+</div>
+
+---
+
+## ✨ Overview
+
+**DeepRodent** is a unified, detector-agnostic deep learning framework built for **precise, generalizable, multi-task rodent monitoring** in laboratory environments. It jointly predicts:
+
+- 📦 **Standard object detection**
+- 🔄 **Oriented Bounding Boxes (OBB)** — captures rotation during grooming, rearing, and huddling
+- 🎨 **Pixel-level instance segmentation** — accurate boundary masks even under occlusion
+- 🧭 **Temporal-consistent behavioral embeddings** — stable identity tracking across video frames
+
+Rather than bolting these on separately, DeepRodent fuses them into a single-stage, multi-head architecture — so one forward pass gives you everything downstream biology pipelines need.
+
+<div align="center">
+
+| 🎯 Metric | 🥇 DeepRodent | Best Baseline (YOLO12-Seg) | 📈 Gain |
+|:---:|:---:|:---:|:---:|
+| mAP₅₀ | **96.2** | 94.4 | +1.8 |
+| mAP₅₀₋₉₅ | **84.6** | 78.2 | **+6.4** |
+| Cross-domain (Lab C) | **91.5** | 87.2 | +4.3 |
+| FPS (real-time) | 154 | 156 | — |
+
+</div>
+
+---
+
+## 🚀 Quick Start
+
+```bash
+pip install ultralytics
+```
+
+```python
+from ultralytics import YOLO
+
+# 🐭 Load DeepRodent
+model = YOLO("DeepRodent_WEIGHT.pt")
+
+# 🔍 Run inference
+results = model.predict("your_cage_image.jpg", save=True)
+
+# 🎨 Visualize instance masks + OBB
+results[0].show()
+```
+
+### 📥 Download directly
+
+```python
+from huggingface_hub import hf_hub_download
+
+weight_path = hf_hub_download(
+    repo_id="kaopanboonyuen/DeepRodent",
+    filename="DeepRodent_WEIGHT.pt"
+)
+```
+
+---
+
+## 🧠 Why DeepRodent?
+
+| Challenge in the Lab 🔬 | How DeepRodent Solves It 💡 |
+|---|---|
+| Rodents curl, rear, and huddle | Oriented Bounding Boxes capture true rotation |
+| Axis-aligned boxes overlap during interaction | Instance segmentation isolates each animal precisely |
+| Lighting/cage geometry varies across labs | Cross-domain robustness constraint for generalization |
+| Jittery masks across video frames | Temporal consistency loss stabilizes identity tracking |
+| Need for downstream analytics | Direct output → trajectories, heatmaps, behavior states |
+
+---
+
+## 🏗️ Architecture Snapshot
+
+```
+Input Frame → Shared Backbone → ┬── Detection Head
+                                 ├── OBB Head (θ-aware)
+                                 ├── Instance Seg Head
+                                 └── Temporal Embedding Head
+                                          ↓
+                        Trajectory Tracking · Behavior States · Occupancy Heatmaps
+```
+
+Detector-agnostic: plug into **YOLOv8 → YOLO12** families and gain **+2.6 to +3.1 mAP** consistently. 🔌
+
+---
+
+## 📊 Benchmarks
+
+Evaluated on a private multi-setting laboratory rodent dataset (~30K annotated frames, 60/20/20 split):
+
+- 🥇 Outperforms **RT-DETR** by **+6.7 mAP₅₀₋₉₅**
+- 🥇 Outperforms **Mask R-CNN** by **+13.5 mAP₅₀₋₉₅**
+- ⚡ Maintains **154 FPS** — real-time, deployment-ready
+
+Full ablation, cross-domain, and SOTA comparison tables are in the [paper](https://kaopanboonyuen.github.io/DeepRodent).
+
+---
+
+## 📁 Repository Links
+
+| Resource | Link |
+|---|---|
+| 💻 Code | [github.com/kaopanboonyuen/DeepRodent](https://github.com/kaopanboonyuen/DeepRodent) |
+| 🌐 Project Page | [kaopanboonyuen.github.io/DeepRodent](https://kaopanboonyuen.github.io/DeepRodent) |
+| 🤗 Weights (this repo) | `DeepRodent_WEIGHT.pt` |
+| 🎮 Interactive Demo | [Hugging Face Spaces](https://huggingface.co/spaces/kaopanboonyuen/DeepRodent-Demo) |
+
+---
+
+## 🐾 Ethical Use
+
+DeepRodent is an **assistive research tool** — it does not replace veterinary oversight or trained behavioral experts. Developed following **ARRIVE guidelines** and the **3Rs principles** (Replacement, Reduction, Refinement). Please validate performance before deployment in a new laboratory setting.
+
+---
+
+## 📜 Citation
+
+If DeepRodent helps your research, please cite:
+
+```bibtex
+@article{panboonyuen2026deeprodent,
+  title   = {DeepRodent: A Robust and Generalizable Vision Framework for Automated Rodent Monitoring in Experimental Biology},
+  author  = {Panboonyuen, Teerapong},
+  year    = {2026}
+}
+```
+
+---
+
+<div align="center">
+
+Made with 🧡 for open, reproducible science.
+
+⭐ **If this helped your research, consider starring the [GitHub repo](https://github.com/kaopanboonyuen/DeepRodent)!**
+
+</div>