# 水质参数反演分析系统 — 项目交接文档

> 文档用途：帮助新负责人快速理解仓库结构、运行方式、核心逻辑与维护要点。  
> 适用仓库：本地工程 **fengzhuang-ui2V3**（水质 GUI + 反演流水线）。

---

## 1. 项目概述

本系统为 **基于遥感影像与机器学习的水质反演桌面应用**：水域掩膜、耀斑检测与去除、CSV/光谱处理、监督与非经验建模、采样与预测、空间制图与报告生成。  

- **图形界面**：PyQt5，主入口 `src/gui/water_quality_gui.py`。  
- **业务编排**：GUI 使用 `src/core/water_quality_inversion_pipeline_GUI.py` 中的 `WaterQualityInversionPipeline`；命令行/无 GUI 场景可参考 `src/core/water_quality_inversion_pipeline.py`（子目录命名已与 GUI 管线对齐，但 **不含** 步骤 5.5 / 6.5 / 6.75 等扩展目录的完整定义，以 GUI 管线为准）。  
- **打包**：PyInstaller，`scripts/water_quality_gui_file.spec`，单文件 exe，`console=False`。

---

## 2. 目录结构（精简）

```
项目根/
├── src/
│   ├── gui/                    # PyQt5 主界面、步骤面板、工作线程
│   ├── core/                   # 反演流水线、去耀斑、建模、预测、非经验反演
│   ├── preprocessing/          # 光谱预处理、水质数据加工
│   ├── postprocessing/         # 制图、可视化、Word 报告、航迹等
│   ├── visualization/        # 可视化包初始化（具体实现多在 postprocessing）
│   └── utils/                  # 水域提取、指数、采样、工具函数
├── data/                       # 图标、公式子数据等静态资源
├── scripts/                    # PyInstaller spec、构建产物常出现在 scripts/build|dist
├── docs/                       # 说明文档（含本文）
├── requirements*.txt         # pip/conda 依赖清单
├── README.md / README-conda.md # 安装与 conda 说明
└── README_SAMPLING_MAP.md      # 采样地图相关说明（若仍写旧目录名，需与下文「工作目录」对照更新）
```

---

## 3. 运行方式

### 3.1 开发运行 GUI

在项目根目录（或已将 `src` 加入 `PYTHONPATH`）下：

```bash
python src/gui/water_quality_gui.py
```

依赖见 `requirements.txt`；地理栈（GDAL/rasterio 等）建议在 **Conda** 环境按 `README-conda.md` / `requirements-conda.txt` 安装。

### 3.2 打包 Windows exe

在已激活的构建环境中执行（路径按本机调整）：

```bash
pyinstaller scripts/water_quality_gui_file.spec
```

产物一般为 `scripts/dist/water_quality_gui.exe`（以 spec 中 `name` 为准）。spec 中已收集 rasterio 动态库、conda `Library/bin` 下 DLL、`data/icons` 等。

### 3.3 多进程说明（Windows / 打包）

- 若使用 **sklearn `GridSearchCV(n_jobs=-1)`** 等并行，joblib 会起子进程；**冻结 exe 时可能出现控制台窗口闪烁**。缓解思路：线程后端 `parallel_backend("threading")`、或 `n_jobs=1`、或模型内部 `n_jobs` 并行（需改 `modeling_batch.py`，交接时按需评估）。  
- 入口脚本建议在 `if __name__ == "__main__":` 内、启动 GUI 前调用 `multiprocessing.freeze_support()`，以符合 PyInstaller + multiprocessing 规范（是否已加请以当前 `water_quality_gui.py` 为准）。

---

## 4. GUI 与流水线步骤对应关系

界面上的「步骤」通过 `WorkerThread.run_single_step` 映射到管线方法（配置键名与面板一致，如 `step6`、`step5_5`）：

| 配置键 / 逻辑步骤 | 管线方法名 |
|-------------------|------------|
| step1 | `step1_generate_water_mask` |
| step2 | `step2_find_glint_area` |
| step3 | `step3_remove_glint` |
| step4 | `step4_process_csv` |
| step5 | `step5_extract_training_spectra` |
| step5_5 | `step5_5_calculate_water_quality_indices` |
| step6 | `step6_train_models` |
| step6_5 | `step6_5_non_empirical_modeling` |
| step6_75 | `step6_75_custom_regression` |
| step7 | `step7_generate_sampling_points` |
| step8 | `step8_predict_water_quality` |
| step8_5 | `step8_5_predict_with_non_empirical_models` |
| step8_75 | `step8_75_predict_with_custom_regression` |
| step9 | `step9_generate_distribution_map` |

单步运行时会注入 `skip_dependency_check=True`，便于独立调试；全流程运行仍应保证输入/前置步骤产物存在。

---

## 5. 工作目录（work_dir）子文件夹命名

所有中间结果默认写在用户选择的 **工作目录** 下。当前代码中约定如下（**若磁盘上仍为旧文件夹名，需手动改名或重新跑流程**）：

| 子目录名 | 含义 |
|----------|------|
| `1_water_mask` | 水域掩膜 |
| `2_glint` | 耀斑相关 |
| `3_deglint` | 去耀斑影像 |
| `4_processed_data` | 处理后数据 |
| `5_training_spectra` | 训练光谱等 |
| `6_water_quality_indices` | 水质指数（原 `5_5_water_quality_indices`） |
| `7_models` | 监督学习模型（原 `6_models`） |
| `8_non_empirical_models` | 非经验模型（原 `6_5_non_empirical_models`） |
| `9_custom_regression` | 自定义回归结果（原 `6_75_custom_regression`） |
| `10_sampling` | 采样点/光谱（原 `7_sampling`） |
| `11_12_13_predictions` | 预测 CSV 等（原 `8_predictions`） |
| `14_visualization` | 图表、分布图、预览等（原 `9_visualization`） |
| `reports` | 报告输出（原 `10_reports`） |

**定义位置**：`water_quality_inversion_pipeline_GUI.py` 构造函数中对 `self.*_dir` 的赋值；GUI 中大量路径拼接需与此一致（如 `14_visualization`、`7_models`）。

---

## 6. 核心模块说明

| 模块路径 | 职责 |
|----------|------|
| `src/gui/water_quality_gui.py` | 主窗口、各步骤面板、线程 Worker、图像查看、配置收集与单步/全流程触发 |
| `src/core/water_quality_inversion_pipeline_GUI.py` | GUI 用流水线：步骤实现、目录管理、与可视化/报告类协作 |
| `src/core/water_quality_inversion_pipeline.py` | 无扩展步骤目录时的管线实现，供脚本或非 GUI 参考 |
| `src/core/modeling/modeling_batch.py` | 批量训练、`GridSearchCV`、模型落盘（joblib） |
| `src/core/prediction/inference_batch.py` | 批量预测与模型加载 |
| `src/core/glint_removal/*.py` | Goodman、Hedley、Kutser、SUGAR 等去耀斑算法 |
| `src/postprocessing/visualization_reports.py` | 水质可视化封装（输出目录常指向 `14_visualization`） |
| `src/postprocessing/report_word.py` | Word 报告；默认从 `work_dir/14_visualization` 等读图 |
| `src/postprocessing/map.py` | 分布图、插值相关（内含开发者本地示例路径，勿当生产配置） |

---

## 7. 依赖与环境

- **Python**：3.8+（README 声明；实际环境以 `requirements-py310.txt` 等为准）。  
- **关键库**：PyQt5、numpy、pandas、scipy、scikit-learn、joblib、matplotlib、rasterio/geopandas（视功能启用）、opencv-python、Pillow 等。  
- **Conda**： GDAL 等二进制依赖推荐用 conda-forge，见 `README-conda.md`。

---

## 8. 维护与排错提示

1. **资源路径（打包后图标不显示）**：冻结运行时勿依赖 `Path(__file__)` 指向源码树；应使用 `sys._MEIPASS` 或项目内统一的 `get_icon_path()` 类逻辑。  
2. **tqdm / 无控制台**：打包 GUI 时若 `sys.stdout` 为 `None`，tqdm 可能报错；`Goodman.py` 等处已对 frozen GUI 做了 `disable` 处理，新增进度条时注意同样处理。  
3. **配置与 YAML**：全流程配置由 GUI 各面板 `get_config()` 汇总；改字段名需同步管线 `**config['stepX']` 形参。  
4. **文档滞后**：`README_SAMPLING_MAP.md` 等若仍出现 `9_visualization` 等旧目录名，应以本文第 5 节为准或更新该文档。

---

## 9. 交接检查清单

- [ ] 已能在本机用 `python src/gui/water_quality_gui.py` 启动 GUI 并完成一次最小流程（或关键单步）。  
- [ ] 已确认 Conda/pip 环境与 `README-conda.md`、`requirements.txt` 一致。  
- [ ] 已阅读 `scripts/water_quality_gui_file.spec`，知悉打包入口与 `datas` 列表。  
- [ ] 已知悉 `work_dir` 子目录当前命名，并能区分「配置键 step6」与「文件夹 `7_models`」。  
- [ ] 已记录客户/内部使用的 **工作目录样例** 与 **典型输入数据格式**（CSV 列、影像格式）。  
- [ ] Git 远程、发布分支、Issue/需求跟踪方式已交接。  
- [ ] 许可证与第三方库合规（MIT 与 README 声明等）已确认。

---

## 10. 文档修订记录

| 日期 | 说明 |
|------|------|
| 2026-04-09 | 初版：目录结构、步骤映射、工作目录新命名、打包与多进程注意事项 |

---

**联系人（请交接时填写）**  

| 角色 | 姓名 | 联系方式 |
|------|------|----------|
| 移交人 | | |
| 接收人 | | |