150 lines
4.1 KiB
Markdown
150 lines
4.1 KiB
Markdown
# scan-panorama 端侧扫描验证拼图
|
||
|
||
这个程序用于在RK3588端快速验证`scan`输出是否完整、网格顺序是否正确。
|
||
它读取指定扫描目录中的`meta.json`，根据每张图片的`row`和`col`恢复二维网格，
|
||
生成一张总览大图。
|
||
|
||
这里生成的是**验证用网格拼图**，不会执行后台服务器上的球面投影、特征融合、
|
||
畸变校正和无缝全景优化。输入小图不会被复制、修改或删除。
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
scan-panorama/
|
||
├── README.md
|
||
├── stitch.sh
|
||
├── stitch_scan.py
|
||
└── result/
|
||
└── <扫描ID>_<安装方式>_scan_grid_panorama.jpg
|
||
```
|
||
|
||
程序只把最终拼图保存在`result/`，运行中的临时文件会自动删除。
|
||
|
||
## 依赖
|
||
|
||
- Python 3
|
||
- ImageMagick的`identify`和`montage`
|
||
|
||
当前RK3588设备已经安装这些依赖，可用下面的命令检查：
|
||
|
||
```bash
|
||
python3 --version
|
||
identify -version
|
||
montage -version
|
||
```
|
||
|
||
## 最简单的使用方法
|
||
|
||
进入程序目录：
|
||
|
||
```bash
|
||
cd /home/zhangw/scan-calibrator/scan-panorama
|
||
```
|
||
|
||
查看可用扫描目录：
|
||
|
||
```bash
|
||
find /userdata/data/scan -mindepth 1 -maxdepth 1 -type d -printf '%f\n' | sort
|
||
```
|
||
|
||
指定扫描目录名进行拼图：
|
||
|
||
```bash
|
||
./stitch.sh 2026-07-22_18-25-09 --mount desktop
|
||
```
|
||
|
||
必须用`--mount`声明球机安装方式：
|
||
|
||
```bash
|
||
# 办公室测试：球机正放桌面，摄像头后台将画面旋转180度
|
||
./stitch.sh 2026-07-22_18-25-09 --mount desktop
|
||
|
||
# 野外部署：球机物理倒挂
|
||
./stitch.sh 2026-07-22_18-25-09 --mount hanging
|
||
```
|
||
|
||
- `desktop`同时反转网格行顺序和列顺序；
|
||
- `hanging`按`meta.json`原始row/col顺序排列；
|
||
- 两种模式都不会旋转或镜像单张图片，只改变图片在大图中的位置。
|
||
|
||
目录名会自动解析为：
|
||
|
||
```text
|
||
/userdata/data/scan/2026-07-22_18-25-09
|
||
```
|
||
|
||
也可以直接传绝对路径：
|
||
|
||
```bash
|
||
./stitch.sh /userdata/data/scan/2026-07-22_18-25-09 --mount desktop
|
||
```
|
||
|
||
结果保存在：
|
||
|
||
```text
|
||
/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行时，最终大图为：
|
||
|
||
```text
|
||
7680×2880
|
||
```
|
||
|
||
这是推荐的快速验证尺寸。
|
||
|
||
如果异常配置产生了很多列或很多行，默认尺寸会使大图超过ImageMagick的尺寸上限，
|
||
程序会自动缩小每个单格并打印“尺寸保护”提示，而不是直接报错。
|
||
|
||
如果希望使用小图原始分辨率拼接，传入`--tile-width 0`：
|
||
|
||
```bash
|
||
./stitch.sh 2026-07-22_18-25-09 --mount desktop --tile-width 0
|
||
```
|
||
|
||
12列×8行的全分辨率结果为15360×5760，占用更多内存、时间和磁盘空间。
|
||
|
||
也可以指定其他单格宽度和JPEG质量：
|
||
|
||
```bash
|
||
./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正常读取。
|
||
|
||
任一检查失败时不会生成拼图，并会在终端中说明具体问题。
|
||
|
||
## 如何查看结果
|
||
|
||
桌面环境下可以直接打开：
|
||
|
||
```bash
|
||
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信息，
|
||
完成球面投影及无缝融合。
|