推送

说明文档

@@ -0,0 +1,186 @@
+# 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`
+
+---