交互式 PTZ-全景手动标定脚本设计

背景

正式环境 RK3588 上的自动标定 calibration_scan_180_360_z1/calibration_group1.json RMS 误差约 100°，导致球机无法对准人体。

自动模板/特征匹配失败的原因：施工现场为重复钢结构（蓝色钢梁、脚手架），不同 PTZ 角度拍到的纹理高度相似，匹配算法把多个不同角度映射到相近的全景位置。

目标

开发一个交互式手动标定脚本，通过浏览器 Web UI 实时查看 PTZ 抓拍图，点击按钮调整 pan/tilt，逐步确认每个标定点，最终生成可直接替换的 calibration_group1.json。

约束

运行环境：RK3588 (10.126.126.1)，Python 3.8，OpenCV 4.5.5
球机：Dahua 192.168.20.197，PTZ 控制 via Dahua SDK
全景：Dahua 192.168.20.196，RTSP 3840×1080
标定范围：pan 180°–340°，tilt -35°–45°（与现有 calibration_scan_180_360_z1 范围一致）
用户通过单一浏览器页面完成所有操作，无需 SSH 终端输入

方案

在 RK3588 上运行标定脚本，脚本内置 HTTP 服务和 Web UI。用户通过浏览器访问页面，看到实时 PTZ 画面、全景标定点标记和控制按钮，点击按钮即可调整并确认。

数据流

points.txt (用户预选全景坐标)
        │
        ▼
dual_camera_system/scripts/manual_calibrate.py
  ├── 抓取 panorama.jpg
  ├── 在 panorama_marks.jpg 上标记所有待标定点
  ├── 启动 HTTP 服务 + Web UI
  └── 对每个点：
        1. 用粗略线性估计初始 pan/tilt
        2. 球机 goto_exact_position
        3. 抓拍并保存 latest_ptz.jpg
        4. 等待用户通过 Web UI 发送指令
        5. 收到确认后记录 (x_ratio, y_ratio, pan, tilt)
        ▼
manual_points.json + calibration_group1_manual.json

Web UI 页面

实时 PTZ 画面：左侧，自动刷新
全景标定点标记：右侧，显示 P1-PN 标记
状态栏：当前点、PAN、TILT、状态
控制按钮：
- Pan：← 10° / ← 5° / ← 3° / 3° → / 5° → / 10° →
- Tilt：↓ 10° / ↓ 5° / ↓ 3° / ↑ 3° / ↑ 5° / ↑ 10°
- 操作：确认该点 / 跳过该点 / 退出标定

API 接口

接口	方法	说明
`/` / `/index.html`	GET	Web UI 页面
`/api/status`	GET	当前标定状态 JSON
`/api/command`	POST	接收用户指令 `{command: "p+5"}`
`/ptz_shots/latest_ptz.jpg`	GET	最新 PTZ 图像
`/panorama_marks.jpg`	GET	全景标记图

关键文件

文件	作用
`dual_camera_system/scripts/manual_calibrate.py`	标定主脚本（含 HTTP/Web UI）
`dual_camera_system/scripts/points.txt`	用户预选的全景归一化坐标（运行时可复制到输出目录）
`manual_calib/panorama.jpg`	当前全景图
`manual_calib/panorama_marks.jpg`	带标定点标记的全景图
`manual_calib/ptz_shots/latest_ptz.jpg`	最新球机抓拍
`manual_calib/manual_points.json`	原始标定点记录
`manual_calib/calibration_group1_manual.json`	生成的校准文件

校准文件生成

从记录的标定点拟合：

pan = a + b*x + c*y
tilt = d + e*x + f*y
同时保存 pan_lookup / tilt_lookup 供 CameraCalibrator.transform 直接使用
输出 RMS 误差供用户评估

验收标准

脚本在 RK3588 成功启动并连接到球机和全景
浏览器可以访问 http://10.126.126.1:8000/ 看到 Web UI
用户完成 ≥4 个标定点后生成 calibration_group1_manual.json
生成的校准文件 RMS 误差 < 5°
替换正式 calibration_group1.json 后，球机能够对准全景中的人体

风险

RK3588 8000 端口可能被占用（已设置 SO_REUSEADDR）
球机移动需要时间，抓拍前必须等待稳定
浏览器与 RK3588 之间网络需通畅

后续工作

已实现 Web UI 版 manual_calibrate.py
部署到 RK3588 并运行
用户通过浏览器完成标定
验证生成的校准文件并替换正式环境

2026-06-15-interactive-ptz-calibration-design.md 4.0 KB Verlauf Originalformat