118 lines
4.3 KiB
Markdown
118 lines
4.3 KiB
Markdown
# water_GUI.py 使用说明（SAM3 水体分割 GUI）
|
||
|
||
本说明文档对应脚本：[water_GUI.py](file:///e:/code/sam3-main/sam3-main/water_GUI.py)。
|
||
该脚本是 **纯 GUI 启动器**：界面负责参数编辑、提示说明、日志与进度展示；真正的分割计算由 [water_V5.py](file:///e:/code/sam3-main/sam3-main/water_V5.py) 提供的 `run_segmentation()` 执行，并在点击“运行”时才会被懒加载导入。
|
||
|
||
## 1. 功能概览
|
||
|
||
- 选择输入 GeoTIFF（待分割遥感影像）与输出掩膜 GeoTIFF 路径
|
||
- 编辑分割参数（Overview/Coarse/Fine/Region/Post）
|
||
- 鼠标悬停在参数输入框上显示详细提示（tooltip）
|
||
- 后台线程执行分割，GUI 不会卡死
|
||
- 右侧日志窗口实时输出运行信息
|
||
- 进度条显示子区域处理进度
|
||
- 支持“停止”（会在子区域边界处响应）
|
||
|
||
## 2. 运行方式
|
||
|
||
在项目目录下运行：
|
||
|
||
```bash
|
||
python e:\code\sam3-main\sam3-main\water_GUI.py
|
||
```
|
||
|
||
运行后：
|
||
- 点击“浏览”选择输入影像（`.tif/.tiff`）
|
||
- 点击“浏览”选择输出掩膜路径（建议 `.tif`）
|
||
- 调整参数（可保持默认）
|
||
- 点击“运行”
|
||
|
||
## 3. 依赖与环境
|
||
|
||
GUI 本身依赖：
|
||
- Python 标准库 `tkinter`
|
||
|
||
执行分割时会懒加载并依赖（来自 water_V5.py）：
|
||
- torch（建议 CUDA 可用）
|
||
- rasterio
|
||
- numpy
|
||
- scipy
|
||
- pillow
|
||
- tqdm
|
||
- 以及 sam3 模型代码与权重（由项目现有加载逻辑处理）
|
||
|
||
## 4. 参数说明（界面分组）
|
||
|
||
### 4.1 Overview 兜底
|
||
|
||
用于减少“中心水域漏检”。Overview 会对每个子区域做一次低分辨率全局预测，并在最终输出中与 coarse/fine 结果取并集。
|
||
|
||
- `overview_max_side`：兜底预测的最大边长。越大越准越慢。
|
||
- `overview_threshold`：兜底阈值。偏低可减少漏检，但误检会增加。
|
||
|
||
### 4.2 Coarse 粗分割
|
||
|
||
粗分割用于提高召回、生成精修的边缘带（band），并与 overview 一起决定精修区域范围。
|
||
|
||
- `coarse_threshold`：粗分割阈值。偏低提高召回，偏高减少误检。
|
||
- `coarse_tile_size`：粗分割分块大小（原图像素）。
|
||
- `coarse_tile_overlap`：粗分割块重叠像素。
|
||
- `coarse_downsample_factor`：粗分割输出降采样比例。2 更细更慢；4 折中；8 更快更粗。
|
||
- `band_radius`：边缘带半径（原图像素）。越大精修范围越大，速度越慢。
|
||
|
||
### 4.3 Fine 精修
|
||
|
||
只对边缘带覆盖到的区域进行精细分割，补足边界细节。
|
||
|
||
- `final_threshold`：最终阈值。偏低更易连通，偏高更干净。
|
||
- `fine_tile_size`：精修分块大小（原图像素）。一般 1536 更稳，2048 更快但更吃显存/更慢。
|
||
- `fine_overlap`：精修块重叠像素。越大接缝越少但更慢。
|
||
|
||
### 4.4 Region 子区域
|
||
|
||
将整图划分成多个有重叠的子区域，降低内存峰值。
|
||
|
||
- `num_splits_y`：纵向切分数。
|
||
- `num_splits_x`：横向切分数。
|
||
- `region_overlap`：子区域重叠像素，减少子区域边界断裂。
|
||
|
||
### 4.5 Post 后处理
|
||
|
||
- `min_area`：移除小碎片的最小连通域面积（像素）。
|
||
- `keep_largest_only`：只保留最大连通域（适合只要最大水体）。
|
||
|
||
## 5. 输出说明
|
||
|
||
输出文件为单通道 `uint8` 掩膜 GeoTIFF：
|
||
- 0：非水体
|
||
- 1：水体
|
||
|
||
输出文件的空间参考（CRS/transform）来自输入影像的 profile。
|
||
|
||
## 6. 使用建议（16GB 显存）
|
||
|
||
优先按以下顺序调参：
|
||
- 先把 `fine_tile_size` 从 2048 降到 1536（更稳）
|
||
- `fine_overlap` 从 256 降到 128（更快，可能稍有拼接缝）
|
||
- `coarse_downsample_factor` 从 4 改 2（更细更慢，但中心/边缘召回更稳）
|
||
- `overview_threshold` 从 0.4 降到 0.35（召回更强，误检更可能增加）
|
||
|
||
## 7. 常见问题
|
||
|
||
### 7.1 点击“运行”后报 `ModuleNotFoundError: water_V5`
|
||
|
||
确保 `water_GUI.py` 与 `water_V5.py` 在同一目录：
|
||
- `e:\code\sam3-main\sam3-main\water_GUI.py`
|
||
- `e:\code\sam3-main\sam3-main\water_V5.py`
|
||
|
||
并从该目录执行运行命令，或将该目录加入 Python 路径。
|
||
|
||
### 7.2 界面正常但运行很慢
|
||
|
||
这通常是正常的：粗分割/精修会对大量瓦片做模型推理。优先调小 `fine_tile_size`、`fine_overlap`，并提高 `coarse_downsample_factor`。
|
||
|
||
### 7.3 “停止”不立即生效
|
||
|
||
停止信号会在子区域边界处检查，因此可能需要等待当前子区域处理完成后才退出。
|
||
|