Tahr Guardian — Wildlife & Intruder Detection

Computer-vision monitoring for endangered Arabian Tahr conservation: detect and count the species, flag human/animal intruders, and classify habitat from field-camera and drone footage.

Overview

Tahr Guardian is a computer-vision pipeline built for wildlife conservation and anti-poaching monitoring for a wildlife reserve on the Arabian Peninsula. It analyzes video from field cameras and drones to:

• Detect and count the endangered Arabian Tahr in each frame.
• Flag intruders — humans and donkeys — that should not be present in protected habitat.
• Classify the surrounding habitat (Desert, Greenland, Snow) directly from the imagery.

Detection uses an Ultralytics YOLO model (trained with both YOLOv8 and YOLOv11), habitat classification uses OpenAI CLIP (zero-shot, via text prompts), and tracking uses an OpenCV CSRT tracker to assign stable IDs and avoid double-counting across frames. The repository also includes an experimental self-improving loop that saves low-confidence detections and periodically retrains the model on them.

Features

• Tahr detection & counting — bounding boxes, per-frame counts, and on-screen overlays.
• Intruder alerting — humans and donkeys are labelled as intruders with separate counts and console notifications per frame.
• Habitat classification — zero-shot CLIP (ViT-B/32) maps each frame to Desert, Greenland, or Snow from natural-language descriptions.
• Multi-object tracking — OpenCV CSRT trackers assign consistent IDs for unique-object counting.
• Self-improving retraining (experimental) — low-confidence detections are cropped and saved in YOLO label format, then used to periodically retrain the model.
• Evaluation tooling — confusion-matrix generation plus full YOLOv8 / YOLOv11 training artifacts (PR/F1 curves, results, confusion matrices) under trainYOLOV8/ and trainYOLOV11/.
• Annotated video output — processed frames are written to an output video with all overlays.

Tech Stack

• Language: Python
• Detection: Ultralytics YOLO (YOLOv8 & YOLOv11)
• Classification: OpenAI CLIP (ViT-B/32)
• Vision / video I/O: OpenCV
• ML / numerics: PyTorch, NumPy, scikit-learn
• Visualization: Matplotlib, Pillow

Project Structure

.
├── intruder.py             # Detection + intruder flagging + CLIP habitat classification
├── Intruder_Learning.py    # Same pipeline + self-improving low-confidence retraining loop
├── tracking.py             # YOLO detection + CSRT tracking for unique Tahr counting
├── trainYOLOV8/            # YOLOv8 training run (args, metrics, curves, confusion matrices)
├── trainYOLOV11/           # YOLOv11 training run (args, metrics, curves, confusion matrices)
└── YOLOV8/                 # (placeholder)

Setup

1. Clone

git clone https://github.com/ube09/Tahr-Guardian.git
cd TahrGuardian

2. Create a virtual environment

python -m venv env
# Windows:
env\Scripts\activate
# macOS / Linux:
source env/bin/activate

3. Install dependencies

pip install --upgrade pip
pip install opencv-python ultralytics numpy torch torchvision clip scikit-learn matplotlib Pillow

A CUDA-capable GPU is recommended but optional — the code falls back to CPU automatically.

4. Add model weights and input video

• Place your trained YOLO weights (e.g. v11.pt) in the project root, or update the YOLO_WEIGHTS_PATH constant in the script you run.
• Set the input video path via VIDEO_PATH and the output path via OUTPUT_VIDEO_PATH.

Run

Detection + intruder flagging + habitat classification:

python intruder.py

Detection + self-improving retraining loop:

python Intruder_Learning.py

Detection + CSRT tracking for unique Tahr counting:

python tracking.py

Each script displays processed frames in a window (press q to quit early) and writes an annotated output video to disk.

Configuration

Key constants are set at the top of each script:

• VIDEO_PATH, OUTPUT_VIDEO_PATH, YOLO_WEIGHTS_PATH
• Confidence thresholds (detection cutoff, and the low-confidence threshold for retraining)
• class_names, colors, and the habitat_descriptions / habitat_names used by CLIP

Results

Trained on a custom Tahr dataset (25 epochs). Final validation metrics:

Model	Precision	Recall	mAP@50	mAP@50-95
YOLOv11	~0.96	~0.94	~0.97	~0.60
YOLOv8	~0.97	~0.94	~0.97	~0.59

See trainYOLOV8/ and trainYOLOV11/ for full curves, confusion matrices, and results.csv.

Author

Usama Bin Ejaz — AI/ML Engineer | Data Scientist | Founder, UBE Labs

• GitHub: github.com/ube09
• Website: usamabinejaz.com