insar-management-system-v2/docs/archive/TODO_water.md

水体提取与洪涝监测 — 开发 TODO

架构概览

Phase 1: 水体提取  → WaterMaskORM（每景影像的水体掩膜）
Phase 2: 水体配对  → WaterPairORM（参考期 + 监测期）
Phase 3: 变化检测  → FloodEventORM（洪涝事件 + 告警）

依赖库（InSAR conda 环境已有）：rasterio, shapely, numpy, scipy, Pillow

---

任务列表

Step 1：ORM 建表

• W01 orm.py 新增 WaterMaskORM、WaterPairORM、FloodEventORM
• W02 models/__init__.py 导出新 ORM
• W03 Alembic migration 0002_water_tables.py

Step 2：核心服务

• W04 water_service.py Phase 1 — 单景水体提取（OTSU + 形态学 + 矢量化）
• W05 water_service.py Phase 2 — 水体配对逻辑（空间重叠 + 时间筛选）
• W06 water_service.py Phase 3 — 变化检测（掩膜差值 + 面积统计 + 告警）

Step 3：Job 集成

• W07 job_handlers.py 新增 WATER_EXTRACT / WATER_DETECT job 类型

Step 4：路由

• W08 routers/water.py 全部端点
• W09 routers/__init__.py 注册 water router

Step 5：前端

• W10 api/water.js API 层
• W11 WaterMonitorPanel.jsx 三 Tab 面板（提取/配对/事件）
• W12 App.jsx 注册新面板入口

---

端点设计

POST /water/extract              # 批量提取（传 radar_data_ids 列表）
GET  /water/masks                # 查询水体掩膜列表（分页）
GET  /water/masks/{id}/preview   # 水体掩膜预览图

POST /water/pairs                # 创建配对（reference_id + monitor_id）
GET  /water/pairs                # 查询配对列表
POST /water/pairs/{id}/detect    # 对指定配对执行变化检测

GET  /water/events               # 查询洪涝事件列表
GET  /water/events/{id}/preview  # 变化图预览

---

关键算法备忘

OTSU（纯 numpy 实现，不依赖 scikit-image）

def _otsu_threshold(arr_db):
    hist, bin_edges = np.histogram(arr_db[np.isfinite(arr_db)], bins=256)
    bin_centers = (bin_edges[:-1] + bin_edges[1:]) / 2
    total = hist.sum()
    w0 = np.cumsum(hist) / total
    w1 = 1 - w0
    mu0 = np.cumsum(hist * bin_centers) / (np.cumsum(hist) + 1e-10)
    mu1 = (np.sum(hist * bin_centers) - np.cumsum(hist * bin_centers)) / (np.cumsum(hist[::-1])[::-1] + 1e-10)
    sigma_b = w0 * w1 * (mu0 - mu1) ** 2
    return bin_centers[np.argmax(sigma_b)]

水体掩膜预览图

• 原始影像灰度拉伸为背景（半透明）
• 水体区域叠加蓝色（RGBA: 0, 100, 255, 180）
• 新增水体叠加红色（洪涝变化图）

---

状态

全部完成 ✓ — 等待测试

测试步骤

1. 重启后端（新表由 create_all 自动创建）
2. 前端强制刷新，进入"结果分析"→"水体监测"
3. Phase 1：输入已入库的雷达数据 ID，提交提取任务，等待完成后刷新列表
4. Phase 2：选参考期和监测期掩膜 ID，创建配对
5. Phase 3：对配对点击"执行变化检测"，在"洪涝事件"Tab 查看结果

已知限制

• _find_geocoded_path 依赖 preview_cache_path 或 file_path，若雷达数据没有地理编码文件则提取失败
• 告警阈值默认 30%，可通过 .env 中 FLOOD_ALERT_THRESHOLD=0.3 调整