water-body-segmentation/README_water_GUI.md

water_GUI.py 使用说明（SAM3 水体分割 GUI）

本说明文档对应脚本：water_GUI.py。
该脚本是 纯 GUI 启动器：界面负责参数编辑、提示说明、日志与进度展示；真正的分割计算由 water_V5.py 提供的 run_segmentation() 执行，并在点击“运行”时才会被懒加载导入。

1. 功能概览

• 选择输入 GeoTIFF（待分割遥感影像）与输出掩膜 GeoTIFF 路径
• 编辑分割参数（Overview/Coarse/Fine/Region/Post）
• 鼠标悬停在参数输入框上显示详细提示（tooltip）
• 后台线程执行分割，GUI 不会卡死
• 右侧日志窗口实时输出运行信息
• 进度条显示子区域处理进度
• 支持“停止”（会在子区域边界处响应）

2. 运行方式

在项目目录下运行：

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

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