# 项目上下文说明

本文档为 AI 助手提供项目上下文，便于后续交互时快速理解项目结构和技术细节。

---

## 项目概述

**施工现场安全行为智能识别系统 v2.0.0** - 基于 Python 的双摄像头联动系统。

核心功能：
- 全景摄像头实时监控，YOLO11 检测人体/安全帽/反光衣
- 球机 PTZ 联动跟踪，变焦定位目标
- OCR 编号识别（llama-server API）
- 安全违规检测（未戴安全帽、未穿反光衣）
- 事件推送至业务平台 + 语音播报

---

## 目录结构

```
dual_camera_system/
├── config/                      # 模块化配置（已重构）
│   ├── __init__.py              # 配置汇总导出
│   ├── camera.py                # 摄像头 + 日志配置
│   ├── detection.py             # 人体/安全检测配置
│   ├── ptz.py                   # PTZ 控制参数
│   ├── ocr.py                   # OCR 配置
│   ├── coordinator.py            # 联动 + 校准配置
│   ├── event.py                 # 事件推送配置
│   ├── voice.py                 # 语音播报配置
│   ├── llm.py                   # 大模型配置
│   └── system.py                # 系统开关 + 工作模式
├── main.py                      # OCR 模式入口（编号识别）
├── safety_main.py               # 安全模式入口（安全检测）
├── dahua_sdk.py                 # 大华 SDK ctypes 封装
├── panorama_camera.py           # 全景摄像头 + 人体检测
├── ptz_camera.py                # 球机 PTZ 控制
├── calibration.py               # 视觉校准（运动检测 + 特征匹配）
├── ocr_recognizer.py            # OCR 编号识别
├── safety_detector.py           # 安全检测（安全帽/反光衣）
├── safety_coordinator.py        # 安全联动控制器
├── llm_service.py               # 大模型服务封装
├── event_pusher.py              # 事件推送至业务平台
├── voice_announcer.py           # TTS 语音播报
└── README.md                    # 项目说明

dh/                              # 大华 SDK（仅参考）
├── Bin/                         # Linux .so 库（macOS 不可用）
├── Demo/                        # C++ Qt 示例
└── Include/Common/              # SDK 头文件
```

---

## 运行命令

### OCR 模式（编号识别）
```bash
python main.py --panorama-ip 192.168.1.100 --ptz-ip 192.168.1.101
python main.py --interactive      # 交互模式
python main.py --demo            # 演示模式
python main.py --skip-calibration # 跳过校准
```

### 安全模式（安全检测）
```bash
python safety_main.py --panorama-ip 192.168.1.100 --ptz-ip 192.168.1.101
```

### 通用参数
```bash
--model-size {n,s,m,l,x}    # YOLO11 模型尺寸
--no-gpu                     # 禁用 GPU
--ocr-host localhost --ocr-port 8111  # OCR API 地址
```

---

## 技术栈

| 组件 | 技术 |
|------|------|
| 人体检测 | YOLO11 (ultralytics) |
| 安全检测 | YOLO11 安全专用模型 |
| OCR 识别 | llama-server API (Qwen2.5-VL-7B-Instruct) |
| 安全判断 | 规则 + LLM 混合模式 |
| 摄像头 SDK | 大华 NetSDK (ctypes) |
| 图像处理 | OpenCV |
| 特征匹配 | SIFT / ORB |
| PTZ 控制 | DH_EXTPTZ_EXACTGOTO |
| 语音播报 | Edge-TTS (zh-CN-XiaoxiaoNeural) |
| 事件推送 | HTTP API → jtjai.device.wenhq.top:8583 |

---

## 配置说明

### config/system.py - 功能开关
- `mode`: `'safety'` 或 `'ocr'`
- `enable_panorama_camera`, `enable_ptz_camera`
- `enable_detection`, `enable_safety_detection`
- `enable_calibration`, `enable_ptz_tracking`
- `enable_ocr`, `enable_llm`
- `enable_event_push`, `enable_voice_announce`
- `safety_strategy`: `'llm'` / `'rule'` / `'hybrid'`

### config/camera.py - 摄像头配置
- `PANORAMA_CAMERA`: 全景摄像头 IP/端口/凭证
- `PTZ_CAMERA`: 球机 IP/端口/凭证
- `SDK_PATH`: `/home/wen/dsh/dh/Bin`（Linux 路径）

### config/detection.py - 检测配置
- `DETECTION_CONFIG`: 人体检测（目标类别、置信度、检测间隔）
- `SAFETY_DETECTION_CONFIG`: 安全检测模型路径 `/home/wen/dsh/yolo/yolo11m_safety.pt`
  - 类别映射: `0=安全帽`, `3=人`, `4=反光衣`
  - `alert_cooldown`: 3.0 秒，同一目标告警冷却

### config/llm.py - 大模型配置
- `LLM_CONFIG`: Qwen2.5-VL-7B-Instruct，localhost:8111
- `LLM_SAFETY_CONFIG`: `use_llm_for_safety`, `verify_with_llm`

### config/event.py - 事件推送
- `EVENT_PUSHER_CONFIG`: 推送到 `jtjai.device.wenhq.top:8583`
- `/api/resource/oss/upload` - 图片上传
- `/api/system/event` - 事件创建

### config/voice.py - 语音播报
- `TTS_CONFIG`: Edge-TTS, zh-CN-XiaoxiaoNeural
- `VOICE_ANNOUNCER_CONFIG`: 违规播报重复 3 次

### config/coordinator.py - 校准配置
- `CALIBRATION_CONFIG.interval`: 24 小时（不是 5 分钟）

---

## RKNN 测试环境

- **连接**: `ssh admin@192.168.20.84`
- **Conda 环境**: `conda activate rknn`
- **项目路径**: `/home/admin/dsh/dual_camera_system`
- **SDK 路径**: `/home/admin/dsh/dh/Bin`

## 重要注意事项

1. **SDK 路径**: config/camera.py 根据 CPU 架构自动选择 SDK 路径：
   - `aarch64` → `/home/admin/dsh/dh/arm/Bin`（Orange Pi 测试设备）
   - `x86_64` → `/home/wen/dsh/dh/Bin`（x86 Linux 服务器）
   - 其他 → 项目相对路径 `../dh/Bin`（开发环境参考）
2. **ARM64 SDK 兼容性**: ARM64 版 SDK 缺少 `CLIENT_SetVideoProcCallBack` 等函数，`dahua_sdk.py` 已做可选绑定处理，缺失函数运行时降级而非崩溃
3. **SDK 类型映射**: 大华 SDK 在 Linux 上 `DWORD=unsigned int(4B)`, `LONG=int(4B)`, `LLONG=long(8B)`，ctypes 绑定必须严格匹配，否则结构体对齐错误导致登录失败
4. **初始化顺序**: `main.py` 中先加载 YOLO/PyTorch，再初始化大华 SDK。大华 SDK 的 `CLIENT_Init` 会修改进程内存映射，如果先于 PyTorch 加载会导致 segfault
5. **校准间隔**: 实际是 24 小时，不是 README 中的 5 分钟
6. **模型路径**: 安全检测模型在 `/home/wen/dsh/yolo/yolo11m_safety.pt`
7. **YOLO11 自动下载**: 首次运行自动下载预训练权重
8. **OCR 服务**: 需先启动 llama-server（默认 localhost:8111）
9. **工作模式**: `main.py` 是 OCR 模式，`safety_main.py` 是安全检测模式
10. **摄像头端口**: SDK 登录用 37777，RTSP 流用 554，config 中 `port=37777`, `rtsp_port=554`

---

## 交互命令（OCR 模式 main.py）

- `s` - 开始/停止联动
- `r` - 获取识别结果
- `t` - 手动跟踪（输入坐标）
- `c` - 抓拍快照
- `q` - 退出

---

## 校准机制

**方法**：
1. 运动检测法：帧差定位球机移动区域
2. 特征匹配法：SIFT/ORB 匹配球机图像与全景画面
3. 加权融合 + 降级（角度估算）

**流程**：
```
移动前全景帧 ────┐
                 ├──> 运动检测 ──> 运动区域中心
移动后全景帧 ────┘

球机抓拍 ────────┐
                 ├──> 特征匹配 ──> 匹配点中心
全景画面 ─────────┘

运动区域 + 匹配点 ──> 加权融合 ──> 坐标映射
```

---

## SDK 参考

头文件：`dh/Include/Common/dhnetsdk.h`

关键接口：
- `CLIENT_Init` / `CLIENT_Cleanup`
- `CLIENT_LoginEx2` / `CLIENT_Logout`
- `CLIENT_RealPlayEx`
- `CLIENT_DHPTZControlEx` (DH_EXTPTZ_EXACTGOTO)