🦌 ADIS: Animal Intrusion Detection System

ADIS (Animal Intrusion Detection System) is a high-performance, end-to-end framework for detecting and identifying animals in various environments. Built on the YOLOv11 architecture, it provides advanced tools for training, hyperparameter optimization, and rigorous statistical validation.

---

Figure 1: Sample detection output highlighting real-time animal identification with high confidence.

---

🚀 Key Features

• 🎯 YOLOv11 Integration: Full support for the YOLOv11 family (Nano to Extra-Large) via the custom YOLO11Model wrapper.
• 🧪 Statistical Significance Testing: Built-in suite for comparing model variants (Wilcoxon, paired t-test, Friedman, Kruskal-Wallis).
• 🧠 Hyperparameter Tuning: Integrated support for Optuna and BOHB (Bayesian Optimization and HyperBand) optimization.
• 📊 Comprehensive Analytics: Per-class IoU and accuracy diagnostics, confusion matrices, and COCO/LVIS metrics.
• 📓 Workflow Notebooks: Purpose-built Jupyter notebooks for seamless Training, Tuning, and Evaluation.
• 🛡️ Production Ready: Supports export to multiple formats (ONNX, TensorRT, etc.) for optimized deployment.

---

📂 Repository Structure

The project is modularly designed to separate model architecture from training orchestration:

• model.py: Primary API. A user-friendly façade for training, predicting, and exporting models.
• detector.py: Core logic for building the detection network from YAML specifications.
• blocks.py: Neural network building blocks (C3k2, C2f, SPPELAN, etc.).
• trainer.py: Custom training engine with DDP, EMA, and advanced scheduling support.
• validator.py: Metric accumulation and validation loop with per-class diagnostics.
• statistical_tests.py: Evaluation suite for academic-grade performance validation.
• config/: Model architecture definitions (YAML) for various YOLO11 scales.
• assets/: Project assets and sample media.

---

⚙️ Installation

1. Requirements

Ensure you have Python 3.8+ and a compatible PyTorch version installed (matching your CUDA setup).

2. Setup Environment

# Create and activate virtual environment (Windows/PowerShell)
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# Upgrade pip and install dependencies
python -m pip install --upgrade pip
pip install -r requirements.txt

3. Optional Dependencies

For COCO metadata export or LVIS evaluation:

pip install pycocotools lvis

---

🏁 Quick Start

Training

Start training with a single command using the YOLO11Model API:

from model import YOLO11Model

# Initialize a new nano model
model = YOLO11Model('config/yolo11n.yaml')

# Train on your custom data
model.train(data='data.yaml', epochs=100, imgsz=640, batch=16)

Statistical Evaluation

Compare multiple checkpoints to ensure performance gains are statistically sound:

from statistical_tests import evaluate_all_models, run_all_significance_tests

model_checkpoints = {
    "Baseline": "weights/baseline.pt",
    "Tuned-BOHB": "weights/bohb_tuned.pt"
}

# Run per-class evaluation and significance tests
results = evaluate_all_models(model_checkpoints, data_yaml="data.yaml")
run_all_significance_tests(results)

Inference

model = YOLO11Model('runs/detect/train/weights/best.pt')
results = model.predict('forest_scene.jpg', conf=0.5)
results[0].show()

---

🐆 Supported Classes

ADIS is pre-configured to detect 10 unique animal classes in the balanced_dataset:

• Cat | Cattle | Chicken | Deer | Dog
• Squirrel | Eagle | Goat | Rodents | Snake

---

📑 Acknowledgements & Citation

This project is built upon the foundational work by the Ultralytics team and use tools like Optuna for advanced optimization.

Note

If you use this repository in your research, please cite our corresponding publication (Pending/PeerJ): Placeholder: Sathish Kumar et al., "Animal Intrusion Detection using Optimized YOLOv11 and BOHB Tuning", 2024.

---

⚖️ License

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

---

Made with ❤️ for Animal Wildlife Conservation