scan-calibrator/scan-panorama/README.md

scan-panorama 端侧扫描验证拼图

这个程序用于在RK3588端快速验证scan输出是否完整、网格顺序是否正确。 它读取指定扫描目录中的meta.json，根据每张图片的row和col恢复二维网格， 生成一张总览大图。

这里生成的是验证用网格拼图，不会执行后台服务器上的球面投影、特征融合、 畸变校正和无缝全景优化。输入小图不会被复制、修改或删除。

目录结构

scan-panorama/
├── README.md
├── stitch.sh
├── stitch_scan.py
└── result/
    └── <扫描ID>_<安装方式>_scan_grid_panorama.jpg

程序只把最终拼图保存在result/，运行中的临时文件会自动删除。

依赖

• Python 3
• ImageMagick的identify、convert和montage

当前RK3588设备已经安装这些依赖，可用下面的命令检查：

python3 --version
identify -version
montage -version
convert -version

最简单的使用方法

进入程序目录：

cd /home/zhangw/scan-calibrator/scan-panorama

查看可用扫描目录：

find /userdata/data/scan -mindepth 1 -maxdepth 1 -type d -printf '%f\n' | sort

指定扫描目录名进行拼图：

./stitch.sh 2026-07-22_18-25-09 --mount desktop --pan-direction increasing

必须用--mount声明球机安装方式：

# 办公室测试：球机正放桌面，摄像头后台将画面旋转180度
./stitch.sh 2026-07-22_18-25-09 --mount desktop --pan-direction increasing

# 野外部署：球机物理倒挂
./stitch.sh 2026-07-22_18-25-09 --mount hanging --pan-direction increasing

• desktop反转上下行顺序，hanging保持上下行顺序；
• --pan-direction increasing表示画面左到右时pan递增，列保持正序；
• --pan-direction decreasing表示画面左到右时pan递减，列反序；
• pan方向由交互式标定第④步自动识别，不能根据desktop/hanging猜测；
• 两种模式都不会旋转或镜像单张图片，只改变图片在大图中的位置。

目录名会自动解析为：

/userdata/data/scan/2026-07-22_18-25-09

也可以直接传绝对路径：

./stitch.sh /userdata/data/scan/2026-07-22_18-25-09 --mount desktop

结果保存在：

/home/zhangw/scan-calibrator/scan-panorama/result/2026-07-22_18-25-09_desktop_scan_grid_panorama.jpg

文件名中的2026-07-22_18-25-09就是对应的扫描ID。重复执行同一个扫描目录时， 会更新该扫描ID对应的结果，不会生成多个无意义副本。

输出尺寸

默认将每张1280×720小图缩小为640×360。12列×8行时，最终大图为：

7680×2880

这是推荐的快速验证尺寸。

如果异常配置产生了很多列或很多行，默认尺寸会使大图超过ImageMagick的尺寸上限， 程序会自动缩小每个单格并打印“尺寸保护”提示，而不是直接报错。

如果希望使用小图原始分辨率拼接，传入--tile-width 0：

./stitch.sh 2026-07-22_18-25-09 --mount desktop --tile-width 0

12列×8行的全分辨率结果为15360×5760，占用更多内存、时间和磁盘空间。

也可以指定其他单格宽度和JPEG质量：

./stitch.sh 2026-07-22_18-25-09 --mount desktop --tile-width 800 --quality 95

程序会自动检查什么

拼图前会检查：

1. 指定目录和meta.json是否存在；
2. images记录是否包含有效的row、col和file；
3. row/col是否从0连续编号；
4. 网格中是否存在缺失位置或重复位置；
5. 所有小图是否存在且文件大小不为0；
6. 所有小图的分辨率是否一致；
7. 图片是否可以被ImageMagick正常读取。

任一检查失败时不会生成拼图，并会在终端中说明具体问题。

大型网格和内存保护

程序不会一次性打开全部4K原图，而是按以下顺序处理：

1. 每次只读取一张原图并生成缩略图；
2. 每一行的小缩略图合并完成后立即删除该行临时缩略图；
3. 最后把已经缩小的行图纵向合并为验证大图。

若ImageMagick仍报告cache resources exhausted、内存分配失败或临时缓存空间不足，程序会 自动把单格宽度降到原计划的75%、50%并重新尝试。临时目录无论成功失败都会删除，不需要提高 ImageMagick的系统缓存上限，也不会影响原始扫描图片。

如何查看结果

桌面环境下可以直接打开：

xdg-open /home/zhangw/scan-calibrator/scan-panorama/result/2026-07-22_18-25-09_desktop_scan_grid_panorama.jpg

也可以把result/中的图片复制到自己的电脑查看。验证时重点检查：

• 每一行是否按水平方向连续变化；
• 相邻列是否存在共同画面；
• 行与行之间俯仰方向是否连续；
• 是否有黑图、空图、重复图或明显漏掉的方向；
• 360°首尾方向是否能对应起来。

后台正式拼接时，应继续使用同一目录下meta.json中的目标PTZ和实际PTZ信息， 完成球面投影及无缝融合。