Harmon/insar-management-system-v2

Fork 0

Files

T

Harmon b1c59051b9 docs: update production workflow design and runtime changes

2026-06-14 18:47:00 +08:00

14 KiB

Raw Blame History

洪涝灾害分析模块工程交接文档

日期：2026-06-02
面向对象：算法工程师、后端工程师
范围：新洪涝灾害分析模块 /flood/*，不包含旧兼容 /water/* 页面和接口。

1. 当前定位

系统现在把洪涝分析拆成两层：

工程层：负责数据入库、场景标准化、任务队列、状态更新、预览上图、套合分析、产品登记。
算法层：只负责从标准化 SAR GeoTIFF 生成水体/洪涝分类栅格，并返回面积、像元数、阈值、模型信息等元数据。

后续算法优化应尽量只替换或新增 processor，不要绕开现有 SARSceneGeoORM、WaterExtractionORM、FloodDetectionORM 和任务队列。

2. 关键代码入口

职责	文件
洪涝 API 路由	`backend/app/routers/flood.py`
洪涝业务编排	`backend/app/services/flood_analysis_service.py`
后台任务执行	`backend/app/services/job_handlers.py`
analysis-ready GeoTIFF 注册	`backend/app/services/sar_analysis_ready_service.py`
当前水体提取算法	`backend/app/services/water_detect_service.py`
水体 processor 包装	`backend/app/services/water_extraction_service.py`
当前洪涝变化检测算法	`backend/app/services/flood_detection_service.py`
洪涝矢量化与套合	`backend/app/services/flood_overlay_service.py`
洪涝产品登记	`backend/app/services/flood_product_service.py`
前端工作台	`frontend/src/FloodAnalysisWorkspace.jsx`
前端 API	`frontend/src/api/flood.js`

旧 /water/* 路由仍在，但只作为历史兼容，不作为新算法接入目标。

3. 数据模型

3.1 SARSceneGeoORM

表：sar_scene_geo

这是算法输入场景表。每条记录对应一景已标准化的 SAR 分析影像。

关键字段：

字段	含义
`radar_data_id`	关联源影像 `radar_data.id`
`analysis_tif_path`	算法统一输入，单波段 GeoTIFF
`analysis_dir`	analysis-ready 目录
`analysis_preview_path`	场景预览 PNG
`analysis_engine`	标准化引擎，如 `gf3_sarscape`、`gf3_gdal`、`lt_gamma`
`analysis_profile`	标准化 profile
`analysis_backscatter_unit`	后向散射单位，如 `sigma0_db`、`unknown`
`analysis_quality_json`	栅格尺寸、范围、nodata、采样统计
`pixel_size_m`	近似像元大小
`status`	`PENDING/RUNNING/DONE/FAILED`

当前 GF3 SARscape 链路会先产出原生 _geo ENVI 二进制，再由平台转换为 D:\production_results\gf3\standard_l2 下的 GeoTIFF，并注册到这里。

3.2 WaterExtractionORM

表：water_extractions

用于单景水体提取。

关键字段：

字段	含义
`scene_id`	输入场景
`processor`	算法名称，当前默认 `otsu`
`input_path`	实际输入 GeoTIFF
`output_path`	输出水体掩膜 GeoTIFF
`preview_path`	预留，目前预览按需渲染
`vector_path`	预留，用于未来水体矢量
`water_area_km2`	水体面积
`water_pixel_count`	水体像元数
`threshold_value`	阈值或模型置信阈值
`metadata_json`	算法元数据
`status/error_msg/task_id`	任务状态

3.3 FloodDetectionORM

表：flood_detections

用于灾前/灾后两景洪涝变化检测。

关键字段：

字段	含义
`pre_scene_id`	灾前场景
`post_scene_id`	灾后场景
`output_dir`	输出目录，默认 `WATER_RESULTS_DIR/flood_{id}`
`classified_path`	分类结果 GeoTIFF
`flood_area_km2`	新增洪涝面积
`stable_water_area_km2`	稳定水体面积
`status/error_msg`	任务状态

分类图当前约定：

值	类别	前端颜色
0	nodata	透明
1	stable_water	蓝色
2	flood	红色
3	high_backscatter	橙色
4	non_water	灰色

4. 现有业务流程

4.1 单景水体提取

流程：

前端选择 SARSceneGeo
-> POST /flood/water-extractions { scene_id }
-> 创建 WaterExtractionORM(PENDING)
-> 创建 SystemJob: WATER_DETECT
-> job_handlers._handle_water_detect
-> water_extraction_service.run_otsu_water_extraction
-> water_detect_service.run_water_detection
-> 写 water_mask.tif
-> 更新 WaterExtractionORM 为 DONE/FAILED
-> 前端 GET /flood/water-extractions/{id}/preview 上图

当前输出目录：

WATER_RESULTS_DIR/
  water_extraction_{id}/
    water_mask.tif

当前算法状态：

Otsu 阈值；
GF3 线性强度自动转 10*log10；
支持 COPDEM/SRTM 类 DEM 栅格约束；
中值滤波、高斯滤波、形态学、连通域过滤；
可作为 baseline，不适合作为最终高精度算法。

4.2 灾前/灾后洪涝检测

流程：

前端输入灾害日期 + 行政区 AOI
-> POST /flood/disaster-pairs/search
-> 后端按时间窗、AOI 覆盖率、重叠率推荐 pre/post 配对
-> POST /flood/detections { pre_scene_id, post_scene_id, refine }
-> 创建 FloodDetectionORM(PENDING)
-> 创建 SystemJob: FLOOD_DETECTION
-> job_handlers._handle_flood_detection
-> flood_detection_service.run_geotiff_flood_detection
-> 写 classified.tif/flood_mask.tif/stable_water_mask.tif/metadata.json
-> 更新 FloodDetectionORM
-> 前端加载 pre/post/classified 图层

当前输出目录：

WATER_RESULTS_DIR/
  flood_{id}/
    classified.tif
    flood_mask.tif
    stable_water_mask.tif
    metadata.json

当前算法状态：

灾前、灾后分别 Otsu；
灾后水体且灾前非水体判为 flood；
灾前灾后均水体判为 stable_water；
可选 refine 做简单形态学清理；
支持灾前重投影到灾后网格；
还未接入更强的 GF3 双极化分类、深度学习或弱监督模型。

4.3 套合分析

流程：

FloodDetection DONE
-> POST /flood/detections/{id}/overlay
-> classified.tif 中 value=2 的 flood 区域矢量化
-> 与灾害点、DInSAR 产品、行政区 AOI 套合
-> 写 flood_detection_{id}_overlay.geojson
-> 新增 FloodOverlayORM

输出：

WATER_RESULTS_DIR/
  flood_overlays/
    flood_detection_{id}_overlay.geojson

4.4 产品登记

流程：

FloodDetection DONE
-> POST /flood/detections/{id}/products
-> 创建 FloodProductORM
-> GET /flood/products 或 /flood/results 查询

当前只是轻量登记，没有完整归档包导出。

5. analysis-ready 输入契约

算法工程师应以 SARSceneGeoORM.analysis_tif_path 为唯一标准输入。

输入约定：

项	要求
格式	单波段 GeoTIFF
坐标	有 CRS，推荐 EPSG:4326 或投影坐标
transform	必须正确
nodata	支持 `NaN` 或明确 nodata
单位	可能是 dB，也可能是线性强度，需读 `analysis_backscatter_unit` 或自行稳健判断
文件大小	GF3 单极化可达几千万像元

现有 GF3 SARscape 标准化结果大致为：

数据来自 ENVI/SARscape _geo；
转为 GeoTIFF 后注册；
analysis_backscatter_unit 当前可能为 unknown；
实际数值可能是线性强度，需做 dB 转换。

6. 算法 processor 输出契约

6.1 水体提取 processor

建议新增统一接口：

def run_xxx_water_extraction(
    *,
    input_path: str,
    output_dir: str,
    job_id: str | None = None,
    options: dict | None = None,
) -> dict:
    ...

{
    "ok": True,
    "processor": "gf3_rf_v1",
    "output_path": ".../water_mask.tif",
    "water_area_km2": 123.45,
    "water_pixel_count": 123456,
    "threshold_value": 0.62,
    "metadata": {
        "model_version": "...",
        "features": ["hh_db", "hv_db", "ratio", "slope"],
        "confidence_path": ".../water_probability.tif"
    }
}

最低要求：

output_path 是 GeoTIFF；
水体像元值为 255 或 1，背景为 0；
CRS/transform 与输入一致；
nodata 推荐为 0；
面积统计要与输出一致。

6.2 洪涝检测 processor

建议接口：

def run_xxx_flood_detection(
    *,
    pre_tif_path: str,
    post_tif_path: str,
    output_dir: str,
    job_id: str | None = None,
    refine: bool = False,
    options: dict | None = None,
) -> dict:
    ...

{
    "ok": True,
    "processor": "gf3_change_rf_v1",
    "classified_path": ".../classified.tif",
    "flood_mask_path": ".../flood_mask.tif",
    "stable_water_mask_path": ".../stable_water_mask.tif",
    "metadata_path": ".../metadata.json",
    "flood_area_km2": 12.34,
    "stable_water_area_km2": 56.78,
    "flood_pixel_count": 12345,
    "stable_water_pixel_count": 67890,
    "metadata": {
        "model_version": "...",
        "pre_scene_reprojected": True
    }
}

classified.tif 必须遵守第 3.3 节的分类值，否则前端预览和套合分析会失效。

7. 推荐算法路线

7.1 短期：GF3 快速分类器

目标：替换当前单阈值水体提取，减少误判。

建议 processor 名称：

gf3_rf_v1
gf3_lgbm_v1

输入：

优先支持 GF3 HH/HV 双极化；
如果系统当前只注册单极化 analysis_ready.tif，工程侧需要补充“同一产品多极化查找”能力，或算法先支持单极化。

特征建议：

HH_db
HV_db
HH-HV
HH/HV ratio
局部均值、方差、纹理；
DEM 高程、坡度；
可选永久水体、河网、土地覆盖先验。

样本策略：

第一版可用弱监督样本：永久水体为正样本，远离水系/坡度较大/高后向散射区域为负样本；
后续在系统内加入人工修正样本导出；
不建议用当前 Otsu 结果直接当唯一标签。

7.2 中期：GF3 深度学习推理

目标：面向洪涝产品的高质量识别。

可参考：

Sen2GF3Floods：GF3 洪水数据集和 PyTorch 代码；
FCN/UNet++/DeepLabV3+/SegFormer；
支持 patch 推理和边缘重叠融合。

工程要求：

模型权重必须版本化；
processor 输出必须仍是标准 GeoTIFF；
推理可以 GPU 加速，但不能阻塞任务队列主进程；
大图必须 tile 化，避免一次性占满显存/内存。

7.3 保留 baseline

当前 otsu 应保留为：

快速预览；
无模型时兜底；
算法对比 baseline。

不建议作为最终默认高质量结果。

8. 工程侧下一步

8.1 后端 processor 注册

建议在 water_extraction_service.py 增加 processor 分发：

def run_water_extraction(processor: str, **kwargs):
    if processor == "otsu":
        return run_otsu_water_extraction(**kwargs)
    if processor == "gf3_rf_v1":
        return run_gf3_rf_water_extraction(**kwargs)
    ...

FloodWaterExtractionRequest 需要增加：

processor: str = "otsu"
options: dict | None = None

然后 submit_water_extraction 把 processor/options 写入 WaterExtractionORM 和 job payload。

8.2 多极化场景组织

目前 SARSceneGeoORM 与 RadarDataORM 基本是一景一条。GF3 标准化链路可能存在 HH/HV 两个 GeoTIFF，但洪涝算法输入仍是单 analysis_tif_path。

如果算法需要 HH/HV，应补一个工程能力：

在 analysis_metadata_json 中记录同产品全部极化 GeoTIFF；
或新增 SARSceneBandORM/analysis_assets 表；
或在 processor 内根据当前路径和命名规则寻找同目录同产品 HV/HH。

建议先采用 metadata 方案，改动最小。

8.3 水体结果矢量化

当前水体提取只按需返回 PNG 预览，没有持久化矢量。

建议新增：

water_vector_path GeoJSON；
confidence_path 概率图；
preview_path 持久 PNG；
后端接口支持水体结果矢量上图。

8.4 质量评估字段

建议 metadata_json 至少写入：

processor
model_version
input_paths
features
threshold
confidence_stats
valid_pixel_count
water_ratio
runtime_seconds
warnings

8.5 前端入口

当前前端有水体提取按钮，但没有 processor 选择。

建议增加：

水体提取 processor 下拉框；
快速 Otsu / GF3 RF / 深度学习；
结果行显示 processor 和模型版本；
可选显示置信度图层。

9. 算法开发边界

算法工程师只需要保证：

能读取输入 GeoTIFF；
能输出符合契约的 GeoTIFF；
返回标准 dict；
大图处理不会把内存/显存打爆；
错误抛出清晰异常或返回 {"ok": False, "error": "..."}。

算法工程师不需要处理：

前端；
任务队列；
用户权限；
数据库事务；
资产扫描；
上图预览；
套合分析；
产品登记。

10. 当前风险和已知问题

当前 Otsu 水体提取误判较多，只能作为 baseline。
GF3 双极化没有形成正式算法输入契约。
analysis_backscatter_unit 对 GF3 SARscape 输出仍可能是 unknown。
洪涝变化检测仍是双阈值差分，复杂地物下误判会明显。
水体和洪涝结果缺少质量评价和置信度图层。
产品登记还不是完整归档包。
旧 /water/* 和新 /flood/* 共存，后续需要逐步收敛到 /flood/*。

11. 建议交付里程碑

M1：GF3 RF 水体 processor

输入单景 GF3 HH/HV 或单极化；
输出 water_mask.tif；
写入模型元数据；
接入 /flood/water-extractions。

M2：多极化输入契约

工程侧让 processor 能稳定拿到 HH/HV；
文档化极化路径和 metadata；
前端显示使用的极化。

M3：洪涝变化 processor

输入灾前/灾后；
输出标准 classified.tif；
与现有套合和产品链路兼容。

M4：深度学习推理

支持 tile 推理；
支持模型版本；
输出概率图和二值图；
与 RF/baseline 可切换。

14 KiB Raw Blame History Unescape Escape

洪涝灾害分析模块工程交接文档

1. 当前定位

2. 关键代码入口

3. 数据模型

3.1 SARSceneGeoORM

3.2 WaterExtractionORM

3.3 FloodDetectionORM

4. 现有业务流程

4.1 单景水体提取

4.2 灾前/灾后洪涝检测

4.3 套合分析

4.4 产品登记

5. analysis-ready 输入契约

6. 算法 processor 输出契约

6.1 水体提取 processor

6.2 洪涝检测 processor

7. 推荐算法路线

7.1 短期：GF3 快速分类器

7.2 中期：GF3 深度学习推理

7.3 保留 baseline

8. 工程侧下一步

8.1 后端 processor 注册

8.2 多极化场景组织

8.3 水体结果矢量化

8.4 质量评估字段

8.5 前端入口

9. 算法开发边界

10. 当前风险和已知问题

11. 建议交付里程碑

M1：GF3 RF 水体 processor

M2：多极化输入契约

M3：洪涝变化 processor

M4：深度学习推理

14 KiB

Raw Blame History