# 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 “停止”不立即生效

停止信号会在子区域边界处检查，因此可能需要等待当前子区域处理完成后才退出。