# 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`

---