RoomGate AI 🚪⚡

RoomGate AI is an enterprise-grade, high-performance Smart Access & Occupancy Monitoring System engineered for real-time computer vision processing, spatial region-of-interest (ROI) filtering, and automated hardware access control.

Designed for high-throughput operational environments, RoomGate AI features a multi-threaded video stream pipeline, non-blocking asynchronous event logging, an intuitive glassmorphic visual HUD, and embedded web streaming capabilities.

---

🌟 Key Architecture & Capabilities

• ⚡ High-Throughput Threaded Acquisition: Dedicated background ThreadedCamera pipeline ensuring non-blocking video capture and zero I/O frame drops.
• 🎯 Spatial Region-of-Interest (ROI) Engine: Real-time geometric polygon containment checks with configurable spatial boundaries.
• 🔐 Deterministic Decision Engine: Temporal median filtering and confidence thresholding to guarantee stable, chatter-free access control decisions.
• 🛠️ Hardware Lock Integration: Direct serial protocol interfacing with Arduino/ESP32 relay modules, dry-run safety modes, and fail-safe command throttling.
• 📊 Asynchronous SQLite WAL Event Logging: Non-blocking SQLite event persistence utilizing Write-Ahead Logging (WAL), indexed analytical schemas, and image snapshot archiving.
• 🖥️ Glassmorphic Operational Visual HUD: Real-time telemetry overlay featuring dynamic access indicators, live FPS metrics, inference latency timing, and bounding box spatial tracking.
• 🌐 Embedded Web Dashboard & MJPEG Stream: Integrated HTTP web dashboard serving a real-time MJPEG video feed and JSON status REST API for remote administrative monitoring.
• 📈 Performance Diagnostic Tools: Command-line benchmark and diagnostic suite for evaluating hardware acceleration, frame throughput, and sub-millisecond latency.

---

🏗️ System Architecture

flowchart TD
    A[Camera / Video Source] -->|Raw Frames| B[ThreadedCapture Pipeline]
    B -->|Latest Frame| C[YOLO Spatial Detector & Tracker]
    C -->|Detections| D[ROI Spatial Filter]
    D -->|Inside Count| E[Occupancy Decision Engine]
    E -->|Access Command| F[Hardware Relay Controller]
    E -->|Event Record| G[Async SQLite WAL Logger]
    C -->|Annotated Stream| H[Glassmorphic HUD Renderer]
    H -->|Frame Render| I[OpenCV Window & Web MJPEG Server]

Loading

---

🚀 Installation & Setup

Prerequisites

• Python 3.10+
• OpenCV 4.8+
• PyTorch 2.0+

Environment Installation

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e .

---

💻 Usage & CLI Reference

1. Live Monitoring Mode

Launch the live access monitor using default system configuration:

roomgate-ai monitor --config config/default.yaml

To run in simulation mode (dry-run hardware relay with synthetic camera feed):

roomgate-ai monitor --dry-run

To enable the live Web Dashboard on port 8080:

roomgate-ai monitor --web --web-port 8080

Access the live stream dashboard at http://localhost:8080.

---

2. Diagnostics & Performance Benchmarks

Run hardware acceleration diagnostics (CUDA / MPS / CPU availability):

roomgate-ai status

Execute latency and frame rate benchmark tests:

roomgate-ai benchmark --frames 100

---

3. Full Subcommand Reference

Subcommand	Description
roomgate-ai monitor	Executes the real-time access monitoring pipeline
roomgate-ai web	Runs the headless web dashboard and MJPEG stream server
roomgate-ai benchmark	Evaluates system throughput (FPS) and latency metrics
roomgate-ai status	Displays runtime software environment and CUDA diagnostics
roomgate-ai collect	Collects raw image datasets for specific operational scenarios
roomgate-ai dataset-report	Validates dataset structure and label completeness
roomgate-ai train	Fine-tunes object detection models on custom datasets
roomgate-ai export	Exports trained models to ONNX or TensorRT formats

---

⚙️ Configuration Schema (config/default.yaml)

camera:
  source: 0
  width: 1280
  height: 720
  fps: 30
  threaded: true

model:
  weights: "yolo26n.pt"
  confidence: 0.35
  iou: 0.7
  device: null

occupancy:
  max_occupancy: 3
  confirmation_frames: 5
  minimum_average_confidence: 0.35
  log_every_seconds: 1.0

roi:
  name: "main_room"
  points:
    - [80, 80]
    - [1200, 80]
    - [1200, 700]
    - [80, 700]

relay:
  enabled: false
  port: "COM3"
  baudrate: 9600

logging:
  sqlite_path: "logs/events.sqlite3"
  snapshot_dir: "snapshots"
  save_event_snapshots: false
  wal_mode: true

---

🔌 Hardware Relay Protocol

RoomGate AI interfaces with hardware relays (Arduino, ESP32, or industrial controllers) via high-speed serial communication.

Deploy firmware located at hardware/arduino_relay_lock/arduino_relay_lock.ino to your micro-controller board, then enable serial control in config/default.yaml:

relay:
  enabled: true
  port: "COM3"
  baudrate: 9600

---

🧪 Verification & Automated Testing

Execute the unit test suite:

pytest tests/ -v

---

📄 License

This project is licensed under the MIT License. See the LICENSE file for complete details.