How sayedgamal99/real-time-smoke-fire-detection-yolo11 works
1. Repository purpose
- This is a Python-based real-time smoke/fire detection system built around a YOLOv11 object detection model.
- The core runtime takes image/video input, detects Fire and Smoke, and then triggers alerts through messaging channels.
2. Primary runtime path
- The main execution path is centered in src/main.py.
- That entry point likely wires together:
- model loading,
- frame/video ingestion,
- detection post-processing,
- alerting/notification dispatch.
- src/fire_detector.py is the main detection domain module.
3. Detection subsystem
- src/fire_detector.py is the core inference boundary.
- It likely encapsulates:
- loading YOLO weights from models/,
- running inference on frames/images/videos,
- filtering detections by confidence/IOU,
- formatting detection results for downstream use.
- The repository ships several pretrained weights, with models/best_nano_111.pt appearing to be the default small production-oriented model.
4. Alerting / notification subsystem
- src/notification_service.py is the notification boundary for external alerts.
- From the README and file naming, this service is intended to send detection evidence to messaging platforms such as Telegram and possibly WhatsApp.
- The system is therefore not just a detector; it is an event-driven safety monitor that turns detections into outbound notifications.
5. Bot integration
- src/bot.py suggests a Telegram bot integration layer, separate from the core detector.
- This implies a split between:
- detection logic,
- messaging/bot transport,
- possibly user interaction or command handling.
- Keeping bot code separate from detection code is an important architectural boundary.
6. Configuration and user gating
- src/config.py holds runtime configuration, likely including model paths, confidence thresholds, API tokens, and channel-specific settings.
- src/check_users.py indicates some form of access control or recipient validation, probably to ensure only approved users receive bot notifications or can interact with the service.
7. Data flow
- Input sources include sample media in data/ and live camera/webcam sources described in the README.
- Frames are processed by the detector, detections are written or copied to an output area such as detected_fires/, and then notification payloads are sent through the messaging layer.
- The key pipeline is: video/image input → YOLO detection → event classification as fire/smoke → evidence capture → notification.
8. Model and experiment assets
- models/ contains multiple trained YOLO weights at different sizes (nano, small, medium, large) and a Kaggle-developed set.
- This suggests the architecture supports model swapping for different latency/accuracy tradeoffs.
- The README emphasizes real-time performance, so smaller models are likely used for deployment, while larger ones are available for experimentation.
9. Frontend / presentation layer
- index.html and styles.css indicate a simple static presentation layer.
- This is likely used as a landing page or demo page rather than the main runtime.
- It is architecturally separate from detection/notification logic and does not appear to be the core product surface.
10. Generated outputs
- detected_fires/ is an output artifact area, probably storing captured images or annotated frames when a fire/smoke event is detected.
- This folder supports human verification and provides the visual evidence attached to alerts.
11. Training and notebooks
- notebook/smoke-fire-detection-yolo11.ipynb captures the training/experimentation workflow.
- This notebook is an offline ML development asset, distinct from the production inference path.
- The repository therefore has both model development and model serving/inference concerns, but they are kept in separate areas.
12. Testing structure
- tests/ covers detector behavior, notification behavior, integration paths, and label/data cleanup utilities.
- The presence of tests/test_data/ with label edge cases suggests validation around dataset preprocessing and annotation correctness.
- This test suite protects both ML-adjacent logic and the notification pipeline, which is important for a system that depends on external alerts.
13. External dependencies and runtime profile
- The project is Python-based and uses Ultralytics YOLOv11 as the key ML runtime.
- The README also references Telegram and WhatsApp integrations, so the system depends on external messaging APIs/services.
- That means the architecture has two critical external boundaries: model inference and messaging delivery.
14. Overall architectural shape
- Conceptually, this is a single-machine inference service with outbound alerting, not a distributed backend.
- The major subsystems are:
- inference engine,
- alert/notification layer,
- configuration/access control,
- model/data assets,
- offline training notebooks,
- tests and validation fixtures.
- For an architecture diagram, the main emphasis should be on the real-time media processing pipeline and its notification side effects.
Main entry points: fire_detector.py Detector · main.py Main · test_integration.py Test Suite · notification_service.py Alerts
Components 17
Runtime
Real-time detection and alerting path
- Main · Application entrypoint wiring the live pipeline
src/main.py - Config · Runtime thresholds, paths, and credentials
src/config.py - Detector · YOLO-based fire and smoke inference boundary
src/fire_detector.py - Alerts · Outbound notification service for detections
src/notification_service.py - Bot · Telegram-facing transport and command layer
src/bot.py - Users · Recipient validation and user gating
src/check_users.py - Landing Page · Static demo or informational front end
index.html
Assets
Models, sample media, and generated evidence
- Video Input · Sample video and live camera inputs
data/video.mp4 - Fire Clips · Example fire-bearing video assets
data/gen_fire.mp4 - Default Weights · Primary production-oriented YOLO model
models/best_nano_111.pt - Model Variants · Alternative YOLO checkpoints for tradeoffs
models/kaggle developed models/best_small.pt - Detected Fires · Annotated frames and captured evidence for review
detected_fires/README.md
Offline ML
Training and experimentation workflow
- Notebook · Offline training and experimentation workflow
notebook/smoke-fire-detection-yolo11.ipynb
Tests
Validation and regression coverage
- Test Suite · Core regression tests for detection and notifications
tests/test_integration.py - Detector Tests · Focused coverage for inference behavior
tests/test_fire_detector.py - Alert Tests · Coverage for notification delivery logic
tests/test_notification_service.py - Label Fixtures · Edge-case annotation data for cleanup validation
tests/test_data/train/labels/test_valid.txt
Connections 18
- Main → Config: loads · Reads runtime configuration and paths
- Main → Detector: starts · Creates the inference pipeline
- Main → Alerts: connects · Initializes outbound alerting
- Main → Bot: routes · Wires messaging transport into the app
- Detector → Default Weights: uses · Loads the default YOLO checkpoint
- Detector → Model Variants: can swap · Supports alternate model sizes
- Main → Video Input: reads · Consumes video or camera frames
- Video Input → Detector: frames · Supplies media to inference
- Fire Clips → Detector: examples · Representative fire scenarios for evaluation
- Detector → Detected Fires: writes · Stores annotated captures and event evidence
- Detector → Alerts: triggers · Emits fire/smoke events for alerting
- Alerts → Bot: dispatches · Sends alerts through the bot transport
- Bot → Users: verifies · Checks who may receive or use notifications
- Notebook → Default Weights: produces · Trains or evaluates model checkpoints
- Test Suite → Detector Tests: covers · Regression coverage includes detector behavior
- Test Suite → Alert Tests: covers · Regression coverage includes alerting behavior
- Test Suite → Label Fixtures: uses · Uses label edge cases and cleanup fixtures
- Landing Page → Main: presents · Static surface separate from the runtime pipeline