Update reamde

2026-01-07 02:53:45 +07:00
1 parent b2f4b4f748
commit b5ea0232f7
@@ -0,0 +1,94 @@
+# 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:
+
+```bash
+# 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
+
+```text
+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)
+```