186 lines
6.3 KiB
Plaintext
186 lines
6.3 KiB
Plaintext
# StripStitch（航带批量配准工具）使用说明
|
||
|
||
## 1. 工具简介
|
||
|
||
`StripStitch.py` 用于将一个文件夹中的多幅 `.bip` 航带影像批量配准到一幅参考底图 `.tif`（GeoTIFF）上，输出配准后的 BIP 文件，并生成配准统计 CSV、日志与可视化结果（若启用/代码包含）。
|
||
|
||
支持的能力（按当前脚本实现为准）：
|
||
- GUI 图形界面：选择输入/输出、配置 matcher、选择变换模型、设置质量阈值与过滤参数
|
||
- 参考底图可选“掩膜”：先用 `tif_caijain.py` 对底图做 NoData 掩膜，再用掩膜后的底图执行配准
|
||
- 统计 CSV：每次运行生成独立文件（文件名包含时间戳）
|
||
- 出错弹窗：处理线程异常会弹窗显示完整 traceback，便于定位问题
|
||
|
||
---
|
||
|
||
## 2. 目录结构（建议）
|
||
|
||
建议将脚本与相关文件保持在同一目录（当前工程已是）：
|
||
|
||
- `e:\code\vismatch-main\vismatch-main\test\StripStitch.py`
|
||
- `e:\code\vismatch-main\vismatch-main\test\tif_caijain.py`
|
||
- `e:\code\vismatch-main\vismatch-main\vismatch\`（matcher 依赖）
|
||
|
||
---
|
||
|
||
## 3. 环境依赖
|
||
|
||
### 3.1 必需依赖（运行 GUI/配准）
|
||
- Python 3.9+（建议与现有环境一致）
|
||
- `numpy`
|
||
- `opencv-python`（cv2）
|
||
- `rasterio`
|
||
- `affine`
|
||
- `vismatch`（本仓库内模块）
|
||
|
||
### 3.2 可选依赖（对应功能可用/不可用）
|
||
- `scikit-image`：piecewise/polynomial 变换相关
|
||
- `matplotlib` + `scipy`：凸包内点判定等
|
||
- `SimpleITK` / `pirt` / `scipy.interpolate`：TPS 相关
|
||
- `tqdm`：掩膜处理进度条（已做无控制台环境兼容）
|
||
|
||
---
|
||
|
||
## 4. 输入数据要求
|
||
|
||
### 4.1 参考底图（GeoTIFF）
|
||
- 文件格式：`.tif` / `.tiff`
|
||
- 应包含正确 CRS 与 transform（地理参考信息）
|
||
|
||
### 4.2 待配准航带（ENVI BIP）
|
||
- 文件格式：`.bip`
|
||
- 建议包含合理的波段与 NoData（若有）
|
||
|
||
### 4.3 （可选）底图掩膜（GeoTIFF）
|
||
启用“底图掩膜”时：
|
||
- 掩膜必须是与底图 **严格对齐** 的 GeoTIFF（同 CRS、同 transform、同 width/height）
|
||
- `tif_caijain.py` 默认逻辑：掩膜中值等于 `1` 的像素会被置为 NoData（可在后续扩展为 GUI 可配）
|
||
|
||
---
|
||
|
||
## 5. GUI 使用方法（推荐）
|
||
|
||
### 5.1 启动 GUI
|
||
在 Windows PowerShell 或 CMD 中运行：
|
||
|
||
```powershell
|
||
cd "e:\code\vismatch-main\vismatch-main\test"
|
||
python "StripStitch.py"
|
||
```
|
||
|
||
### 5.2 GUI 字段说明
|
||
- 参考TIF文件：要配准到的底图
|
||
- 启用底图掩膜：勾选后需要选择掩膜 TIF，并会先生成“掩膜后的底图”
|
||
- BIP文件夹：包含待配准 `.bip` 的文件夹（程序会遍历 `*.bip`）
|
||
- 输出文件夹：所有输出写入此目录
|
||
- 匹配算法：选择 matcher（例如 `matchanything-roma`）
|
||
- 设备：`cuda`（更快）或 `cpu`
|
||
- 变换方法：可多选，按优先级尝试（可上移/下移顺序）
|
||
- 参数设置：匹配缩放、ROI 扩展、质量阈值、边缘/纹理过滤等
|
||
|
||
### 5.3 开始/停止
|
||
- 开始处理：开始批量配准
|
||
- 停止处理：设置停止标记，当前文件处理结束后停止
|
||
|
||
---
|
||
|
||
## 6. 命令行模式（CLI）
|
||
|
||
脚本保留了 CLI 模式入口（若实现支持 `--cli`）：
|
||
|
||
```powershell
|
||
python "StripStitch.py" --cli
|
||
```
|
||
|
||
说明：
|
||
- CLI 模式下通常使用脚本顶部的默认配置（REF_TIF / BIP_DIR / OUT_DIR 等）。
|
||
- 若需要完整参数化 CLI，可后续再扩展 argparse。
|
||
|
||
---
|
||
|
||
## 7. 输出说明
|
||
|
||
假设输出目录为 `OUT_DIR`：
|
||
|
||
### 7.1 统计 CSV
|
||
每次运行会生成一个新 CSV：
|
||
|
||
- `OUT_DIR\stats\registration_stats_YYYYMMDD_HHMMSS.csv`
|
||
|
||
内容包含（示例字段）：
|
||
- 时间戳、文件名、匹配点/内点数、内点比例、所选方法、误差统计、成功与否等
|
||
|
||
### 7.2 掩膜后的底图（如果启用底图掩膜）
|
||
- `OUT_DIR\masked_refs\<底图名>_masked_<时间戳>.tif`
|
||
|
||
配准时会使用这个掩膜后的底图作为参考。
|
||
|
||
### 7.3 配准输出
|
||
- 脚本会将每个 `.bip` 配准后输出到 `OUT_DIR`（具体命名以代码为准，例如 `_registered.bip`）。
|
||
|
||
---
|
||
|
||
## 8. 常见问题与排查
|
||
|
||
### 8.1 处理过程中发生错误: No module named 'src'
|
||
原因：
|
||
- `matchanything-*` 依赖第三方源码目录（`vismatch/third_party/MatchAnything/.../src`），打包或运行时没有被正确加入 `sys.path`。
|
||
|
||
解决：
|
||
- 确保 PyInstaller spec 中把 `vismatch/third_party` 打进包里（Tree 方式）
|
||
- 运行时脚本会尝试从 `_MEIPASS` 和 exe 目录自动寻找 third_party 并加入 `sys.path`
|
||
- 如果仍失败，检查 dist 目录下是否存在：
|
||
- `dist\StripStitch\_internal\vismatch\third_party\MatchAnything\imcui\third_party\MatchAnything\src\`
|
||
|
||
### 8.2 No module named 'loguru'
|
||
原因：
|
||
- MatchAnything 的第三方代码中引用了 `loguru`
|
||
|
||
解决：
|
||
- 打包时将 `loguru` 加入 hiddenimports（或安装 loguru）
|
||
- 脚本也提供了缺失时的兼容 stub（以避免直接崩溃）
|
||
|
||
### 8.3 底图掩膜时报错：'NoneType' object has no attribute 'write'
|
||
原因：
|
||
- PyInstaller `console=False` 时 tqdm 可能没有可写的输出流
|
||
|
||
解决：
|
||
- `tif_caijain.py` 已处理：无控制台环境会自动禁用 tqdm 或使用安全输出，不应再崩溃
|
||
- 重新打包并运行最新代码
|
||
|
||
---
|
||
|
||
## 9. 打包（PyInstaller，文件夹模式 onedir）
|
||
|
||
### 9.1 使用 spec 打包
|
||
在 `test` 目录执行：
|
||
|
||
```powershell
|
||
pyinstaller --clean -y "e:\code\vismatch-main\vismatch-main\test\StripStitch.spec"
|
||
```
|
||
|
||
输出：
|
||
- `dist\StripStitch\StripStitch.exe`（以及同目录依赖文件）
|
||
|
||
### 9.2 打包注意事项
|
||
- 若你改动了 `.spec` 或 `.py`，务必 `--clean` 重新打包
|
||
- 深度学习 matcher 依赖多，出现 “No module named xxx” 时通常需要：
|
||
- spec 增加 hiddenimports
|
||
- 或把第三方源码目录作为 datas 打进去
|
||
- 或做运行时兼容 stub（仅当该依赖不影响核心逻辑/可替代）
|
||
|
||
---
|
||
|
||
## 10. 建议的使用流程（从零到一）
|
||
|
||
1) 准备底图 `result.tif` 与待配准 `.bip` 文件夹
|
||
2) （可选）准备与底图对齐的掩膜 `result_mask.tif`（值=1 为去除区域）
|
||
3) 启动 GUI，选择底图、BIP 文件夹、输出目录
|
||
4) 选择 matcher（建议从 `matchanything-roma` 或你已验证可用的 matcher 开始）
|
||
5) 选择变换方法（建议先 `affine + homography`）
|
||
6) 点“开始处理”，观察日志与进度
|
||
7) 处理结束后查看：
|
||
- 输出 BIP
|
||
- `stats\registration_stats_*.csv`
|
||
- （可选）`masked_refs\*_masked_*.tif`
|
||
|
||
--- |