516 lines
15 KiB
Markdown
516 lines
15 KiB
Markdown
# 洪涝模块 GeoTIFF 化与 GAMMA 前处理评估
|
||
|
||
更新日期：2026-05-15
|
||
|
||
## 1. 结论
|
||
|
||
洪涝模块后续应把业务算法全部下放到标准 GeoTIFF 层：
|
||
|
||
```text
|
||
原始 SAR 数据
|
||
-> 可插拔前处理器：GAMMA 优先，其他处理器兜底
|
||
-> 分析级 GeoTIFF
|
||
-> Python 水体提取 / 洪涝检测 / 套合分析 / 产品生成
|
||
```
|
||
|
||
ENVI/SARscape 不再作为洪涝算法主线。它可以短期保留为历史兼容处理器，但不应继续决定数据模型、接口命名和算法逻辑。
|
||
|
||
GAMMA 适合作为第一候选前处理底座，原因是当前项目已经具备 WSL、PyINT、GAMMA 环境注入、DEM、`geocode_back`、`data2geotiff` 和 D-InSAR 生产发布经验。但现有 GAMMA/PyINT 接入是 D-InSAR pair 流程，不是洪涝需要的“单景分析级 GeoTIFF 预处理服务”。因此不能直接把 `lt1_gamma_dinsar` 或 `s1_gamma_dinsar` 原样接到洪涝预处理按钮上，必须新增单景前处理适配层。
|
||
|
||
## 2. 当前真实情况
|
||
|
||
### 2.1 洪涝模块当前仍绑定 ENVI/SARscape
|
||
|
||
当前 `/flood/preprocess` 最终仍执行旧的 `water_service.run_geocoding_workflow()`，内部流程是：
|
||
|
||
```text
|
||
SARsImportLuTan1
|
||
-> SARsBasicMultilooking
|
||
-> SARsBasicGeocoding
|
||
```
|
||
|
||
输出写入 `SARSceneGeoORM.geo_path`，语义是 SARscape 地理编码 dB 影像 base path，不是标准 GeoTIFF 交付物。
|
||
|
||
当前 `/flood/detections` 后台任务仍调用 `water_service.run_flood_detection()`，内部流程是：
|
||
|
||
```text
|
||
SARsBasicFeFloodingClassification
|
||
-> 可选 SARsBasicFeFloodingClassificationRefinement
|
||
-> rasterio 统计分类结果面积
|
||
```
|
||
|
||
分类值约定是：
|
||
|
||
```text
|
||
0 = 无数据 / 背景
|
||
1 = 稳定水体
|
||
2 = 洪涝 / 新增水体
|
||
3 = 高散射点
|
||
4 = 非水体
|
||
```
|
||
|
||
这说明当前“洪涝检测算法”实际是 SARscape 黑盒，不是平台自有算法。
|
||
|
||
### 2.2 已经接近目标形态的部分
|
||
|
||
以下部分已经更接近“标准栅格 + Python 算法”的目标：
|
||
|
||
```text
|
||
水体提取：
|
||
water_extraction_service -> water_detect_service
|
||
Otsu + DEM/坡度约束 + 形态学 + 连通分量过滤
|
||
|
||
套合分析：
|
||
flood_overlay_service
|
||
读取 classified 栅格，class=2 转矢量，套合灾害点、DInSAR 产品和 AOI
|
||
|
||
GF3：
|
||
gf3_service
|
||
Python/GDAL 完成 L1A -> L2：辐射定标 + RPC 几何校正
|
||
```
|
||
|
||
其中 GF3 路线虽然不走 GAMMA，但输出理念已经是“处理到 GeoTIFF 后进入平台算法”。它应该作为 `external/gdal` 前处理器接入统一 Scene，而不是继续挂在 `/water/gf3-process` 下。
|
||
|
||
### 2.3 当前 GAMMA/PyINT 接入情况
|
||
|
||
当前仓库里的 GAMMA/PyINT 能力主要服务 D-InSAR 生产：
|
||
|
||
```text
|
||
backend/app/dinsar_engines/pyint_engine.py
|
||
- lt1_gamma_dinsar
|
||
- s1_gamma_dinsar
|
||
|
||
backend/app/pyint_pipeline/run_lt1_pyint_pipeline.py
|
||
- LT-1 托管 runner
|
||
- geocode_gamma.py
|
||
- data2geotiff
|
||
- 标准产品发布
|
||
|
||
backend/app/pyint_pipeline/run_s1_pyint_pipeline.py
|
||
- Sentinel-1 runner
|
||
- 复用 LT-1 runner 的日志、发布和质量检查框架
|
||
|
||
deploy/wsl/profiles/gamma_env.sh
|
||
- 注入 GAMMA_HOME
|
||
- 注入 GAMMA 各模块 bin/scripts
|
||
- 注入 third_party/PyINT/pyint
|
||
```
|
||
|
||
当前 `.env` 中 PyINT/GAMMA 是启用状态：
|
||
|
||
```text
|
||
PYINT_ENABLED=true
|
||
PYINT_WSL_DISTRO=Ubuntu-24.04
|
||
PYINT_WSL_PYTHON=/home/administrator/miniconda3/envs/insar_wsl_v1/bin/python
|
||
PYINT_DEM_MODE=prepared_file
|
||
PYINT_PREPARED_DEM_PATH=D:\DEM\SRTMDEM_RSP_SARscape.wgs84
|
||
PYINT_GEO_INTERP=1
|
||
PYINT_GAMMA_NODATA_VALUE=-9999.0
|
||
```
|
||
|
||
需要注意一个不一致点：`pyint_engine.py` 已经暴露 `s1_gamma_dinsar`，但 `wsl_runtime_registry.py` 当前允许的 PyINT operation 仍只有 `lt1_gamma_dinsar` 和 `gamma_refine`。如果后续洪涝或生产任务走 WSL Broker，需要同步补齐允许列表。
|
||
|
||
### 2.4 GAMMA 现有输出与洪涝需求的差距
|
||
|
||
现有 D-InSAR GAMMA 链已经能导出 GeoTIFF，但输出重点是 pair 产品：
|
||
|
||
```text
|
||
disp.tif
|
||
disp_unmasked.tif
|
||
coh.tif
|
||
wrapped_phase.tif
|
||
vertical displacement
|
||
look vector
|
||
```
|
||
|
||
`hyp3format_gamma.py` 也能把 `geocode_gamma.py` 产生的 geocoded GAMMA 二进制导出为 GeoTIFF，包含：
|
||
|
||
```text
|
||
amp
|
||
corr
|
||
dem
|
||
unw_phase
|
||
wrapped_phase
|
||
los_disp
|
||
vert_disp
|
||
lv_theta
|
||
lv_phi
|
||
```
|
||
|
||
但洪涝模块真正需要的是单景产品：
|
||
|
||
```text
|
||
analysis_ready.tif
|
||
- 单景后向散射强度
|
||
- 明确单位：sigma0_db / gamma0_db / power_db
|
||
- 明确极化：VV / VH / HH / HV
|
||
- 明确 CRS、分辨率、nodata、覆盖范围
|
||
- 可与另一景重采样到同一网格
|
||
```
|
||
|
||
当前没有一个独立的 `gamma_single_scene_preprocess` 服务稳定地产出上述文件。现有 D-InSAR 流程里的 `geo_<master>_*.amp` 可以证明 GAMMA 有地理编码 MLI/AMP 的能力，但它嵌在 pair 配准和干涉流程中，不能直接作为洪涝单景预处理接口。
|
||
|
||
## 3. 目标数据契约
|
||
|
||
后续洪涝模块不再以 `geo_path` 表示模糊的“地理编码产物”，而应引入明确的分析级 Scene 产物语义。
|
||
|
||
建议模型命名：
|
||
|
||
```text
|
||
SarAnalysisScene / AnalysisReadyScene
|
||
```
|
||
|
||
最小字段：
|
||
|
||
```text
|
||
id
|
||
radar_data_id
|
||
engine # gamma / gf3_gdal / snap / envi_legacy / external
|
||
engine_profile # lt1_gamma_scene / s1_gamma_scene / gf3_rpc_l2
|
||
analysis_tif_path # 主分析 GeoTIFF
|
||
preview_path
|
||
coverage_polygon
|
||
satellite
|
||
satellite_family # LT1 / S1 / GF3 / ...
|
||
imaging_date
|
||
polarization
|
||
orbit_direction
|
||
relative_orbit
|
||
backscatter_unit # sigma0_db / gamma0_db / power_db / unknown
|
||
crs
|
||
pixel_size_x
|
||
pixel_size_y
|
||
nodata_value
|
||
grid_id # 同网格配对时使用
|
||
dem_path
|
||
incidence_angle_tif_path # 可选
|
||
layover_shadow_mask_path # 可选
|
||
quality_json
|
||
lineage_json
|
||
status
|
||
error_msg
|
||
created_at
|
||
updated_at
|
||
```
|
||
|
||
输出文件要求：
|
||
|
||
```text
|
||
analysis_ready.tif:
|
||
- GeoTIFF，优先 COG
|
||
- float32
|
||
- nodata = -9999
|
||
- 推荐值域为 dB
|
||
- rasterio/GDAL 可直接读取
|
||
|
||
preview.png:
|
||
- 仅用于地图快视
|
||
|
||
metadata.json:
|
||
- 记录处理器、命令、输入资产、DEM、参数、软件版本、质量检查
|
||
```
|
||
|
||
## 4. 目标流水线
|
||
|
||
### 4.1 前处理器只负责到 GeoTIFF 为止
|
||
|
||
前处理器接口建议统一为：
|
||
|
||
```text
|
||
submit_scene_preprocess(radar_data_id, engine="gamma", profile="auto")
|
||
```
|
||
|
||
处理器职责：
|
||
|
||
```text
|
||
1. 识别输入资产和传感器类型。
|
||
2. 导入原始产品到处理器内部格式。
|
||
3. 做必要的辐射定标。
|
||
4. 做多视 / 滤波 / speckle 控制。
|
||
5. 使用 DEM 做地形校正或地理编码。
|
||
6. 导出 analysis_ready.tif。
|
||
7. 生成 coverage、preview、metadata、quality。
|
||
8. 注册 SarAnalysisScene。
|
||
```
|
||
|
||
处理器不负责：
|
||
|
||
```text
|
||
1. 水体提取。
|
||
2. 洪涝分类。
|
||
3. 洪涝矢量化。
|
||
4. 灾害点套合。
|
||
5. 报告生成。
|
||
```
|
||
|
||
### 4.2 洪涝算法只认 GeoTIFF
|
||
|
||
水体提取：
|
||
|
||
```text
|
||
analysis_ready.tif
|
||
-> 读取 dB 栅格
|
||
-> 有效像元 / nodata / DEM / 坡度约束
|
||
-> Otsu 或自适应阈值
|
||
-> 形态学与连通域过滤
|
||
-> water_mask.tif + water_vector.geojson
|
||
```
|
||
|
||
洪涝检测：
|
||
|
||
```text
|
||
pre analysis_ready.tif
|
||
post analysis_ready.tif
|
||
-> 检查 CRS / 分辨率 / 极化 / 覆盖范围
|
||
-> 重采样到同一网格
|
||
-> 分别生成 pre_water_mask / post_water_mask
|
||
-> post_water && !pre_water = 洪涝 / 新增水体
|
||
-> pre_water && post_water = 稳定水体
|
||
-> 结合 dB 差值、DEM 坡度、连通域和面积阈值过滤
|
||
-> classified.tif
|
||
```
|
||
|
||
建议分类值继续沿用现有约定，降低前端和套合分析改动量：
|
||
|
||
```text
|
||
0 = nodata
|
||
1 = stable_water
|
||
2 = flood
|
||
3 = high_scatter_or_uncertain
|
||
4 = non_water
|
||
```
|
||
|
||
套合分析：
|
||
|
||
```text
|
||
classified.tif
|
||
-> class=2 转矢量
|
||
-> 灾害点命中
|
||
-> 近洪涝风险点
|
||
-> DInSAR 产品 footprint 相交
|
||
-> AOI / 行政区面积统计
|
||
```
|
||
|
||
## 5. GAMMA 适配性判断
|
||
|
||
| 能力项 | 当前情况 | 适配判断 |
|
||
| --- | --- | --- |
|
||
| WSL/GAMMA 环境 | 已有 `gamma_env.sh`，能注入 GAMMA 与 PyINT 路径 | 可复用 |
|
||
| LT-1 导入 | 已有 `down2slc_LT1_*` 与精轨桥接，历史上处理过几何问题 | 可作为第一批验证对象，但需专项 QA |
|
||
| Sentinel-1 导入 | PyINT 脚本支持 ZIP、EOF、burst、TOPS 相关流程，项目已有 `s1_gamma_dinsar` runner | 可做第二批，但 runtime operation 白名单需补齐 |
|
||
| GF3 | 当前项目已有 Python/GDAL L1A->L2，不依赖 GAMMA | 不建议强行走 GAMMA，先走 `gf3_gdal` 处理器 |
|
||
| 地理编码 | 已有 `geocode_gamma.py`、`geocode_back`、DEM 生成链 | 可复用思想和部分脚本 |
|
||
| GeoTIFF 导出 | 已有 `data2geotiff`、HyP3/标准产品导出经验 | 可复用 |
|
||
| 单景分析级输出 | 当前没有独立服务，D-InSAR 中只顺带产出 master amp | 需要新建 |
|
||
| 辐射定标语义 | Sentinel-1 导入使用 calibration XML；LT-1/GF3 各有差异 | 必须在 metadata 中明确单位，不能含糊写 dB |
|
||
| 生产稳定性 | 当前 D-InSAR runner 已有日志、repair、quality、manifest | 可复用框架，但不能复用 pair 假设 |
|
||
|
||
结论：GAMMA 适合做洪涝模块的优先前处理引擎，但第一阶段目标应是：
|
||
|
||
```text
|
||
LT-1 单景 -> GAMMA -> analysis_ready.tif
|
||
```
|
||
|
||
跑通并验证后再扩展：
|
||
|
||
```text
|
||
Sentinel-1 ZIP -> GAMMA -> analysis_ready.tif
|
||
GF3 L1A -> gf3_gdal -> analysis_ready.tif
|
||
```
|
||
|
||
## 6. 不应采用的方案
|
||
|
||
### 6.1 不应继续以 ENVI/SARscape 作为洪涝主线
|
||
|
||
原因：
|
||
|
||
```text
|
||
1. 数据格式和任务对象绑定 SARscape。
|
||
2. 洪涝分类是黑盒，难以解释和调参。
|
||
3. 服务器部署依赖重。
|
||
4. 后续多源数据扩展会反复补导入适配器。
|
||
5. 输出不天然适合平台统一发布。
|
||
```
|
||
|
||
### 6.2 不应把洪涝算法绑定到 GAMMA
|
||
|
||
GAMMA 应只负责把原始 SAR 处理成标准 GeoTIFF。洪涝算法不能依赖 GAMMA 中间二进制，也不能要求输入来自 GAMMA。否则只是把“绑定 ENVI”换成“绑定 GAMMA”。
|
||
|
||
正确边界是：
|
||
|
||
```text
|
||
GAMMA / GF3_GDAL / SNAP / ISCE / external
|
||
-> analysis_ready.tif
|
||
-> 同一套 Python 洪涝算法
|
||
```
|
||
|
||
### 6.3 不应直接复用 D-InSAR pair profile 做单景预处理
|
||
|
||
现有 `lt1_gamma_dinsar` / `s1_gamma_dinsar` 是 pair 生产 profile，包含：
|
||
|
||
```text
|
||
master/slave
|
||
coreg
|
||
diff
|
||
unwrap
|
||
geocode pair products
|
||
disp/coh export
|
||
```
|
||
|
||
洪涝单景预处理只需要：
|
||
|
||
```text
|
||
single scene import
|
||
radiometric calibration
|
||
multilook/filter
|
||
terrain correction/geocoding
|
||
GeoTIFF export
|
||
QA/register
|
||
```
|
||
|
||
两者不能混成一个 profile。
|
||
|
||
## 7. 建议实施阶段
|
||
|
||
### Phase 1：建立 GeoTIFF 数据契约
|
||
|
||
```text
|
||
1. 新建或扩展 Scene 表，明确 analysis_tif_path。
|
||
2. 保留旧 SARSceneGeoORM.geo_path 兼容字段。
|
||
3. /flood/scenes 改为优先返回 analysis_tif_path。
|
||
4. 前端把“可处理”判断改为是否存在 analysis_ready scene。
|
||
```
|
||
|
||
### Phase 2：先把洪涝检测改成 Python GeoTIFF 算法
|
||
|
||
```text
|
||
1. 新建 flood_detection_service.py。
|
||
2. 输入 pre_scene.analysis_tif_path 和 post_scene.analysis_tif_path。
|
||
3. 对齐网格。
|
||
4. 复用水体提取算法生成 pre/post water mask。
|
||
5. 输出 classified.tif。
|
||
6. 统计 flood_area_km2 和 stable_water_area_km2。
|
||
```
|
||
|
||
这一步可以先用 ENVI 现有 geocode 结果或 GF3 L2 GeoTIFF 做输入测试，目的是先解除洪涝分类对 SARscape 的依赖。
|
||
|
||
### Phase 3：新增 GAMMA LT-1 单景前处理器
|
||
|
||
建议新增：
|
||
|
||
```text
|
||
backend/app/services/sar_scene_preprocess_service.py
|
||
backend/app/services/gamma_scene_preprocess_service.py
|
||
backend/app/pyint_pipeline/run_gamma_scene_preprocess.py
|
||
```
|
||
|
||
最小 runner：
|
||
|
||
```text
|
||
1. stage LT-1 输入资产。
|
||
2. 调用 LT-1 导入脚本，产出 SLC。
|
||
3. multi_look 生成 MLI/AMP。
|
||
4. generate_rdc_dem 或等价 DEM 几何。
|
||
5. geocode_back 把 AMP 映射到地理网格。
|
||
6. data2geotiff 输出 analysis_ready.tif。
|
||
7. 可选转 COG。
|
||
8. rasterio 质量检查。
|
||
```
|
||
|
||
### Phase 4：接 Sentinel-1 和 GF3
|
||
|
||
Sentinel-1：
|
||
|
||
```text
|
||
1. 复用 Sentinel-1 ZIP/SAFE/EOF 管理设计。
|
||
2. 新增 s1_gamma_scene profile。
|
||
3. 不走 diff/unwrap，只产出单景 analysis_ready.tif。
|
||
4. 修正 WSL runtime operation 白名单。
|
||
```
|
||
|
||
GF3：
|
||
|
||
```text
|
||
1. 保留 gf3_service.py 的 GDAL/RPC 路线。
|
||
2. 输出注册为 analysis_ready scene。
|
||
3. 不强行改成 GAMMA。
|
||
```
|
||
|
||
### Phase 5：退役 ENVI 洪涝主线
|
||
|
||
```text
|
||
1. `/flood/detections` 默认使用 GeoTIFF 算法。
|
||
2. ENVI/SARscape 作为 `envi_legacy` 处理器保留一段时间。
|
||
3. 新任务不再默认创建 SARscape 洪涝分类。
|
||
4. 文档、界面和部署说明移除“ENVI 是洪涝必须项”的表述。
|
||
```
|
||
|
||
## 8. 验收标准
|
||
|
||
### 8.1 Scene 前处理
|
||
|
||
```text
|
||
1. 任意一个完成的 analysis_ready.tif 可以被 rasterio 打开。
|
||
2. CRS、bounds、transform、nodata 完整。
|
||
3. 有效像元比例达到阈值。
|
||
4. dB 值域在合理范围内。
|
||
5. metadata.json 能追溯输入资产、处理器、DEM、命令和版本。
|
||
6. preview 和 coverage 能在地图上显示和清除。
|
||
```
|
||
|
||
### 8.2 洪涝检测
|
||
|
||
```text
|
||
1. pre/post 两个 GeoTIFF 可自动对齐到同一网格。
|
||
2. classified.tif 只依赖 Python/rasterio/numpy/scipy/skimage，不调用 ENVI/SARscape。
|
||
3. class=1/2 面积统计稳定。
|
||
4. 套合分析可直接读取 classified.tif。
|
||
5. 同一算法能跑 GAMMA TIF、GF3 L2 TIF 和其他外部 TIF。
|
||
```
|
||
|
||
### 8.3 GAMMA 适配
|
||
|
||
```text
|
||
1. LT-1 单景 GAMMA 前处理能稳定产出 analysis_ready.tif。
|
||
2. 失败时有明确阶段日志，不出现“任务成功但全 0”的假成功。
|
||
3. data2geotiff 输出通过 GDAL/rasterio 质量检查。
|
||
4. 处理器输出不要求后续算法知道 GAMMA 中间目录结构。
|
||
```
|
||
|
||
## 9. 对部署的影响
|
||
|
||
Git 可以提供平台代码、Python 算法、任务编排、数据库迁移和前端能力，但不能内置 GAMMA 商业软件本体。另一台服务器部署时必须额外满足：
|
||
|
||
```text
|
||
1. WSL 或 Linux 环境可用。
|
||
2. GAMMA 安装路径可被 gamma_env.sh 发现，或配置 PYINT_GAMMA_HOME/GAMMA_HOME。
|
||
3. PyINT 代码随仓库存在。
|
||
4. WSL Python/conda 环境具备 rasterio、GDAL、numpy、scipy、skimage 等依赖。
|
||
5. DEM、轨道池和源数据池路径在 .env 中配置。
|
||
```
|
||
|
||
如果目标服务器没有 GAMMA，系统仍应允许：
|
||
|
||
```text
|
||
1. 使用已经存在的 analysis_ready.tif。
|
||
2. 使用 GF3_GDAL 处理器。
|
||
3. 后续接 SNAP/ISCE/external 处理器。
|
||
4. 继续执行水体提取、洪涝检测、套合分析和产品生成。
|
||
```
|
||
|
||
这也是把算法下放到 GeoTIFF 层的核心价值。
|
||
## 2026-05-16 implementation note
|
||
|
||
The first code pass now implements LT1 and GF3 as analysis-ready scene preprocessors:
|
||
|
||
- Current config roots: `SAR_ANALYSIS_READY_ROOT` and `SAR_ANALYSIS_WORK_ROOT`. `SAR_ANALYSIS_PREVIEW_ROOT` was removed; previews live beside each analysis-ready scene.
|
||
- `sar_scene_geo` now stores `analysis_tif_path`, `analysis_dir`, preview path, engine/profile, backscatter unit, nodata, metadata and quality JSON.
|
||
- `/flood/preprocess` routes GF3 scenes to `gf3_gdal` standardization and LT1 scenes to `lt_gamma` single-scene preprocessing.
|
||
- GF3 uses the existing GDAL/RPC L1A->L2 result, then registers the selected L2 GeoTIFF under `SAR_ANALYSIS_READY_ROOT`.
|
||
- LT1 uses a new Gamma/PyINT runner that stops at single-scene geocoded MLI GeoTIFF and does not write into D-InSAR product directories.
|
||
- Water extraction, flood detection and scene previews now prefer `analysis_tif_path` and fall back to legacy `geo_path`.
|
||
- Startup database maintenance now treats Alembic `0004` as the managed head, can auto-add missing ORM columns/indexes, and records the `alembic_version` marker after the schema is healthy.
|
||
- `/health?full=true&refresh=true` now includes `sar_analysis_ready` root and scene-path checks.
|
||
|
||
This keeps D-InSAR product publication isolated from flood/water analysis inputs.
|