Harmon/insar-management-system-v2
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Integrate GF3 SARscape flood workflow

Browse Source
This commit is contained in:
Harmon
2026-06-02 01:25:42 +08:00
parent 16cac0e292
commit 79e08b3a47
24 changed files with 4220 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/FLOOD_WATER_ALGORITHM_ENGINEERING_HANDOFF_20260602.md
+511
View File
@@ -0,0 +1,511 @@
# 洪涝灾害分析模块工程交接文档
日期：2026-06-02
面向对象：算法工程师、后端工程师
范围：新洪涝灾害分析模块 `/flood/*`，不包含旧兼容 `/water/*` 页面和接口。
## 1. 当前定位
系统现在把洪涝分析拆成两层：
1. 工程层：负责数据入库、场景标准化、任务队列、状态更新、预览上图、套合分析、产品登记。
2. 算法层：只负责从标准化 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:\GF3_L2_Image_Pool` 下的 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 单景水体提取
流程：
```text
前端选择 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 上图
```
当前输出目录：
```text
WATER_RESULTS_DIR/
water_extraction_{id}/
water_mask.tif
```
当前算法状态：
- Otsu 阈值；
- GF3 线性强度自动转 `10*log10`；
- 支持 COPDEM/SRTM 类 DEM 栅格约束；
- 中值滤波、高斯滤波、形态学、连通域过滤；
- 可作为 baseline，不适合作为最终高精度算法。
### 4.2 灾前/灾后洪涝检测
流程：
```text
前端输入灾害日期 + 行政区 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 图层
```
当前输出目录：
```text
WATER_RESULTS_DIR/
flood_{id}/
classified.tif
flood_mask.tif
stable_water_mask.tif
metadata.json
```
当前算法状态：
- 灾前、灾后分别 Otsu；
- 灾后水体且灾前非水体判为 flood；
- 灾前灾后均水体判为 stable_water；
- 可选 `refine` 做简单形态学清理；
- 支持灾前重投影到灾后网格；
- 还未接入更强的 GF3 双极化分类、深度学习或弱监督模型。
### 4.3 套合分析
流程：
```text
FloodDetection DONE
-> POST /flood/detections/{id}/overlay
-> classified.tif 中 value=2 的 flood 区域矢量化
-> 与灾害点、DInSAR 产品、行政区 AOI 套合
-> 写 flood_detection_{id}_overlay.geojson
-> 新增 FloodOverlayORM
```
输出：
```text
WATER_RESULTS_DIR/
flood_overlays/
flood_detection_{id}_overlay.geojson
```
### 4.4 产品登记
流程：
```text
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
建议新增统一接口：
```python
def run_xxx_water_extraction(
*,
input_path: str,
output_dir: str,
job_id: str | None = None,
options: dict | None = None,
) -> dict:
...
```
返回：
```python
{
"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
建议接口：
```python
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:
...
```
返回：
```python
{
"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 分发：
```python
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` 需要增加：
```python
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. 算法开发边界
算法工程师只需要保证：
1. 能读取输入 GeoTIFF；
2. 能输出符合契约的 GeoTIFF；
3. 返回标准 dict；
4. 大图处理不会把内存/显存打爆；
5. 错误抛出清晰异常或返回 `{"ok": False, "error": "..."}`。
算法工程师不需要处理：
- 前端；
- 任务队列；
- 用户权限；
- 数据库事务；
- 资产扫描；
- 上图预览；
- 套合分析；
- 产品登记。
## 10. 当前风险和已知问题
1. 当前 Otsu 水体提取误判较多，只能作为 baseline。
2. GF3 双极化没有形成正式算法输入契约。
3. `analysis_backscatter_unit` 对 GF3 SARscape 输出仍可能是 `unknown`。
4. 洪涝变化检测仍是双阈值差分，复杂地物下误判会明显。
5. 水体和洪涝结果缺少质量评价和置信度图层。
6. 产品登记还不是完整归档包。
7. 旧 `/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 可切换。
docs/GF3_SARSCAPE_NATIVE_TO_GEOTIFF_DESIGN_20260530.md
+476
View File
@@ -0,0 +1,476 @@
# GF3 SARscape Native To GeoTIFF Design
更新日期：2026-05-30
## 1. 结论
GF3 生产链路后续采用“生产解耦、系统标准化”的模型：
```text
GF3 原始压缩包池
-> 生产服务器使用 ENVI / IDL Runtime / SARscape 稳定生产
-> 只保留 SARscape 最终 _geo 原生结果组
-> 系统扫描原生结果池
-> 后台转换为标准 GeoTIFF
-> 入库、预览、洪涝分析和后续业务只消费 GeoTIFF
```
系统不直接把 SARscape `.sml` 或无后缀二进制作为业务算法输入。`.sml`、`.hdr` 和无后缀主数据属于原生证据层；`GeoTIFF` 属于平台消费层。
## 2. 目录约定
推荐继续沿用现场已有目录语义，并新增一个 ENVI/SARscape 原生池。
```env
GF3_ARCHIVE_SOURCE_DIRS=D:\GF3_Image_Pool_Zip
GF3_SARSCAPE_NATIVE_DIRS=D:\GF3_L2_ENVI_Binary_Pool
GF3_STORAGE_DIRS=D:\GF3_L2_Image_Pool
SAR_ANALYSIS_READY_ROOT=D:\production_results\sar_analysis_ready
```
目录职责：
| 目录 | 职责 | 系统是否直接分析 |
| --- | --- | --- |
| `GF3_ARCHIVE_SOURCE_DIRS` | 原始 GF3 L1A `.tar.gz` 池 | 否 |
| `GF3_SARSCAPE_NATIVE_DIRS` | SARscape `_geo` 原生结果池 | 否 |
| `GF3_STORAGE_DIRS` | GF3 标准 GeoTIFF 池 | 是 |
| `SAR_ANALYSIS_READY_ROOT` | 洪涝/水体分析级统一输入 | 是 |
生产服务器可以不部署完整管理系统。只要把完成后的 `_geo` 原生结果组放入 `GF3_SARSCAPE_NATIVE_DIRS`，管理系统就可以扫描、转换和入库。
## 3. 原生池结构
原生池以批次日期或人工批次号分组。单景目录名尽量保持 GF3 原始产品名。
```text
D:\GF3_L2_ENVI_Binary_Pool
20260514
GF3_MH1_FSII_051377_E132.3_N48.2_20260514_L1A_HHHV_L10007356478
GF3_MH1_FSII_..._hh_geo
GF3_MH1_FSII_..._hh_geo.hdr
GF3_MH1_FSII_..._hh_geo.sml
GF3_MH1_FSII_..._hh_geo.ovr
GF3_MH1_FSII_..._hh_geo.aux.xml
GF3_MH1_FSII_..._hh_geo_ql.tif
GF3_MH1_FSII_..._hh_geo.kml
GF3_MH1_FSII_..._hv_geo
GF3_MH1_FSII_..._hv_geo.hdr
GF3_MH1_FSII_..._hv_geo.sml
GF3_MH1_FSII_..._hv_geo.ovr
GF3_MH1_FSII_..._hv_geo.aux.xml
GF3_MH1_FSII_..._hv_geo_ql.tif
GF3_MH1_FSII_..._hv_geo.kml
gf3_sarscape_cli.log
```
### 3.1 必保文件
每个极化至少保留：
```text
*_geo
*_geo.hdr
*_geo.sml
```
建议同时保留：
```text
*_geo.ovr
*_geo.aux.xml
*_geo_ql.tif
*_geo.kml
gf3_sarscape_cli.log
```
说明：
- 无后缀 `*_geo` 是 SARscape 主数据。
- `.hdr` 是 ENVI/GDAL 读取二进制数据的关键 sidecar。
- `.sml` 是 SARscape 追溯和完成判定的关键 sidecar。
- `*_geo_ql.tif` 只能作为快视或预览参考，不作为科学分析主输入。
### 3.2 可清理文件
生产结束并确认 `_geo` 结果完整后，可以清理：
```text
.gf3_extract
temp
SLC 中间产物
*_ml*
*_filt*
```
如果需要完整复现 SARscape 处理过程，应额外保留 `work` 中的参数 XML、trace 和日志；否则可将 `work` 作为可选审计资料归档。
## 4. 标准 GeoTIFF 池结构
系统从原生池转换后写入 `GF3_STORAGE_DIRS`。
```text
D:\GF3_L2_Image_Pool
20260514
GF3_MH1_FSII_051377_E132.3_N48.2_20260514_L1A_HHHV_L10007356478
HH_L2.tif
HV_L2.tif
preview_HH.png
preview_HV.png
gf3_standard_manifest.json
quality_HH.json
quality_HV.json
```
平台后续只从该目录或 `SAR_ANALYSIS_READY_ROOT` 消费 GeoTIFF，不直接读取 SARscape 原生目录。
## 5. 扫描与转换流程
推荐把“扫描”和“转换”都放在后台任务中执行，避免普通扫描接口长时间阻塞。
```text
用户触发 GF3 扫描
-> 扫描 GF3_SARSCAPE_NATIVE_DIRS
-> 识别 scene / polarization / _geo 完整性
-> 对待转换项创建或执行 GF3_NATIVE_TO_TIF 任务
-> 转换到 GF3_STORAGE_DIRS
-> 写 gf3_standard_manifest.json
-> 登记 radar_data / sar_scene_geo
-> 生成预览图和 quality.json
```
### 5.1 完整性判定
一个极化的原生 `_geo` 结果完整条件：
```text
*_geo 存在且非空
*_geo.hdr 存在且非空
*_geo.sml 存在且非空
```
如果存在 `.aux.xml`、`.ovr`、`*_geo_ql.tif`、`.kml`，登记为辅助资产。
一个 scene 的状态：
| 状态 | 条件 |
| --- | --- |
| `DONE` | 请求极化全部具备完整 `_geo` 结果，且 GeoTIFF 转换成功 |
| `NATIVE_READY` | 原生 `_geo` 完整，但 GeoTIFF 尚未转换 |
| `PARTIAL` | 只完成部分极化 |
| `FAILED` | 原生结果不完整或转换失败 |
### 5.2 增量跳过规则
转换任务应根据 manifest 判断是否需要重跑：
```text
source path
source size
source mtime
converter version
target tif exists
```
当上述信息未变化时，跳过转换。
如果 `_geo` 原生文件被替换、修改时间变化、转换器版本变化或目标 tif 缺失，应重新转换。
## 6. 转换策略
优先使用 GDAL/rasterio 读取 ENVI header 或 SARscape sidecar。
输入优先级：
```text
1. *_geo + *_geo.hdr
2. 可被 GDAL 识别的 *_geo.sml
3. 其他明确可读的 SARscape/ENVI sidecar
```
输出要求：
```text
GeoTIFF
单极化单文件
尽量保留地理参考、nodata、数据类型和投影
默认输出 HH_L2.tif / HV_L2.tif
```
如果转换失败，不应把 quicklook tif 冒充为分析级 tif。应记录：
```text
analysis_ready_status=FAILED
error_message=<转换错误>
source_native_status=NATIVE_READY
```
## 7. 数据库登记
### 7.1 `radar_data`
每个 GF3 scene 至少登记一条 `radar_data`：
```text
satellite=GF3
satellite_family=GF3
source_format=GF3_SARSCAPE_NATIVE
product_level=L2
file_path=<GF3_STORAGE_DIRS 下的 scene 标准目录>
metadata_json.native_dir=<GF3_SARSCAPE_NATIVE_DIRS 下的 scene 原生目录>
metadata_json.standard_manifest=<gf3_standard_manifest.json>
```
应从 scene 名解析：
```text
imaging_date
imaging_mode
polarization
scene_center_lon
scene_center_lat
product_unique_id
```
如果 GeoTIFF 可读，应同步：
```text
min_lon / min_lat / max_lon / max_lat
coverage_polygon
geom
```
### 7.2 `sar_scene_geo`
每个可分析 scene 记录：
```text
analysis_engine=gf3_sarscape
analysis_profile=gf3_sarscape_geo_to_tif
analysis_tif_path=<HH_L2.tif 或默认极化 tif>
analysis_dir=<SAR_ANALYSIS_READY_ROOT 下目录>
analysis_preview_path=<preview.png>
analysis_backscatter_unit=sigma0_linear 或 unknown
analysis_metadata_json.native_dir=<原生目录>
analysis_metadata_json.native_assets=<原生资产列表>
analysis_quality_json=<quality.json 内容>
status=DONE
```
如果需要同时保留 HH 和 HV 两个可分析产品，建议长期扩展为资产表或 scene-pol 级记录；短期可以选择默认极化写入 `sar_scene_geo.analysis_tif_path`，并在 metadata 中登记全部极化 tif。
## 8. Manifest 契约
### 8.1 原生 manifest
`gf3_native_manifest.json` 写入原生 scene 目录或系统索引目录：
```json
{
"schema": "gf3_sarscape_native.v1",
"scene_name": "GF3_MH1_FSII_...",
"native_dir": "D:\\GF3_L2_ENVI_Binary_Pool\\20260514\\GF3_MH1_FSII_...",
"source_archive": "D:\\GF3_Image_Pool_Zip\\20260514\\GF3_MH1_FSII_....tar.gz",
"polarizations": ["HH", "HV"],
"status": "NATIVE_READY",
"assets": [
{
"polarization": "HH",
"role": "geo_native",
"path": "..._hh_geo",
"hdr": "..._hh_geo.hdr",
"sml": "..._hh_geo.sml",
"quicklook": "..._hh_geo_ql.tif"
}
],
"logs": ["gf3_sarscape_cli.log"]
}
```
### 8.2 标准 manifest
`gf3_standard_manifest.json` 写入标准 GeoTIFF scene 目录：
```json
{
"schema": "gf3_standard_geotiff.v1",
"scene_name": "GF3_MH1_FSII_...",
"native_manifest": "D:\\GF3_L2_ENVI_Binary_Pool\\...\\gf3_native_manifest.json",
"standard_dir": "D:\\GF3_L2_Image_Pool\\20260514\\GF3_MH1_FSII_...",
"status": "DONE",
"converter": {
"name": "gf3_sarscape_geo_to_tif",
"version": "v1"
},
"assets": [
{
"polarization": "HH",
"role": "analysis_tif",
"path": "HH_L2.tif",
"source_native": "..._hh_geo",
"quality": "quality_HH.json",
"preview": "preview_HH.png"
}
]
}
```
## 9. 前端与操作入口
短期不新增复杂页面，沿用“数据管理 / 归档预处理”里的 GF3 操作区：
```text
GF3 解包
GF3 SARscape 原生扫描
GF3 原生转 GeoTIFF
扫描 GF3 标准结果
```
也可以先合并为一个按钮：
```text
扫描 GF3
```
后台自动完成：
```text
native scan -> convert missing tif -> register standard result
```
任务日志必须显示：
```text
发现 scene 数
NATIVE_READY 数
转换成功数
转换失败数
跳过数
失败原因
```
## 10. 实施顺序
### Phase 1：设计与配置
- 新增本文档。
- 新增 `.env.example` 中的 `GF3_SARSCAPE_NATIVE_DIRS`。
- 保留 `GF3_STORAGE_DIRS` 作为标准 GeoTIFF 池。
### Phase 2：原生扫描
- 新增 `gf3_native_inventory_service.py`。
- 扫描 `_geo` 原生结果组。
- 生成 native manifest。
- 不做转换、不入业务分析。
### Phase 3：GeoTIFF 标准化
- 新增 `gf3_standardize_service.py`。
- 将 `_geo` 原生结果转换为 `HH_L2.tif` / `HV_L2.tif`。
- 生成 preview 和 quality。
- 写 standard manifest。
### Phase 4：入库与洪涝接入
- 登记 `radar_data`。
- 登记或更新 `sar_scene_geo`。
- `/flood/preprocess` 对 GF3 优先复用已标准化 GeoTIFF。
### Phase 5：清理策略
- 增加 native pool 检查报告。
- 增加可选中间文件清理建议，但系统不主动删除生产机文件。
- 后续如需自动清理，应只清理系统明确生成的临时文件。
## 11. 当前约束
- 不把 `*_geo_ql.tif` 当作分析级产品。
- 不让洪涝、水体、地图预览直接依赖 `.sml`。
- 不要求生产服务器部署管理系统。
- 不在扫描请求同步执行长时间转换，应使用后台任务。
- 不删除用户生产目录中的文件，除非后续新增明确的、受控的清理任务。
## 12. 与旧 GF3 GDAL 路线关系
现有 `gf3_service.py` 的 Python/GDAL L1A -> L2 路线可以保留为 fallback 或实验处理器：
```text
gf3_gdal
```
新 SARscape 原生池路线作为正式现场路线：
```text
gf3_sarscape
```
两条路线最终都必须收敛到：
```text
GF3_STORAGE_DIRS / SAR_ANALYSIS_READY_ROOT 中的标准 GeoTIFF
```
因此后续业务模块只关心标准 GeoTIFF，不关心上游来自 SARscape、GDAL、GAMMA 或其他处理器。
## 13. 2026-05-30 首轮落地
首轮代码已按本文档的主路径实现最小闭环：
- 新增 `GF3_SARSCAPE_NATIVE_DIRS` 配置，作为 SARscape/ENVI 原生 `_geo` 二进制池。
- 新增 `gf3_native_inventory_service.py`，扫描 `*_geo + *_geo.hdr + *_geo.sml` 并写 `gf3_native_manifest.json`。
- 新增 `gf3_standardize_service.py`，将完整原生结果转换到 `GF3_STORAGE_DIRS` 下的 `HH_L2.tif` / `HV_L2.tif`，并写 `gf3_standard_manifest.json`、`quality_*.json`、`preview_*.png`。
- 新增后台任务 `GF3_SARSCAPE_SYNC` 和接口 `POST /api/monitor/gf3-sarscape-sync`。
- 数据监控面板新增 `GF3 SARscape 入库` 按钮。
- 转换成功后登记 `radar_data`，并通过 `sar_analysis_ready_service` 登记 `sar_scene_geo`，使洪涝/水体模块可以继续消费标准 GeoTIFF。
当前实现仍遵守约束：
- 不把 `*_geo_ql.tif` 当作分析级输入。
- 不要求生产服务器部署管理系统。
- 转换优先使用 GDAL Python 绑定；当前环境没有 `osgeo` 时走 rasterio 兜底。
## 14. 2026-05-30 生产链路接入
在首轮“原生结果入库”基础上，系统进一步接入 GF3 SARscape wrapper：
```text
GF3_ARCHIVE_SOURCE_DIRS
-> gf3wrapper.exe / IDL Runtime / SARscape
-> GF3_SARSCAPE_NATIVE_DIRS
-> GF3_SARSCAPE_SYNC 标准化
-> GF3_STORAGE_DIRS
-> 雷达数据扫描、预览、洪涝/水体业务
```
新增配置：
```env
GF3_SARSCAPE_WRAPPER_EXE=D:\Code\Insar_management_system_v2\.codex_tmp\GF3_L1A_To_L2_pipeline\dist\windows\gf3wrapper.exe
GF3_SARSCAPE_IDLRT_PATH=C:\Program Files\Harris\ENVI56\IDL88\bin\bin.x86_64\idlrt.exe
GF3_SARSCAPE_DEM_PATH=D:\DEM\GMTED2010.jp2
GF3_SARSCAPE_POLARIZATIONS=HH,HV
GF3_SARSCAPE_KEEP_EXTRACTED=true
GF3_SARSCAPE_AUTO_STANDARDIZE=true
GF3_SARSCAPE_CLEAN_AFTER_SUCCESS=true
GF3_SARSCAPE_PRODUCE_TIMEOUT_SECONDS=0
```
新增后台任务：
| 任务 | 接口 | 用途 |
| --- | --- | --- |
| `GF3_SARSCAPE_PRODUCE` | `POST /api/monitor/gf3-sarscape-produce` | 从原始 `.tar.gz/.tgz` 触发 SARscape 生产，随后自动标准化、入库、清理 |
| `GF3_SARSCAPE_SYNC` | `POST /api/monitor/gf3-sarscape-sync` | 仅扫描已有 `_geo` 原生结果并转 GeoTIFF 入库 |
| `GF3_SARSCAPE_CLEAN` | `POST /api/monitor/gf3-sarscape-clean` | 手动清理原生池中间数据 |
清理策略：
- 只处理 `GF3_SARSCAPE_NATIVE_DIRS` 内的场景目录。
- 默认要求 `GF3_STORAGE_DIRS/<batch>/<scene>/gf3_standard_manifest.json` 状态为 `DONE` 后才清理。
- 保留最终原生 `_geo` 主数据、`.hdr/.sml/.ovr/.aux.xml`、`*_geo_ql.tif/.kml`、日志和 manifest。
- 删除 `.gf3_extract`、`temp`、`work`，以及根目录中的 `*_slc*`、`*_ml*`、`*_filt*`、`.par/.trace/.working/.list` 等中间文件。
- 每景写 `gf3_cleanup_manifest.json`，记录删除条目和释放字节数。
- 不删除 `GF3_ARCHIVE_SOURCE_DIRS` 中的原始压缩包，也不删除 `GF3_STORAGE_DIRS` 中的标准 GeoTIFF。
这样 `D:\GF3_L2_ENVI_Binary_Pool` 只长期保存可追溯的最终 `_geo` 原生结果组，中间过程文件在标准化完成后自动释放空间。
docs/INDEX.md
+7 -1
View File
@@ -1,6 +1,6 @@
# 文档索引
最后更新：2026-05-28
最后更新：2026-05-30
本页是当前有效文档入口。没有列在本页的历史设计、实验记录和过程文档不再作为当前系统事实依据。
@@ -51,9 +51,15 @@
- [FLOOD_GEOTIFF_GAMMA_PREPROCESS_DESIGN_20260515.md](FLOOD_GEOTIFF_GAMMA_PREPROCESS_DESIGN_20260515.md)
洪涝模块 GeoTIFF 化与 Gamma 前处理方向。
- [GF3_SARSCAPE_NATIVE_TO_GEOTIFF_DESIGN_20260530.md](GF3_SARSCAPE_NATIVE_TO_GEOTIFF_DESIGN_20260530.md)
GF3 SARscape 原生 `_geo` 二进制池、GeoTIFF 标准化、入库和洪涝接入设计。
- [FLOOD_DISASTER_ANALYSIS_SYSTEM_DESIGN_20260514.md](FLOOD_DISASTER_ANALYSIS_SYSTEM_DESIGN_20260514.md)
洪涝灾害分析工作台、产品包和矢量套合边界。
- [FLOOD_WATER_ALGORITHM_ENGINEERING_HANDOFF_20260602.md](FLOOD_WATER_ALGORITHM_ENGINEERING_HANDOFF_20260602.md)
洪涝/水体算法接入现状、processor 输出契约和工程交接路线。
## 安全
- [SECURITY_AUDIT_2026-03-12.md](SECURITY_AUDIT_2026-03-12.md)