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

源影像叠加稳定化方案（Scheme B）

目标：解决“覆盖面是斜四边形，源影像是矩形包围框”的错位问题，优先保障长期稳定与前端流畅。

---

1. 问题本质

当前地图展示中：

• 覆盖范围来自 coverage_polygon（真实斜四边形）
• 源图叠加常用 imageOverlay(url, bounds)（矩形边界）

当源图本身有旋转/倾斜时，直接矩形贴图会产生明显错位。

---

2. 方案选择

A（前端实时变换）

• 在浏览器端做逐帧几何变换
• 优点：改动快
• 缺点：前端负载高，图层增多后容易卡顿

B（后端预纠正缓存）✅

• 扫描/构建阶段在后端完成几何纠正，前端只显示结果图
• 优点：渲染轻、稳定性高、易观测
• 缺点：后端实现复杂度更高

本项目已确定采用 B 方案。

---

3. 当前实现（2026-02-10）

3.1 缓存分层

• backend/image_cache/radar_geo/：地理纠正后的主缓存
• backend/image_cache/radar_raw/：原图回退缓存

3.2 后端能力

• 默认由手动扫描任务触发增量构建（前端“立即扫描”或 POST /api/monitor/run-now）
• 扫描时增量构建纠正缓存（radar_geo）
• 同步维护原图缓存（radar_raw）作为兜底
• 方向判定优先使用 XML 的 sceneCornerCoord/refRow/refColumn，避免仅靠角点名称导致镜像/翻转误判
• GET /api/radar-data/{id}/thumb：
  • 优先返回 radar_geo
  • 失败自动回退 radar_raw
• 新增状态接口：
  • GET /api/radar-data/{id}/preview-status
  • POST /api/radar-data/{id}/rebuild-preview-cache（管理员）

3.3 前端能力

• 每条源影像显示预览状态（纠正/回退/失败/未建）
• 管理员支持“重建”按钮
• 预览请求增加缓存键，避免浏览器长期缓存旧图

---

4. 关键配置项

RADAR_GEO_CACHE_WORKERS=2
RADAR_GEO_CACHE_VERSION=b1
RADAR_GEO_CACHE_QUALITY=84
RADAR_PREVIEW_BUILD_ON_DEMAND=true

建议：

• 小规模先用 RADAR_GEO_CACHE_WORKERS=1~2
• 算法升级时提高 RADAR_GEO_CACHE_VERSION 触发重建

---

5. 验收标准

• 同一场景下，源图与覆盖面边界明显趋于一致
• 缩放/平移时交互平滑，无明显掉帧
• 构建失败可在状态接口与日志中定位原因
• 失败场景可回退原图缓存，不阻塞业务操作

---

6. 后续建议

1. 采集 3 类典型数据（升轨/降轨/大倾斜）做对齐验收
2. 统计 radar_geo 构建失败原因并分级治理
3. 发布前执行一次全量重建，提升线上命中率