SyedRazaZaidi/SecureWatch-AI
GitHub: SyedRazaZaidi/SecureWatch-AI
基于 YOLOv8 与 ByteTrack 的实时计算机视觉安防管线，可自动检测并记录徘徊、奔跑、人群聚集和暴力冲突等异常行为。
Stars: 0 | Forks: 0
# 🧠 SecureWatchAI
这是一个企业级的实时计算机视觉安全 pipeline，可将原始摄像头画面和上传的视频转化为一个主动的威胁情报网络。利用最先进的多目标跟踪技术（YOLOv8 和 ByteTrack），结合自定义的行为启发式算法，SecureWatchAI 能够自动检测徘徊、人群聚集、可疑奔跑以及剧烈混乱的肢体冲突——为安全团队提供实时日志、自动化事件数据库持久化存储以及照片证据。
## 📌 目录
* [核心架构支柱](#-key-architectural-pillars)
* [系统流程架构](#%EF%B8%8F-system-flow-architecture)
* [技术栈](#-technology-stack)
* [核心启发式算法](#-core-heuristic-algorithms)
* [入门指南（安装与运行）](#-getting-started)
* [API 规范](#-api-specifications)
* [数据库 Schema](#-database-schema)
* [仓库协作](#-repository-collaboration)
* [许可证](#-license)
## ⚡ 核心架构支柱
* **自适应双模式引擎**：
* *GPU CUDA 模式*：以 **640px** 的分辨率和 100% 的帧吞吐量运行高精度推理，充分利用 CUDA 处理核心（例如 RTX 4050 笔记本电脑 GPU），提供流畅、零延迟的 60+ FPS 视觉画面。
* *CPU 回退模式*：自动降级至 **320px** 的模型分辨率，并调用智能的 **3 帧跳帧调度器**，在跳过的帧上利用缓存的边界框来维持 30 FPS 的播放，同时避免导致 CPU 热降频。
* **优化的流媒体压缩**：采用经过优化的 Web 流媒体 pipeline，自动将高分辨率源缩小至 **960x540 Web HD**，并利用量身定制的 **JPEG 子采样 (`Quality=80`)**，将服务器上的编码延迟降低了 **90%** 以上（帧处理开销从 45ms 降至 4ms 以下）。
* **帧率调节器**：内置独立于硬件的速度调节器，可读取视频文件元数据，将处理速度与原生帧率同步，从而避免网络拥堵和帧队列延迟。
* **主动审计与自动清理**：将事件日志持久化记录到 SQLite 中，并在发生威胁时捕获高分辨率屏幕截图。集成了 FastAPI 关闭生命周期钩子，可在服务器终止时自动清理缓存的临时截图产物。
## 🔄 流媒体智能 Pipeline
VisionGuard-AI pipeline 通过 **5 个视觉处理阶段**将原始视频流转化为可操作的威胁遥测数据：
```
[ 1. CAPTURE ] ➡️ [ 2. OPTIMIZE ] ➡️ [ 3. TRACK ] ➡️ [ 4. PROFILE ] ➡️ [ 5. ACTION ]
Camera / File Auto-Rescaler YOLOv8 Engine Heuristics Logs & Alerts
(OpenCV Feed) (CPU / GPU Tune) (ByteTrack ID) (Anomalies) (DB / Web UI)
```
### 1️⃣ 捕获阶段（接入）
* 从您的网络摄像头流式传输视频帧，或处理高速视频文件上传。
* **播放速度调节器**会自动读取视频元数据，以精确的 **1 倍实时速度**流式传输文件画面，确保流队列的纯净。
### 2️⃣ 优化阶段（减速处理）
* **自动高清缩放器**：自动将高分辨率输入重新缩放至 **960x540 Web HD**，将 JPEG 编码和叠加渲染的速度提高 4 倍。
* **硬件性能分析器**：
* **GPU 模式 (RTX 4050)**：将完整的 **640px** 图像直接传递给显卡，实现 100% 的吞吐量。
* **CPU 模式（回退）**：将分辨率降至 **320px**，并每 3 帧跳过 2 帧，以保持系统的高响应能力。
### 3️⃣ AI 核心阶段（检测）
* **YOLOv8 引擎**：使用 GPU 在 **12ms** 内检测画面中的人物。
* **ByteTrack 跟踪器**：跨帧关联边界框，为每个被跟踪的个体分配唯一的 **持久化 ID**。
### 4️⃣ 智能分析阶段（启发式规则）
* 自定义数学引擎会扫描坐标和速度历史记录，以检测威胁行为：
* 🚨 *徘徊*：在某一区域内静止停留超过 $> 5$ 秒。
* 🏃 *奔跑*：滚动矢量速度超过自定义的位移限制。
* 👥 *拥挤*：累计帧人数超过密度阈值。
* 💥 *暴力*：重叠或相近的 ID 之间出现异常高速的移动。
### 5️⃣ 事件阶段（通知）
* 在画面上绘制视觉警报边界框和历史移动轨迹。
* 利用超快的 **JPEG 编码 (Quality=80)** 压缩帧，并将流广播到您的仪表板。
* 将详细信息（时间戳、类别和 ID）记录到 **SQLite 数据库**中，并将高分辨率照片证据保存到 `alerts/` 目录。
## 💻 技术栈
* **AI 引擎**：[Ultralytics YOLOv8](https://docs.ultralytics.com/)、PyTorch（CUDA 12.1 加速）、[ByteTrack](https://github.com/ifzhang/ByteTrack)。
* **计算机视觉**：OpenCV（C++ 编译的绑定）、NumPy。
* **Web 服务**：FastAPI（异步 ASGI）、Uvicorn、python-multipart（流式上传解析器）。
* **数据层**：SQLite3（标准 SQL RDBMS）。
## 🧠 核心启发式算法
SecureWatchAI 运行着轻量级、高度优化的启发式数学算法，旨在以极低的性能影响完成行为分析：
1. **徘徊检测**：监控唯一的跟踪 ID 持久化坐标。如果某个 ID 的中心点在指定的坐标半径内停留超过 $> 5$ 秒，则会触发徘徊事件。
2. **可疑速度 / 奔跑**：计算过去 5 帧滚动历史记录中的欧几里得像素距离位移向量：
$$d = \sqrt{(x_t - x_{t-5})^2 + (y_t - y_{t-5})^2}$$
如果 $d > 50\text{px}$，该速度将触发 RUNNING（奔跑）警告。
3. **人群检测**：持续跟踪活动矩阵中累计的边界框。如果单帧中的总活动人数超过 $N$（默认为 $3$），将发出人群警告。
4. **暴力 / 打斗检测**：检查活动跟踪 ID 之间的邻近度指标。如果两个 ID 重叠或进入 80px 边界范围内，*同时*突破了奔跑/异常速度阈值（$d > 50\text{px}$），系统会将该交互标记为正在发生的冲突。
## 🚀 入门指南
### 前置条件
* Python 3.10 - 3.12（强烈推荐使用 Python 3.11.9，以兼容标准的预编译 wheel）。
* 安装了 NVIDIA CUDA 驱动程序的 NVIDIA 显卡（用于利用 GPU 模式）。
### 1. 克隆仓库
从您的 GitHub 个人主页克隆您的自定义仓库：
```
git clone https://github.com/sheralisaleem/VisionGuard-Smart-Surveillance.git
cd VisionGuard-Smart-Surveillance
```
### 2. 设置虚拟环境
创建并激活一个干净的沙盒环境，以避免包版本冲突：
```
# 使用 Python 3.11 launcher 创建 venv
py -3.11 -m venv venv
# 在 Windows PowerShell 上激活
.\venv\Scripts\Activate.ps1
```
### 3. 安装支持 CUDA 加速的 PyTorch
为确保您的 RTX GPU 得到充分利用，请先安装支持 CUDA 12.1 的二进制文件：
```
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
```
### 4. 安装项目依赖包
```
pip install -r requirements.txt
```
### 5. 启动监控系统
```
python main.py
```
打开 Web 浏览器并访问 **`http://localhost:8000`**，即可查看您的控制中心仪表板！
## 📡 API 规范
| 方法 | Endpoint | 描述 | Payload 结构 / 查询 |
| :--- | :--- | :--- | :--- |
| **`GET`** | `/` | 提供主要的 HTML5/JavaScript 监控仪表板 UI。 | *无* |
| **`GET`** | `/video_feed` | 流式传输高性能、实时的 AI 注释摄像头画面。 | *MJPEG Stream (`multipart/x-mixed-replace`)* |
| **`GET`** | `/get_logs` | 获取视觉分析器记录的最新 50 条安全威胁日志。 | `{"logs": ["Timestamp ... Alert Type ..."]}` |
| **`POST`** | `/upload_video` | 动态流式传输并上传本地录像，自动切换视觉 pipeline 对其进行分析。 | 包含 `file` 字段的 `multipart/form-data`。 |
## 📊 数据库 Schema
SecureWatchAI 利用持久的本地 SQLite 数据库（`surveillance.db`）来记录安全指标。`alerts` 表的配置如下：
```
CREATE TABLE IF NOT EXISTS alerts (
id INTEGER PRIMARY KEY AUTOINCREMENT, -- Unique incident ID
timestamp TEXT, -- Local timestamp (YYYY-MM-DD HH:MM:SS)
alert_type TEXT, -- Threat type (LOITERING, RUNNING, CROWD, FIGHT)
person_id INTEGER, -- Bounded offender ID assigned by ByteTrack
image_path TEXT -- Absolute file path to saved JPEG evidence screenshot
);
```
## 👥 仓库协作
如果您想为该仓库贡献改进或新的启发式模型：
1. 在您自己的 GitHub 账号上 **Fork 该仓库**。
2. 创建一个 **Feature Branch** 来隔离您的更新：
git checkout -b feature/your-awesome-improvement
3. 提交带有精确描述的修改：
git commit -m "Add custom spatial trespass fence heuristics"
4. 将更改推送到您的个人 fork：
git push origin feature/your-awesome-improvement
5. 针对此仓库的 `main` 分支发起 **Pull Request (PR)** 以供审查！
标签：CCTV/网络接口发现, Vectored Exception Handling, 凭据扫描, 多目标跟踪, 异常行为检测, 物理安防, 目标检测, 视频监控, 计算机视觉, 逆向工具
