项目上下文说明

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

项目概述

双摄像头联动抓拍系统 - 基于 Python 实现的全景摄像头与 PTZ 球机联动系统。

核心功能：

全景摄像头实时监控，使用 YOLO11 检测人体
检测到人体后，球机自动变焦定位到目标
对人体进行分割，通过 llama-server API 进行 OCR 编号识别
自动校准全景相机与球机的坐标映射关系

目录结构

/home/wen/dsh/
├── AGENTS.md                    # 本文档
├── dual_camera_system/          # 主项目目录
│   ├── config.py                # 配置文件 (摄像头、检测、OCR等配置)
│   ├── dahua_sdk.py             # 大华 SDK Python ctypes 封装
│   ├── panorama_camera.py       # 全景摄像头模块 (视频流、YOLO11人体检测)
│   ├── ptz_camera.py            # 球机控制模块 (PTZ控制、三维精确定位)
│   ├── calibration.py           # 视觉校准模块 (运动检测+特征匹配)
│   ├── ocr_recognizer.py        # OCR识别模块 (llama-server API)
│   ├── coordinator.py           # 联动控制器 (事件驱动、坐标转换)
│   ├── main.py                  # 主程序入口
│   └── README.md                # 项目说明文档
└── dh/                          # 大华 SDK 目录
    ├── Bin/                     # SDK 动态库
    │   ├── libdhnetsdk.so       # 网络 SDK
    │   ├── libavnetsdk.so       # AV 网络 SDK
    │   └── ...
    ├── Demo/                    # C++ 示例代码 (Qt项目)
    │   ├── 00.DevInit/          # 设备初始化
    │   ├── 01.RealPlay/         # 实时预览
    │   ├── 02.PTZControl/       # PTZ控制
    │   └── ...
    ├── Doc/                     # SDK 文档
    │   ├── NetSDK编程指导手册.pdf
    │   └── ...
    └── Include/Common/          # SDK 头文件
        ├── dhnetsdk.h           # 网络 SDK 接口定义
        └── ...

技术栈

组件	技术
人体检测	YOLO11 (ultralytics)
OCR识别	llama-server API (PaddleOCR-VL)
摄像头SDK	大华 NetSDK (ctypes封装)
图像处理	OpenCV
特征匹配	SIFT / ORB
PTZ控制	DH_EXTPTZ_EXACTGOTO (三维精确定位)

运行命令

安装依赖

pip install opencv-python opencv-contrib-python ultralytics

启动 OCR 服务

llama-server -m PaddleOCR-VL-1.5-GGUF.gguf --port 8111

运行系统

# 基本运行
python main.py --panorama-ip 192.168.1.100 --ptz-ip 192.168.1.101

# 指定模型大小
python main.py --model-size s --ocr-host localhost --ocr-port 8111

# 交互模式
python main.py --interactive

# 演示模式 (不连接实际摄像头)
python main.py --demo

# 跳过校准
python main.py --skip-calibration

核心模块说明

config.py

集中配置文件，包含：

LOG_CONFIG: 日志配置
PANORAMA_CAMERA: 全景摄像头连接参数
PTZ_CAMERA: 球机连接参数
SDK_PATH: 大华SDK库路径
DETECTION_CONFIG: YOLO检测配置
PTZ_CONFIG: PTZ控制参数
OCR_CONFIG: llama-server API配置
CALIBRATION_CONFIG: 校准配置 (间隔24小时)

dahua_sdk.py

大华SDK Python封装：

使用 ctypes 加载 libdhnetsdk.so
实现登录、实时预览、PTZ控制等接口
SDK回调使用 _disconnect_callback 持有引用防止垃圾回收

panorama_camera.py

全景摄像头模块：

ObjectDetector: YOLO11人体检测器
PersonTracker: 人体跟踪器
PanoramaCamera: 视频流获取和帧处理

ptz_camera.py

球机控制模块：

PTZController: PTZ控制封装
PTZCamera: 球机连接和变焦控制
支持三维精确定位 (DH_EXTPTZ_EXACTGOTO)

calibration.py

视觉校准模块：

VisualCalibrationDetector: 视觉校准检测器
运动检测法：帧差定位球机移动区域
特征匹配法：SIFT/ORB特征点匹配
加权融合两种方法结果
降级方案：视觉失败时使用角度估算

ocr_recognizer.py

OCR识别模块：

NumberDetector: 编号识别器
使用 llama-server HTTP API
图像base64编码发送
重试机制 (最多3次，指数退避)

coordinator.py

联动控制器：

Coordinator: 基础联动逻辑
EventDrivenCoordinator: 事件驱动控制器
坐标转换：全景(x_ratio, y_ratio) → PTZ(pan, tilt)
性能统计：帧率、检测数、OCR成功率

main.py

主程序入口：

DualCameraSystem: 系统主类
命令行参数解析
定时校准线程
交互命令处理 (s/r/t/c/q)

工作流程

┌─────────────────────────────────────────────────────────────┐
│  1. 系统启动 → 自动校准全景相机与球机坐标映射               │
│  2. 全景摄像头获取视频流                                    │
│  3. YOLO11检测画面中的人体                                  │
│  4. 计算人体在画面中的相对位置 (x_ratio, y_ratio)           │
│  5. 通过校准转换 → PTZ角度 (pan, tilt)                      │
│  6. 球机变焦移动到目标位置                                  │
│  7. 人体分割 + OCR识别编号                                  │
│  8. 输出识别结果                                            │
│  9. 每24小时自动重新校准                                    │
└─────────────────────────────────────────────────────────────┘

性能优化要点

OCR频率控制: self.ocr_interval = 1.0 避免API过于频繁调用
PTZ位置阈值: self.ptz_position_threshold = 0.02 避免频繁发送相同位置命令
帧缓冲: 支持运动检测所需的多帧处理
重试机制: OCR失败时指数退避重试

大华SDK参考

SDK头文件位置：/home/wen/dsh/dh/Include/Common/dhnetsdk.h

关键接口：

CLIENT_Init: 初始化SDK
CLIENT_LoginEx2: 登录设备
CLIENT_RealPlayEx: 开始实时预览
CLIENT_DHPTZControlEx: PTZ控制
CLIENT_Logout: 登出设备
CLIENT_Cleanup: 清理SDK

PTZ命令：

DH_EXTPTZ_EXACTGOTO: 三维精确定位 (pan, tilt, zoom)

注意事项

大华SDK库路径在 config.py 中配置，默认 /home/wen/dsh/dh/Bin
YOLO11首次运行会自动下载预训练权重
OCR依赖 llama-server 服务，需先启动
校准间隔默认24小时，可在 CALIBRATION_CONFIG 中修改
球机需支持PTZ控制功能

AGENTS.md 6.8 KB 文件歷史 原始文件