scan-calibrator/README.md

# scan参数交互式配置向导

该工具用于在不同摄像头点位通过固定对话完成scan参数标定、配置替换、完整试扫和验证拼图，
适合批量部署RK3576和RK3588。详细的底层命令和原理见[手动配置README.md](./手动配置README.md)。

## 目录结构

```text
scan-calibrator/
├── README.md                    # 交互式向导主文档
├── 手动配置README.md             # 完整手动流程和参数原理
├── install.sh                  # 首次部署时安装依赖并做完整环境自检
├── interactive.sh              # 交互式向导入口
├── interactive_calibrator.py
├── calibrate.sh                # 手动配置入口
├── scan_calibrator.py
├── src/measure_overlap.cpp
├── result/                     # 运行时生成的scan配置片段
└── scan-panorama/
    ├── stitch.sh
    ├── stitch_scan.py
    ├── README.md
    └── result/                 # 运行时生成的验证大图
```

## 启动

首次把本目录复制到一台RK3576或RK3588后，先执行一次安装与自检：

```bash
cd /home/zhangw/scan-calibrator
./install.sh
./interactive.sh
```

`install.sh`可重复运行，不会修改scan参数。它会在缺少时通过`apt-get`安装宿主机
`python3`和`imagemagick`，然后检查Docker、smart-cam容器、scan HTTP服务、数据目录写权限、
容器内C++/OpenCV编译环境以及拼图命令。非root账号安装缺失软件时需要具有`sudo`权限。

如果设备上曾出现“未找到ImageMagick identify”，就是宿主机缺少`imagemagick`；
运行`install.sh`会自动补齐。ImageMagick安装在RK3588宿主机，而不是smart-cam容器内，
因为验证拼图程序运行在宿主机。

只需要输入：

- `1`：确认、执行或选择野外部署；
- `2`：只在第一个问题中表示办公室测试；
- `3`：结束对话，并清理本次未完成向导生成的标定状态和临时标定截图；
- `Ctrl+C`：等同于退出。

退出不会删除历史扫描目录，也不会回滚已经明确确认替换并重启的`config.json`。

## 完整对话示例

下面以办公室测试、28张小图为例。`>`后面的`1`或`2`是现场人员输入；PTZ、step、
文件名和扫描目录只是示例，实际值由当前摄像头返回。

```text
您好！我们现在开始配置扫图参数！
在接下来的对话中，回复 3 会立即结束，并清理本次向导产生的标定痕迹。

① 当前是【野外部署阶段】（回复 1）还是【办公室测试阶段】（回复 2）？
> 2

② 请在Web界面中设置左上角zoom，再手动把摄像头移到扫描区域的【左上角】。
到位后回复 1；回复 3 随时退出。
> 1
已读取: pan=19120 (191.20°), tilt=990 (9.90°), zoom=810 (8.10×)

③ 请手动把摄像头移到扫描区域的【右下角】。
右下角可以使用不同zoom，程序会取两个角点zoom的平均值作为最终扫描zoom。
到位后回复 1；回复 3 随时退出。
> 1
已读取: pan=13420 (134.20°), tilt=-340 (-3.40°), zoom=810 (8.10×)

④ 这一步用于测量当前zoom下的水平/垂直视场。
请把摄像头移到扫描区域内部、距离较远且纹理分布在整幅画面的位置。
请避开纯天空、纯墙面、水面、玻璃、近距离物体和重复图案；
回复1后不要再操作Web云台，程序会自动移动、拍照并返回起点。
到位后回复 1；回复 3 随时退出。
> 1

正在计算，请不要操作摄像头或Web控制页面……
已读取: pan=16220 (162.20°), tilt=440 (4.40°), zoom=810 (8.10×)

正在标定 pan_step，摄像头会自动移动并回到起点……
  step=250: 重叠约 77.0%，有效特征=286，内点率=91.7%
  step=450: 重叠约 58.6%，有效特征=191，内点率=84.5%
  step=700: 重叠约 35.5%，有效特征=116，内点率=73.9%

正在标定 tilt_step，摄像头会自动移动并回到起点……
  step=120: 重叠约 81.3%，有效特征=302，内点率=92.0%
  step=220: 重叠约 65.8%，有效特征=215，内点率=86.7%
  step=350: 重叠约 45.6%，有效特征=143，内点率=78.1%

⑤ 本次得到的扫图参数：
{
  "pan_start": 13420,
  "pan_end": 19870,
  "pan_step": 1075,
  "tilt_start": -340,
  "tilt_end": 1511,
  "tilt_step": 617,
  "zoom": 810
}
安装方式：desktop
范围检查：视觉左→右pan=decreasing，指定弧段=57.00°
整步扩边：pan_step=1075，向终点外扩=750（7.50°）
整步扩边：tilt_step=617，向终点外扩=521（5.21°）
预计网格：7列 × 4行 = 28张

⑥ 是否替换 smart-cam 容器内的/smart-cam/config/config.json？
替换并重启回复 1；不替换并结束回复 3。
> 1
替换完成，smart-cam已重启。

⑦ 是否现在进行一次完整扫图测试？
开始测试回复 1；不测试并结束回复 3。
> 1
已启动测试扫描。

扫图日志：
已保存第 1/28 张图
已保存第 2/28 张图
……
已保存第 27/28 张图
已保存第 28/28 张图

扫描完成，共保存 28 张图。
保存目录：/smart-cam/data/scan/2026-07-23_16-53-51

⑧ 本次扫描已完成，是否立即进行拼图测试？
开始拼图回复 1；不拼图并结束回复 3。
> 1

拼图完成。
大图存储位置：/home/zhangw/scan-calibrator/scan-panorama/result/2026-07-23_16-53-51_desktop_scan_grid_panorama.jpg

配置向导已完成，对话结束。
```

## 每个问题背后执行了什么

### ① 选择部署环境

- 回复`1`：使用`hanging`，表示球机在野外正常倒挂；
- 回复`2`：使用`desktop`，表示办公室桌面正放且摄像头后台旋转了180度。

它决定验证拼图时的画面方向。摄像头的pan数值递增/递减方向不再由安装姿态写死，
而是在第④步根据实拍画面位移自动识别。生成配置仍等价于最后执行：

```bash
./calibrate.sh generate --mount hanging
# 或
./calibrate.sh generate --mount desktop
```

### ② 记录左上角

现场人员先在Web界面设置左上角zoom，并移动到扫描区域左上角。回复`1`后，向导通过
smart-cam的HTTP接口读取PTZ并记录，等价于：

```bash
./calibrate.sh ptz
./calibrate.sh mark top-left
```

记录的是当前画面中心的`pan/tilt/zoom`。

### ③ 记录右下角

移动到右下角；这里允许根据覆盖范围使用不同zoom。回复`1`后等价于：

```bash
./calibrate.sh ptz
./calibrate.sh mark bottom-right
```

向导会显示两个角点的zoom，并取算术平均值作为最终扫描zoom。第四步开始测量前，
程序会自动把镜头切换到该平均zoom，因此视场标定与最终配置使用同一焦段。

### ④ 自动计算pan_step和tilt_step

现场人员把镜头移到扫描区域内部、距离较远且纹理丰富的位置。
回复`1`后，向导会：

1. 抓取基准图；
2. 沿pan方向先从小角度探测；取得首个有效样本后立即反算当前zoom的视场，
   并自适应补测约82%、72%、60%、48%、35%重叠附近的候选角度，每次抓图后回到起点；
3. 用ORB特征、RANSAC和单轴画面位移求水平视场；
4. 沿tilt方向重复测量；
5. 每个方向统一筛选相互一致的视场样本；获得4个覆盖充分、离散度不超过8%的
   可靠样本后提前停止，不再测试更大且通常没有公共画面的step；
6. 两组结果只有在特征质量高且视场差不超过8%时才接受，否则要求至少三组一致结果；
7. 水平方向按4.5%、垂直方向按2%目标重叠计算step；这是根据完整扫图接缝分别设置的轴向补偿；
8. 默认使用ORB特征和RANSAC几何变换；当局部图案重复导致几何内点不足时，自动使用整幅图
   相位相关复核纯单轴位移，相位响应不得低于0.20；
9. 要求至少50个几何内点且内点率至少45%，否则拒绝结果；
10. 根据配置中的图像宽高比，用可靠的tilt视场按普通透视公式反算pan视场；若与pan实测相差
    不超过15%，取“直接pan结果”和“tilt推导结果”的几何平均值，避免任一模型单独产生偏差；
11. 若pan实测与tilt透视预测相差超过15%，不强制套用比例，并明确提示镜头畸变或不同tilt行
    水平覆盖不一致；这种摄像头使用单一pan_step无法保证所有行同时零重叠且无缺口；
12. 根据多个水平样本的带符号位移，自动识别该型号摄像头从画面左到右时pan是递增还是递减；
13. 每次标定会话只编译一次OpenCV重叠分析器，后续step直接复用；
14. 如果smart-cam因RTSP采集看门狗而短暂重启，向导会等待scan HTTP恢复，
    然后重试当前PTZ或拍照操作，不会直接丢失整个第四步；
15. 删除本次自动标定产生的临时截图。

这一步不能省略。两个角点只能确定扫描范围，无法确定当前摄像头型号和zoom下的一幅画面
覆盖多少角度。

不要把画面对准纯天空、纯墙、纯水面、玻璃、近距离物体或重复图案。水面场景应让岸线、
浮标等固定物体横向分布在画面中，不能只依赖不断变化的水纹。
测量过程中程序会锁定两个角点的平均zoom；自动对焦不影响zoom。标定失败时可以只更换第四步的位置重试，
不需要重新记录左上角和右下角。

### ⑤ 显示最终参数

向导按完整step向终点扩展扫描范围，保证范围只能比手动选择的区域稍大，不能少扫。
它会显示：

```text
pan_start / pan_end / pan_step
tilt_start / tilt_end / tilt_step
zoom
预计行数、列数、图片总数和向外扩展角度
```

同时将片段保存到：

```text
/home/zhangw/scan-calibrator/result/
```

### ⑥ 替换配置并重启

回复`1`后，向导会：

1. 从容器读取`/smart-cam/config/config.json`；
2. 只更新`scan`中的七个运动参数，保留定时时间、等待时间、容差和HTTP设置；
3. 用`python3 -m json.tool`验证新JSON；
4. 原子替换配置，不另外备份原配置；
5. 执行`docker restart smart-cam`；
6. 等待scan HTTP服务重新可用。

回复`3`不会替换配置。

### ⑦ 立即完整试扫

回复`1`等价于：

```bash
docker exec smart-cam curl -fsS -X POST \
  http://127.0.0.1:18080/api/v1/scan/start
```

向导会在后台轮询扫描状态，但不会把HTTP请求日志显示到终端。终端只显示图片保存进度：

```text
已保存第 1/28 张图
已保存第 2/28 张图
……
```

后台状态查询等价于：

```bash
docker exec smart-cam curl -fsS \
  http://127.0.0.1:18080/api/v1/scan/status
```

扫描完成或失败后自动停止日志跟随，并显示结果目录。

扫描过程中需要中断时，直接按`Ctrl+C`。向导会主动调用停止接口并结束本次扫描，
已经保存的小图和`meta.json`会保留。也可以在另一个终端执行：

```bash
docker exec smart-cam curl -fsS -X POST \
  http://127.0.0.1:18080/api/v1/scan/stop
```

### ⑧ 拼图测试

只有本次试扫成功完成后才会出现这个问题。回复`1`后，向导将本次扫描的结果目录和第①步
选择的安装方式传给：

```bash
/home/zhangw/scan-calibrator/scan-panorama/stitch.sh \
  <本次扫描目录> --mount <desktop或hanging> \
  --pan-direction <increasing或decreasing>
```

`mount`只决定上下行顺序；左右列顺序使用第④步实拍得到的pan方向。交互式向导会自动传入，
不需要现场人员额外选择。

拼图完成后，终端返回大图的绝对存储路径，然后结束对话。回复`3`则不拼图并结束。

拼图结果统一保存在：

```text
/home/zhangw/scan-calibrator/scan-panorama/result/
```

应打开大图检查实际拼图是否存在超过5%的重叠或画面缺口。

## 批量部署注意事项

- 每一个摄像头点位都要重新记录角点；
- 摄像头型号或zoom变化时必须重新自动计算step；
- 不同型号的海康球机可能有相反的pan数值方向；向导会实拍识别，不能用desktop/hanging
  或“默认走短弧”代替；
- 标定期间不要同时从Web界面控制PTZ；
- 向导按轴设置目标重叠：水平4.5%、垂直2%；最终以完整试扫的接缝结果为准；
- 自动标定会完整测试全部候选step，再从所有可靠结果中筛选一致样本；
- 机械回差、镜头畸变和近景视差可能导致不同位置略有差异，最终必须完整试扫并拼图复核；