176 lines
8.7 KiB
Markdown
176 lines
8.7 KiB
Markdown
# 水质参数反演分析系统 — 项目交接文档
|
||
|
||
> 文档用途：帮助新负责人快速理解仓库结构、运行方式、核心逻辑与维护要点。
|
||
> 适用仓库：本地工程 **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 | 初版：目录结构、步骤映射、工作目录新命名、打包与多进程注意事项 |
|
||
|
||
---
|
||
|
||
**联系人（请交接时填写）**
|
||
|
||
| 角色 | 姓名 | 联系方式 |
|
||
|------|------|----------|
|
||
| 移交人 | | |
|
||
| 接收人 | | |
|