Harmon
d108b33f80
- add documentation governance and cleanup audit documents - update README and docs index to distinguish current vs historical sources - move superseded planning, SBAS, Gamma, and experiment notes into docs/archive - fix remaining archive text garbling in two documents
164 lines
6.5 KiB
Markdown
164 lines
6.5 KiB
Markdown
# GAMMA + WSL2 双引擎集成方案
|
||
|
||
## Context
|
||
|
||
当前系统使用 ENVI/SARscape 做 D-InSAR 处理，速度慢（单对处理需数十分钟到数小时）。用户有 GAMMA License，希望在 Windows 服务器的 WSL2 中部署 GAMMA 作为第二处理引擎。ENVI 保留不动，用户可在前端选择用哪个引擎。
|
||
|
||
GAMMA 通过 WSL2 调用完全可行：`subprocess.run(['wsl', '-d', 'Ubuntu', 'bash', '-c', 'gamma_cmd ...'])`，与现有 ENVI 的 subprocess 模式一致。
|
||
|
||
---
|
||
|
||
## 架构对比
|
||
|
||
```
|
||
ENVI 链路（保留不动）：
|
||
POST /idl/jobs/dinsar (engine=envi)
|
||
→ SystemJob(IDL_RUN_DINSAR) → envi_runner_cli 子进程
|
||
→ envi_dinsar.run_dinsar_custom_workflow() → 6步 SARscape
|
||
→ envipyengine → taskengine.exe
|
||
|
||
GAMMA 链路（新增）：
|
||
POST /idl/jobs/dinsar (engine=gamma)
|
||
→ SystemJob(GAMMA_RUN_DINSAR) → gamma_runner_cli 子进程
|
||
→ gamma_dinsar.run_dinsar_workflow() → 9步 GAMMA CLI
|
||
→ subprocess.run(['wsl', ...]) → GAMMA 原生命令
|
||
```
|
||
|
||
两条链路共享：SystemTask/SystemJob 任务队列、progress.json 进度机制、job_worker 监控逻辑。
|
||
|
||
---
|
||
|
||
## 新增文件
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| `backend/app/services/gamma_service.py` | WSL2 执行器、路径转换（win↔wsl）、配置读取、环境检查、进度写入 |
|
||
| `backend/app/services/gamma_dinsar.py` | GAMMA D-InSAR 9步工作流 |
|
||
| `backend/app/services/gamma_runner_cli.py` | 子进程 CLI 入口（对标 envi_runner_cli.py） |
|
||
| `backend/app/services/gamma_import.py` | LT-1 原始数据 → GAMMA SLC 格式导入 |
|
||
| `scripts/check_gamma_wsl.py` | GAMMA + WSL2 环境诊断脚本 |
|
||
|
||
## 修改文件
|
||
|
||
| 文件 | 修改内容 |
|
||
|------|----------|
|
||
| `.env` | 新增 `GAMMA_ENABLED`、`GAMMA_WSL_DISTRO`、`GAMMA_HOME`、`GAMMA_ENV_SCRIPT`、`GAMMA_DEM_FILE` 等配置 |
|
||
| `backend/app/config.py` | Settings 类新增 GAMMA 配置字段 |
|
||
| `backend/app/services/job_handlers.py` | 新增 `GAMMA_RUN_DINSAR` handler，注册到 `_HANDLERS` |
|
||
| `backend/app/routers/idl.py` | `DinsarJobRequest` 新增 `engine` 字段（envi/gamma），路由分发 |
|
||
| `frontend/src/IDLAutomationPanel.jsx` | Step 2 新增引擎选择器（radio：ENVI / GAMMA），GAMMA 不可用时灰显 |
|
||
| `frontend/src/api/idl.js` | `queueDinsarJob` payload 新增 `engine` |
|
||
|
||
---
|
||
|
||
## GAMMA D-InSAR 9步工作流
|
||
|
||
每步通过 `gamma_service.gamma_exec(cmd, work_dir)` → `wsl -d {distro} bash -c 'source gamma_env.sh && {cmd}'` 执行。
|
||
|
||
| 步骤 | GAMMA 命令 | 功能 | 对应 ENVI 步骤 |
|
||
|------|-----------|------|---------------|
|
||
| 1 | LT-1 导入（自定义） | 原始数据 → .slc + .slc.par | SARsImportLuTan1 |
|
||
| 2 | `gc_map` | DEM 准备 + lookup table | （ENVI 内置在 Step1） |
|
||
| 3 | `create_offset` + `offset_pwr` + `offset_fit` + `SLC_interp` | 配准 | InterferogramGeneration 内部 |
|
||
| 4 | `SLC_intf` + `multi_look` | 干涉图生成 | InterferogramGeneration |
|
||
| 5 | `adf` | 自适应滤波（Goldstein） | FilterAndCoherence |
|
||
| 6 | `cc_wave` | 相干性估计 | FilterAndCoherence |
|
||
| 7 | `mcf` | 相位解缠 | PhaseUnwrapping |
|
||
| 8 | `dispmap` | 相位→位移 | PhaseToDisplacement |
|
||
| 9 | `geocode_back` + `data2geotiff` | 地理编码 + 转 GeoTIFF | PhaseToDisplacement |
|
||
|
||
---
|
||
|
||
## 关键设计
|
||
|
||
### 路径转换
|
||
```python
|
||
def win_to_wsl(win_path: str) -> str:
|
||
# Z:\Test_data\Task_001 → /mnt/z/Test_data/Task_001
|
||
# D:\SRTM\dem.tif → /mnt/d/SRTM/dem.tif
|
||
```
|
||
|
||
### 进度跟踪
|
||
写入与 ENVI 完全相同格式的 `backend/runtime/idl_worker/job_{id}_progress.json`，job_handler 的 keepalive 无需修改。GAMMA 的 `total_steps=9`（ENVI 为 6），进度公式 `(pair_index-1+step/total)/total_pairs` 天然适配。
|
||
|
||
### 输出格式统一
|
||
GAMMA 最终输出转为 GeoTIFF（`data2geotiff`），同时生成 ENVI `.hdr`，使 `extract_disp_results()` 和 D-InSAR 结果扫描能统一识别。
|
||
|
||
### 前端引擎选择
|
||
页面加载时调 `GET /gamma/status` 检查 GAMMA 是否可用。可用时显示 radio 选择器，不可用时 GAMMA 选项灰显标注"(未配置)"。
|
||
|
||
---
|
||
|
||
## .env 配置项
|
||
|
||
```ini
|
||
# ============ GAMMA + WSL2 配置 ============
|
||
# 总开关（false 则前端不显示 GAMMA 选项）
|
||
GAMMA_ENABLED=false
|
||
|
||
# WSL2 发行版名称（wsl -l -v 查看）
|
||
GAMMA_WSL_DISTRO=Ubuntu-22.04
|
||
|
||
# GAMMA 安装路径（Linux 路径，WSL2 内部）
|
||
GAMMA_HOME=/opt/GAMMA_SOFTWARE-20230101
|
||
|
||
# GAMMA 环境初始化脚本（source 此文件后 GAMMA 命令可用）
|
||
GAMMA_ENV_SCRIPT=/opt/GAMMA_SOFTWARE-20230101/gamma_env.sh
|
||
|
||
# DEM 文件路径（Windows 路径，自动转为 WSL 路径）
|
||
GAMMA_DEM_FILE=D:\SRTM30m\srtm_dem.tif
|
||
|
||
# 处理参数
|
||
GAMMA_GEOCODE_PIXEL_SIZE_M=10.0
|
||
GAMMA_ADF_WINDOW_SIZE=32
|
||
GAMMA_MCF_COH_THRESHOLD=0.3
|
||
GAMMA_RANGE_LOOKS=4
|
||
GAMMA_AZIMUTH_LOOKS=1
|
||
```
|
||
|
||
---
|
||
|
||
## 分阶段实施
|
||
|
||
### Phase 1：基础设施 + 环境验证
|
||
- `.env` / `config.py` 配置层
|
||
- `gamma_service.py`：`win_to_wsl()`、`wsl_exec()`、`gamma_exec()`、`check_gamma_environment()`
|
||
- `scripts/check_gamma_wsl.py` 诊断脚本
|
||
- `GET /gamma/status` 端点
|
||
- 手动验证：`wsl -d Ubuntu bash -c 'source gamma_env.sh && which par_S1_SLC'`
|
||
|
||
### Phase 2：LT-1 数据导入（技术风险最高）
|
||
- `gamma_import.py`：解析 LT-1 `.meta.xml` → 构建 GAMMA `.slc.par` 参数文件
|
||
- **关键验证**：对一个 Task_*/master/ 执行导入，检查 .slc.par 参数是否正确
|
||
- 如果 GAMMA 内置 LT-1 支持，直接调用；否则需手工构建参数文件
|
||
|
||
### Phase 3：D-InSAR 核心工作流
|
||
- `gamma_dinsar.py`：9步工作流
|
||
- `gamma_runner_cli.py`：CLI 入口
|
||
- 逐步调试，每步验证输入输出
|
||
|
||
### Phase 4：任务调度 + 前端集成
|
||
- `job_handlers.py`：新增 GAMMA handler
|
||
- `idl.py`：engine 字段分发
|
||
- `IDLAutomationPanel.jsx`：引擎选择器
|
||
- 端到端测试
|
||
|
||
---
|
||
|
||
## 风险点
|
||
|
||
1. **LT-1 导入**（最大风险）：GAMMA 是否内置 LT-1 读取器需要安装后确认。Plan B：用 GDAL 读 TIFF + 手工构建 .slc.par
|
||
2. **WSL2 跨文件系统 I/O**：`/mnt/z/` 比 WSL 原生文件系统慢 ~5x。初期可接受，后续可优化为先拷贝到 WSL 内部处理
|
||
3. **GAMMA License**：WSL2 中需配置 FlexLM `LM_LICENSE_FILE`，在 `gamma_env.sh` 中统一设置
|
||
|
||
---
|
||
|
||
## 验证
|
||
|
||
1. `py_compile` 所有新增/修改的 .py 文件
|
||
2. `npm run build` 前端构建通过
|
||
3. `python scripts/check_gamma_wsl.py` 环境诊断通过
|
||
4. 前端选 GAMMA 引擎 → 提交任务 → 进度正常更新 → 输出 GeoTIFF 位移图
|
||
5. 前端选 ENVI 引擎 → 行为与改造前完全一致（回归测试）
|
||
6. GAMMA 未配置时 → 前端 GAMMA 选项灰显，无法选择
|