Smoking Detection Pipeline

A robust, multi-stage computer vision pipeline designed to detect smoking events in video files or real-time RTSP streams. The system uses a cascade of YOLO models to ensure high precision and low false positives.

🏗 Architecture

The pipeline operates in a "Fail-Fast" cascade to optimize performance:

1. Broad Phase (Person Detection):

   • Detects humans in the frame.
   • Optimization: If no people are found, processing stops for that frame.

2. Narrow Phase (Cigarette Candidate Detection):

   • Crops the detected person (with a 20% margin for context).
   • Runs a specialized YOLO detector to find small objects (cigarettes/lighters).
   • Filter: Rejects candidates smaller than 10x10 pixels.

3. Verification Phase (Classification):

   • Crops the candidate object.
   • Runs a dedicated Binary Classifier to verify "Smoking" vs "Not Smoking".
   • Output: Only high-confidence events are flagged as alerts.

🚀 Usage

Prerequisites

• Python 3.12+
• Dependencies: ultralytics, opencv-python, numpy

Running the Pipeline

Run the entry point main.py with your video source:

# Run on a local video file
python main.py --source videos/test_footage.mp4

# Run on an RTSP stream
python main.py --source rtsp://admin:[email protected]:554/stream --rtsp

# Enable debug logging (see frame-by-frame details)
python main.py --source videos/test.mp4 --debug

CLI Arguments

Argument	Default	Description
--source	Required	Path to video file or RTSP URL.
--rtsp	False	Set this flag if the source is an RTSP stream (enables threaded reading).
--output	output.mp4	Path for the annotated output video.
--person-model	models/human-det-best.pt	Path to the Person Detection YOLO model.
--cig-model	models/cig-det-best.pt	Path to the Cigarette Detection YOLO model.
--verify-model	models/cig-cls-best.pt	Path to the Verification/Classifier model.
--debug	False	Enable verbose logging.

📊 Outputs

The system generates three types of artifacts during execution:

1. Visual Debug (output.mp4):

   • A video file with bounding boxes drawn for all stages.
   • Blue: Detected Person.
   • Yellow: Cigarette Candidate.
   • Red: Confirmed Smoking Event.

2. Frame Metadata (output.jsonl):

   • A synchronized JSON Lines file containing raw detection data for every frame.
   • Useful for debugging model performance or retraining.

3. Alert Log (alerts.jsonl):

   • A structured log file containing only confirmed smoking events.
   • Use this file to trigger external notifications or audit logic.

📂 Project Structure

gp/
├── main.py                  # CLI Entry point
├── models/                  # Directory for .pt model weights
├── pipeline/
│   ├── core.py              # Main logic loop (Pipeline class)
│   ├── models.py            # Ultralytics model wrappers
│   ├── sources.py           # Stream inputs (File vs RTSP)
│   ├── outputs.py           # Sinks (VideoWriter, JSONL logger)
│   ├── protocols.py         # Interfaces (Model, Verifier, etc.)
│   └── types.py             # Data classes (Frame, Detection, Ticket)