Guns Detection with YOLOv8 + Streamlit + Email Alerts

This project is a real-time weapon detection demo built for a hackathon. It uses a pre-trained YOLOv8 model and a Streamlit UI to detect weapons in a live webcam stream. When a weapon is detected, the app captures the annotated frame and sends it via Gmail.

Disclaimer This app is a prototype meant for educational and demonstration purposes. Dataset is not public on purpose, because of violent content. All sample assets are sourced from openly available material, and the authors oppose any form of violence.

---

Features

• Live gun detection using a YOLOv8 model (gun_detection.pt)
• Streamlit UI with live-configurable confidence and IoU thresholds
• Gmail alert integration with throttling to avoid spamming
• Dataset download tooling (Roboflow) and evaluation notebooks

---

Project Structure

Gun_Detection_YOLOv8/
|-- app_m.py                # Streamlit app (productionized)
|-- gun_detection.pt        # YOLOv8 weights
|-- model_evaluation.ipynb  # Notebook: evaluate model accuracy
|-- testing_yolo.ipynb      # Notebook: run predictions on static images
|-- requirements.txt        # Python dependencies
|-- README.md
|-- .env.example            # Template for application configuration
|-- modules/
|   |-- DataFlow.py         # Roboflow dataset helper (expects secret/.env)
|   |-- email_client.py     # Gmail API wrapper
|   `-- settings.py         # Centralized configuration loader
|-- secret/
|   |-- credentials.json    # Gmail OAuth client secret (not committed)
|   |-- token.pkl           # OAuth token cache (generated on first run)
|   `-- .env                # Roboflow API key for DataFlow
|-- assets/                 # Sample media
`-- runs/                   # YOLO evaluation artifacts

---

Installation

1. Clone the repository

   git clone https://github.com/idemdnu/Guns-Detection-YOLOv8.git
   cd Guns-Detection-YOLOv8

2. Create your environment (recommended)

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

3. Install dependencies

   pip install -r requirements.txt

4. Configure Gmail API credentials

   • Create OAuth credentials in the Google Cloud console (Desktop App).
   • Place credentials.json inside the secret/ directory.
   • On the first app launch the browser-based OAuth flow will create secret/token.pkl.
   • Great tutorial how to setup Gmail API: https://mailtrap.io/blog/send-emails-with-gmail-api/

5. Create the application .env file

   copy .env.example .env  # Windows
   # cp .env.example .env  # macOS/Linux

   Update the values to point at your gun_detection.pt file and Gmail alert settings:

   MODEL_PATH=gun_detection.pt
   GMAIL_SCOPES=https://www.googleapis.com/auth/gmail.send
   GOOGLE_CREDENTIALS_PATH=secret/credentials.json
   GOOGLE_TOKEN_PATH=secret/token.pkl
   ALERT_EMAIL_RECEIVER=recipient@example.com
   ALERT_EMAIL_SUBJECT=Gun Detected!
   ALERT_EMAIL_BODY=A gun has been detected. See attached frame.
   ALERT_COOLDOWN_SECONDS=30
   RTC_STUN_SERVERS=stun:stun.l.google.com:19302

6. (Optional) Configure Roboflow access

   modules/DataFlow.py still expects a separate secret/.env with your Roboflow API key:

   API_KEY=your_roboflow_key

---

Run the Streamlit App

streamlit run app_m.py

• Start your webcam when prompted.
• Adjust confidence/IoU thresholds from the sidebar to tweak sensitivity.
• An email is sent at most once every ALERT_COOLDOWN_SECONDS when detections occur.

---

Model Evaluation (Roboflow)

from modules.DataFlow import DataFlow
from ultralytics import YOLO

df = DataFlow(workspace="your-workspace", project="weapon-detection", version=1)
dataset = df.download_dataset()

model = YOLO("gun_detection.pt")
results = model.val(data=f"{dataset.location}/data.yaml", save_json=True)
print(results.box.map50)  # Example metric access

---

Email Alerts

• modules/email_client.py encapsulates the Gmail API logic and token caching.
• All sensitive paths and recipient details are loaded via modules/settings.py, which reads .env.
• Update the .env file (instead of the code) whenever you need to change the recipient, subject, cooldown, or STUN servers.

---

Requirements

See requirements.txt for the full list. Key packages:

• ultralytics
• streamlit
• streamlit-webrtc
• opencv-python
• python-dotenv
• google-api-python-client and related Gmail auth libraries
• roboflow
• av