Weapon Detection and Alarm System

By using Ultralytics YOLO real-time weapon detection with tracking, cooldown-based alerts, persistence filtering, and multi-channel notifications (Email, Telegram). This Repo also Supports VLMs (LLaVA, PaliGemma, Qwen) for better insights of the incidents .

Quick Start

Clone and Install

git clone https://github.com/K-saif/Weapon-Detection-and-Alarm-System.git
cd Weapon-Detection-and-Alarm-System
pip install -r requirements.txt

Notes:

• ultralytics is required for the detection pipeline.
• requests is required for Telegram alerts.
• transformers and accelerate are needed for VLM features.

Setup Alerts

Gmail Setup

1. Enable 2-Step Verification in your Google Account
2. Go to App Passwords (search in account settings)
3. Generate a new app password for "Mail"
4. Use this 16-character password as ALERT_EMAIL_PASS

Telegram Setup

1. Message @BotFather on Telegram → send /newbot
2. Follow prompts to name your bot and get the bot token
3. Start a chat with your bot (send any message)
4. Visit https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
5. Find "chat":{"id":XXXXXX} — that number is your chat ID

Create a .env file in the weapon_detection/ folder:

# weapon_detection/.env

# Email Configuration
ALERT_SMTP_SERVER=smtp.gmail.com
ALERT_SMTP_PORT=587
ALERT_EMAIL_SENDER=youremail@gmail.com
ALERT_EMAIL_PASS=your_16char_app_password
ALERT_EMAIL_RECEIVER=alert_receiver@gmail.com

# Telegram Configuration
ALERT_TELEGRAM_BOT_TOKEN=your_bot_token
ALERT_TELEGRAM_CHAT_ID=your_chat_id

Tip: Leave a value empty to disable that channel.

Supported Inputs

Input	source
Webcam	0 (default)
Video file	path/to/video.mp4
RTSP stream	rtsp://user:pass@ip:554/stream
HTTP stream	http://ip:8080/video

Single images and image directories are not supported — the pipeline requires a continuous frame stream.

Run Detection

# Webcam
python main.py source=0 conf=0.8 device=cpu

# Video file
python main.py source=path/to/video.mp4 conf=0.8 device=cpu

# RTSP camera
python main.py source=rtsp://user:pass@192.168.1.10:554/stream device=gpu

Alert Logic

The pipeline includes:

• Persistence gating: object must appear for persist_frames before alert.
• Cooldown timer: same track alerts again only after cooldown seconds.
• Stale cleanup: track state is removed after stale_frames missing frames.
• Async dispatch: alert channels run concurrently via thread pool.

Note: keep cooldown high to avoid spamming alerts, especially in crowded scenes.

Visual Language Models (VLMs)

The system can query VLMs for enhanced incident insights. below is an example of how to enable VLM querying for detected weapons:

python main.py source=path/to/video.mp4 conf=0.8 device=cgpu use_vlm=True vlm_model=qwen

Image:

Qwen Description: The person holding the weapon is a man standing in a pharmacy. He is wearing a baseball cap with black t-shirt and jeans. The man appears to be holding a small pistol or a similar weapon, which is pointed towards another person.

Training Custom Models

Dataset

you can download the Weapon Detection Dataset used for training you own model. It contains annotation of weapons with a total of 10330 images of various weapons in different environments and total object annotations of 11,056 in YOLO format.

After downloading, unzip the dataset and use the train/images and train/labels folders for training configure path into data.yaml. You can also augment the dataset with your own images and annotations to improve performance.

Model Test Results

The pre-trained model (best.pt) achieves excellent performance on the test set:

Metric	Value
Images	1573
Instances	1636
Precision (P)	0.988
Recall (R)	0.976
mAP50	0.991
mAP50-95	0.857

These metrics demonstrate high detection accuracy with strong generalization across different environments.

Project Structure

├── main.py
├── models/
│   └── best.pt
├── weapon_detection/
│   ├── __init__.py
│   ├── cli.py
│   ├── config.py
│   ├── events.py
│   ├── channels.py
│   ├── dispatcher.py
│   ├── tracking.py
│   ├── runner.py
│   └── vlm.py
├── app.py
├── requirements.txt
├── README.md
├── DASHBOARD_README.md
└── LICENSE

Dashboard UI

A web-based dashboard to provide real-time monitoring and visualization of weapon detection events. The dashboard offers:

• Real-time video feed with detection overlays
• Live alert notifications and history
• System configuration and management interface
• Detection statistics and insights
• Easy access to incident snapshots and logs

Check the Dashboard README for setup and usage details.

CLI Options

Argument	Type	Default	Description
weights	str	models/best.pt	Path to the YOLO model weights file.
source	int/ str	0	Video input source (webcam index, file path, RTSP/HTTP stream URL).
device	str	cpu	Inference device: cpu or gpu.
conf	float	0.4	Detection confidence threshold.
alert_classes	list[int]	0	Class IDs that trigger alerts (comma-separated in CLI, e.g., 0,1).
persist_frames	int	8	Frames required before the first alert for a tracked object.
cooldown	int	60	Seconds to wait before alerting again for the same track.
stale_frames	int	30	Missing frames before tracked state is removed.
output_dir	str	alerts	Directory used for saved snapshots and alert artifacts.
workers	int	4	Maximum async worker threads for alert channels.
use_vlm	bool	false	Enable VLM querying for detected weapons.
vlm_model	str	paligemma	VLM backend to use: llava, paligemma, or qwen.

Example:

python main.py source=0 device=cpu conf=0.8 output_dir=alerts

Future Enhancements

• Add person detection and tracking to correlate weapons with individuals.
• Support for lightweight models like onnx or tflite for edge deployment.
• Dockerization for easier setup and deployment.
• Multi-camera support with centralized alert management.

Contributing

Contributions are welcome! Please open an issue or submit a pull request for bug fixes, improvements, or new features.

Star History

License

This project is licensed under the MIT License.

please consider starring the repository if you find it useful! ⭐