gengxin

README.md

@@ -14,6 +14,7 @@ scan-calibrator/
 ├── interactive_calibrator.py
 ├── calibrate.sh                # 手动配置入口
 ├── scan_calibrator.py
+├── history/                    # 每次交互向导的完整或中途标定记录（运行时生成）
 ├── src/measure_overlap.cpp
 ├── result/                     # 运行时生成的scan配置片段
 └── scan-panorama/
@@ -41,14 +42,19 @@ cd /home/zhangw/scan-calibrator
 运行`install.sh`会自动补齐。ImageMagick安装在RK3588宿主机，而不是smart-cam容器内，
 因为验证拼图程序运行在宿主机。
 
-只需要输入：
+常用输入：
 
 - `1`：确认、执行或选择野外部署；
 - `2`：只在第一个问题中表示办公室测试；
-- `3`：结束对话，并清理本次未完成向导生成的标定状态和临时标定截图；
+- 历史记录选择处输入`1`、`2`、`3`等序号：复用对应记录，输入`0`新建，输入`q`退出；
+- 左上角和右下角既可回复`1`读取摄像头，也可直接粘贴
+  `pan=21720 (217.20°), tilt=1268 (12.68°), zoom=4580 (45.80×)`；
+- 除历史记录选择处外，`3`：结束对话并保留当前标定进度；
 - `Ctrl+C`：等同于退出。
 
-退出不会删除历史扫描目录，也不会回滚已经明确确认替换并重启的`config.json`。
+每次启动都会建立一条独立历史记录。退出不会删除已记录的角点、已测得的单轴step、
+已生成的配置、历史扫描目录，也不会回滚已经明确确认替换并重启的`config.json`。
+临时标定截图仍会清理，避免长期占用设备磁盘。
 
 ## 完整对话示例
 
@@ -57,21 +63,27 @@ cd /home/zhangw/scan-calibrator
 
 ```text
 您好！我们现在开始配置扫图参数！
-在接下来的对话中，回复 3 会立即结束，并清理本次向导产生的标定痕迹。
+标定进度会逐步保存；中途回复 3 或按 Ctrl+C 退出后，下次运行仍可选择本次记录继续。
 
 ① 当前是【野外部署阶段】（回复 1）还是【办公室测试阶段】（回复 2）？
 > 2
 
+在第②步之前发现以下历史标定记录（最新的排在前面）：
+1. 2026-09-10T10:20:30+08:00，安装方式=办公室正放，左上角=有，右下角=有，pan_step=有，tilt_step=无
+2. 2026-09-09T16:10:00+08:00，安装方式=野外倒挂，左上角=有，右下角=无，pan_step=无，tilt_step=无
+输入对应序号复用；回复 0 不复用并新建；回复 q 退出。
+> 0
+
 ② 请在Web界面中设置左上角zoom，再手动把摄像头移到扫描区域的【左上角】。
-到位后回复 1；回复 3 随时退出。
+摄像头到位后回复 1 读取当前位置；也可以直接输入pan、tilt、zoom；回复 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，程序会从两个角点zoom的平均值向上选择最近可达的最终扫描zoom。
+摄像头到位后回复 1 读取当前位置；也可以直接输入pan、tilt、zoom；回复 3 随时退出。
+> pan=13420 (134.20°), tilt=-340 (-3.40°), zoom=810 (8.10×)
+已采用手动输入: pan=13420 (134.20°), tilt=-340 (-3.40°), zoom=810 (8.10×)
 
 ④ 这一步用于测量当前zoom下的水平/垂直视场。
 请把摄像头移到扫描区域内部、距离较远且纹理分布在整幅画面的位置。
@@ -176,8 +188,11 @@ smart-cam的HTTP接口读取PTZ并记录，等价于：
 ./calibrate.sh mark bottom-right
 ```
 
-向导会显示两个角点的zoom，并取算术平均值作为最终扫描zoom。第四步开始测量前，
-程序会自动把镜头切换到该平均zoom，因此视场标定与最终配置使用同一焦段。
+向导会显示两个角点的zoom，并以算术平均值作为选择最终扫描zoom的下界。第四步开始测量前，
+程序会自动把镜头切换到该平均zoom；即使摄像头当前已经显示为这个zoom，也会明确下发一次
+绝对zoom命令并回读。若算术平均值不是摄像头可达档位，程序会在平均值上方查找最近的可达档位，
+例如平均值`4565`只能落到`4550`或`4580`时采用`4580`。视场标定和最终生成配置都会使用
+回读确认的同一个可达zoom，不会再把不可达平均值写入配置。
 
 ### ④ 自动计算pan_step和tilt_step
 
@@ -211,8 +226,22 @@ smart-cam的HTTP接口读取PTZ并记录，等价于：
 
 不要把画面对准纯天空、纯墙、纯水面、玻璃、近距离物体或重复图案。水面场景应让岸线、
 浮标等固定物体横向分布在画面中，不能只依赖不断变化的水纹。
-测量过程中程序会锁定两个角点的平均zoom；自动对焦不影响zoom。标定失败时可以只更换第四步的位置重试，
-不需要重新记录左上角和右下角。
+测量过程中程序会锁定上述实际可达的扫图zoom；自动对焦不影响zoom。标定失败时可以只更换
+第四步的位置重试，不需要重新记录左上角和右下角。pan或tilt任一方向已经成功时会立刻保存，
+另一方向失败或退出后，下次可以只继续尚未完成的方向。
+
+### 历史记录复用
+
+进入第②步前，向导会读取`history/session_*.json`并按时间倒序编号，逐条显示是否已经包含：
+
+- 左上角位置；
+- 右下角位置；
+- `pan_step`；
+- `tilt_step`。
+
+输入序号后，已有角点会直接跳过；只有一个角点时只补录另一个；只有一个轴的step时只补测另一个。
+如果四项都齐全，向导会询问直接复用还是重新测量step。复用会建立一条新的本次记录，原历史文件
+不会被覆盖。升级前已有的`calibration.json`也会自动导入历史记录一次。
 
 ### ⑤ 显示最终参数