zhanghuilai/WQ_GUI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
WQ_GUI/docs/项目交接文档.md

8.7 KiB
Raw Permalink Blame History

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

文档用途：帮助新负责人快速理解仓库结构、运行方式、核心逻辑与维护要点。
适用仓库：本地工程 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）下：

python src/gui/water_quality_gui.py

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

3.2 打包 Windows exe

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

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 初版：目录结构、步骤映射、工作目录新命名、打包与多进程注意事项

联系人（请交接时填写）

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