Fix D-InSAR pairing payload and center-distance controls

2026-05-10 21:42:24 +08:00
parent 3818f6e03e
commit 6893041a9f
11 changed files with 1089 additions and 44 deletions
@@ -0,0 +1,340 @@
+# Sentinel-1 数据管理改造规划
+
+日期：2026-05-10
+
+本文只规划“让系统能管理哨兵一号 Sentinel-1 数据”的改造范围，不记录已完成实现。当前建议把目标分成两层：先支持 Sentinel-1 源数据入库、检索、预览、配对和分发；真正进入 ISCE2 / PyINT / SARscape 的 Sentinel-1 自动生产链路，作为后续独立阶段处理。
+
+## 1. 目标边界
+
+本轮建议做：
+
+1. 扫描并登记 Sentinel-1 SLC `.SAFE` 解包目录。
+2. 解析 Sentinel-1 基础元数据，包括卫星、成像模式、极化、起止时间、绝对轨道、相对轨道、升降轨、footprint。
+3. 管理 Sentinel-1 精密轨道 `.EOF` 文件，并把影像按 acquisition time 匹配到覆盖该时间窗的轨道文件。
+4. 在源数据检索、配对规划、任务批次和数据分发中正确显示和使用 Sentinel-1。
+5. 对 Sentinel-1 配对增加必要的轻量约束，避免只靠 footprint 交叠产生不科学的候选对。
+
+本轮不建议做：
+
+1. 不把 Sentinel-1 自动送入现有 LT1 专用 ISCE2 / PyINT 流水线。
+2. 不做 burst 级精确公共覆盖计算。
+3. 不计算真实垂直基线，不把 footprint 中心距伪装成 SAR 空间基线。
+4. 不强制支持 `.SAFE.zip` 直接入库；优先支持已解包的 `.SAFE` 目录，zip 可作为后续增强。
+
+## 2. 当前代码现状
+
+已有基础：
+
+- [backend/app/utils.py](../backend/app/utils.py) 已经有 `parse_s1_radar_filename()` 和 `parse_s1_orbit_filename()` 的雏形。
+- [backend/app/services/data_service.py](../backend/app/services/data_service.py) 的 `scan_radar_data()` 是通用源数据扫描入口，理论上可以扫描 LT1 / S1 / GF3。
+- `radar_data` 已有 `satellite`、`satellite_family`、`imaging_date`、`imaging_mode`、`polarization`、`orbit_direction`、`product_type`、`source_product_token`、`has_orbit_data`、`orbit_file_path`、`geom`、`coverage_polygon` 等通用字段。
+- [backend/app/services/pairing_cache_service.py](../backend/app/services/pairing_cache_service.py) 已经把 `S1A/S1B` 归为 `S1` family，配对层具备同卫星族筛选能力。
+- [backend/app/copier.py](../backend/app/copier.py) 分发逻辑是复制原始产品目录，不再依赖 `envi_import`，这对 `.SAFE` 目录是有利的。
+
+主要缺口：
+
+- Sentinel-1 `.SAFE` 的关键元数据主要在 `manifest.safe` 和 `annotation/*.xml`，当前 `find_xml_file()` / `parse_xml_metadata()` 更偏 LT1 风格 XML，不能可靠解析 S1 footprint、升降轨、相对轨道。
+- 当前精轨模块 [backend/app/services/orbit_converter.py](../backend/app/services/orbit_converter.py) 基本写死 LT1 `LT1A_GpsData_GAS_C_YYYYMMDD.txt`，并会同步/转换到 ENVI、ISCE2 池；Sentinel-1 `.EOF` 不能走这套转换逻辑。
+- 当前配对缓存只要求同升降轨、同 look direction、footprint 相交、同卫星族、同模式/极化等。对 Sentinel-1 来说还缺少“同相对轨道/同轨道方向/同 beam mode/必要时同 slice 或同 burst 覆盖”的约束。
+- 前端卫星组 [frontend/src/config/appConstants.js](../frontend/src/config/appConstants.js) 目前只有 LT-1、GF-3；配对默认 `allowed_satellites` 是 `LT1A/LT1B`，导入 S1 后如果不改，会默认把 S1 排除。
+- 现有 ISCE2 / PyINT 生产脚本明显是 LT1 专用，不能因为管理了 S1 数据就默认允许一键生产。
+
+## 3. Sentinel-1 文件名能提供的信息
+
+标准 Sentinel-1 SLC SAFE 名称通常类似：
+
+```text
+S1A_IW_SLC__1SDV_20250101T104105_20250101T104132_XXXXXX_YYYYYY_ZZZZ.SAFE
+```
+
+可直接从文件名得到：
+
+- `satellite`: `S1A` / `S1B`
+- `satellite_family`: `S1`
+- `imaging_mode`: `IW` / `EW` / `SM`
+- `product_type`: `SLC`
+- `product_level`: 可从 `1SDV` 中解析出 level 1
+- `polarization`: `DV`、`DH`、`SV`、`SH`
+- `acquisition_start_time_utc`
+- `acquisition_stop_time_utc`
+- `imaging_date`
+- `absolute_orbit`，即文件名中的 6 位轨道号
+- datatake id / product unique id
+
+文件名通常不能可靠提供：
+
+- footprint
+- orbit direction，升轨/降轨
+- relative orbit / track
+- look direction
+- burst 范围
+- 精轨覆盖关系
+
+因此只靠文件名可以完成“粗入库”，但要做可靠配对，至少还要读取 `manifest.safe` 或 annotation XML。
+
+## 4. 建议新增的元数据模型
+
+为了控制工作量，不建议把 Sentinel-1 所有元数据拆成大量列。建议采用“少量关键列 + JSON 扩展”的方式。
+
+建议新增字段：
+
+- `acquisition_start_time_utc`
+- `acquisition_stop_time_utc`
+- `relative_orbit`
+- `absolute_orbit`
+- `slice_number`
+- `sensor_operational_mode`，可与现有 `imaging_mode` 保持一致或作为补充
+- `swath_list`，可用 JSON 或逗号文本保存 `IW1/IW2/IW3`
+- `source_format`，例如 `SAFE_DIR`、`SAFE_ZIP`、`LT1_DIR`
+- `metadata_json`，保存 Sentinel-1 专用扩展信息
+
+如果想更轻量，也可以第一阶段只增加：
+
+- `relative_orbit`
+- `acquisition_start_time_utc`
+- `acquisition_stop_time_utc`
+- `metadata_json`
+
+这四个字段已经足够支撑 Sentinel-1 基础管理和更科学的配对过滤。
+
+数据库处理要求：
+
+- 新增 ORM 字段和 Pydantic schema 字段。
+- 新增幂等迁移 `010_sentinel1_source_fields.sql`。
+- 把该迁移加入 [backend/app/db_maintenance.py](../backend/app/db_maintenance.py) 的 `MIGRATION_FILES`。
+- 健康检查里至少确认新增列存在；如果后续扩展精轨库存表，再把库存一致性纳入健康检查。
+
+## 5. 入库扫描设计
+
+建议把现有解析逻辑拆成“产品类型适配器”：
+
+```text
+SourceProductParser
+  - LT1 parser
+  - Sentinel1 SAFE parser
+  - GF3 parser
+```
+
+Sentinel-1 parser 负责：
+
+1. 识别 `.SAFE` 目录。
+2. 从目录名解析粗元数据。
+3. 读取 `manifest.safe`。
+4. 读取 annotation XML 获取或校正：
+   - pass / orbit direction
+   - relative orbit
+   - absolute orbit
+   - footprint 坐标
+   - start / stop time
+   - polarization / swath
+5. 生成 `coverage_polygon`、`geom`、`min/max lon/lat`。
+6. 判断 `insar_source_ready`：
+   - 必须是 `SLC`
+   - 必须有 footprint
+   - 必须有 imaging date / acquisition time
+   - 必须有 orbit direction
+   - Sentinel-1 推荐必须有 relative orbit
+
+兼容策略：
+
+- 已解包 `.SAFE` 目录优先。
+- `.SAFE.zip` 不在第一阶段直接解析，除非用户明确需要。后续可以在扫描器里只读 zip 内 `manifest.safe`，但这会明显增加实现和测试量。
+- 预览图优先复用 SAFE 内 `preview/quick-look.png` 或其他 quicklook 文件；当前 `find_radar_preview_source()` 已有关键词扫描，可少量适配。
+
+## 6. Sentinel-1 精轨管理设计
+
+Sentinel-1 精轨文件是 `.EOF`，匹配逻辑不是“卫星 + 日期等于影像日期”，而是：
+
+```text
+orbit.satellite == scene.satellite
+and orbit.validity_start <= scene.acquisition_time <= orbit.validity_stop
+```
+
+建议新增一个 Sentinel-1 orbit inventory 解析路径：
+
+- 解析 `S1A/S1B`
+- 解析轨道类型：`AUX_POEORB` / `AUX_RESORB`
+- 解析 validity start / stop
+- 记录原始 `.EOF` 路径
+
+第一阶段可以不建独立轨道表，仍然把匹配结果写回 `radar_data.has_orbit_data` 和 `radar_data.orbit_file_path`。但代码上要避免把 `.EOF` 送进 LT1 的 txt->xml 转换流程。
+
+更稳的设计是后续新增 `orbit_files` 表：
+
+- `satellite`
+- `satellite_family`
+- `orbit_type`
+- `validity_start_utc`
+- `validity_stop_utc`
+- `file_path`
+- `metadata_json`
+
+考虑到用户希望初级任务不要太复杂，第一阶段建议先不建表，只做扫描时内存索引和 `radar_data` 回填。
+
+## 7. 配对逻辑改造
+
+当前配对缓存可继续使用，但 Sentinel-1 应增加轻量硬约束。
+
+建议硬约束：
+
+- 同 `satellite_family = S1`
+- 默认允许 `S1A/S1B` 跨星，但必须同 Sentinel-1 family
+- 同 `orbit_direction`
+- 同 `relative_orbit`
+- 同 `imaging_mode`
+- 同 `polarization` 或至少主极化兼容
+- footprint 有交叠
+- `insar_source_ready = true`
+
+建议筛选指标：
+
+- `time_baseline_days`
+- `scene_overlap_ratio`
+- `scene_center_distance_meters`，只作为 footprint 中心距，不叫真实空间基线
+- `has_orbit_data`
+
+不建议第一阶段做：
+
+- 真实垂直基线计算
+- TOPS burst 级 overlap
+- 自动下载 ASF / Copernicus metadata
+- Sentinel-1 burst id 图层化管理
+
+配对缓存字段建议：
+
+- 给 `pairing_metric_cache` 增加 `same_relative_orbit` 或通用 `same_track`。
+- 或者在 SQL 硬约束里按 `radar_data.relative_orbit` 直接过滤。
+- 在 `selection_meta_json` 中记录 `relative_orbit`、`orbit_direction`、`source_family`，便于追溯。
+
+## 8. 数据分发设计
+
+分发层整体可以复用：
+
+- master 复制完整 `.SAFE` 目录到 `Task_*/master/`
+- slave 复制完整 `.SAFE` 目录到 `Task_*/slave/`
+- 如果启用精轨分发，则把 `.EOF` 复制到 `Task_*/orbit/`
+- `.dinsar_pair.json` 中增加 Sentinel-1 专用元数据，如 relative orbit、acquisition start/stop、orbit EOF 路径
+
+需要注意：
+
+- `.SAFE` 目录可能很大，zip 分发开关已经存在的话可以复用。
+- 不建议在分发阶段裁剪 SAFE 或抽取 measurement 文件，这会把“数据管理”变成“预处理”。
+- 如果源数据是 `.SAFE.zip`，第一阶段可以要求用户先解包；否则分发逻辑要支持复制 zip 并在生产侧再解包。
+
+## 9. 前端改造
+
+需要处理的点：
+
+- `SATELLITE_GROUPS` 增加 `S1` / `Sentinel-1`。
+- 源数据检索高级字段增加相对轨道、起止时间、源格式等字段。
+- 配对弹窗默认不要固定 `LT1A/LT1B`；建议默认“不限定卫星”，或者根据当前检索结果自动选择可见卫星。
+- 配对参数文案继续使用“footprint 中心距上限”，不要改回“空间基线”。
+- 对 Sentinel-1 配对显示 `relative_orbit` 和 `orbit_direction`，让用户一眼能看出是不是同轨道。
+- 生产提交页如果任务包是 Sentinel-1，但选择了 LT1 专用 PyINT/ISCE2 profile，应给出阻止或强提示。
+
+## 10. 生产链路边界
+
+现有生产引擎不应直接宣布支持 Sentinel-1：
+
+- ISCE2 当前 pipeline 和 profile 明显是 LT1 定制，包含 LT1 wavelength、LT1 输入 resolver、LT1 轨道转换。
+- PyINT / Gamma 当前输入搜索是 `LT1*.tar.gz` / `LT1*.tiff`，也属于 LT1 专用。
+- SARscape 理论上能处理 Sentinel-1，但当前系统侧是否能用 raw SAFE 驱动 SARscape D-InSAR，需要单独验证模板、参数和 task runner。
+
+所以建议第一阶段只做到：
+
+```text
+Sentinel-1 数据管理 -> 配对规划 -> 批次保存 -> 数据分发
+```
+
+生产执行留到第二阶段：
+
+```text
+Sentinel-1 Task_* -> 指定 Sentinel-1 engine/profile -> 预检 -> 生产
+```
+
+## 11. 实施阶段建议
+
+### 阶段 1：管理与检索
+
+工作内容：
+
+- 完成 Sentinel-1 SAFE parser。
+- 从 `manifest.safe` / annotation XML 提取 footprint、relative orbit、pass、start/stop time。
+- 支持 `.EOF` 精轨扫描和时间窗匹配。
+- 增加必要数据库字段和迁移。
+- 前端增加 Sentinel-1 过滤和显示。
+
+预估工作量：2-4 天。
+
+风险：主要在不同 SAFE 版本 XML 结构差异，需要准备 3-5 个真实样本覆盖 S1A/S1B、IW、单双极化。
+
+### 阶段 2：配对与分发
+
+工作内容：
+
+- 配对缓存加入 `relative_orbit` 约束。
+- 配对结果、批次 item、`.dinsar_pair.json` 保留 Sentinel-1 扩展元数据。
+- 分发 `.SAFE` + `.EOF`。
+- 前端配对弹窗默认卫星选择调整。
+
+预估工作量：1-2 天。
+
+风险：如果数据库新增字段后没有正确标 dirty，需要强制重建 pairing cache。
+
+### 阶段 3：生产预检保护
+
+工作内容：
+
+- 识别 task source family。
+- Sentinel-1 批次提交到 LT1 专用 engine/profile 时阻止。
+- 在生产面板显示“当前仅支持管理和分发，生产适配待完成”。
+
+预估工作量：0.5-1 天。
+
+风险：低。
+
+### 阶段 4：Sentinel-1 生产适配
+
+工作内容：
+
+- 选择 SARscape、ISCE2 TOPS、GMTSAR 或其他处理链。
+- 设计 Sentinel-1 专用 engine/profile。
+- 做 TOPS 配准、轨道、DEM、burst overlap、输出发布包和 catalog 适配。
+
+预估工作量：按引擎不同约 1-3 周，不建议和第一阶段混在一起。
+
+## 12. 推荐最小方案
+
+如果目标是“先把系统能管理哨兵数据”，推荐最小闭环如下：
+
+1. 只支持已解包 `.SAFE` 目录入库。
+2. 只解析 SLC 产品。
+3. 只新增 `relative_orbit`、`acquisition_start_time_utc`、`acquisition_stop_time_utc`、`metadata_json` 四类关键字段。
+4. `.EOF` 精轨只做匹配和路径保存，不做转换。
+5. 配对只增加同 relative orbit 约束，不做真实空间基线。
+6. 分发复制完整 SAFE 和 EOF。
+7. 生产页阻止 Sentinel-1 进入 LT1 专用 profile。
+
+这个方案对现有 LT1 链路侵入最小，能让 Sentinel-1 数据先进入“可检索、可配对、可分发、可追踪”的状态。
+
+## 13. 验收标准
+
+最小验收：
+
+- 扫描一个包含 S1A/S1B `.SAFE` 的目录后，`radar_data` 能看到 S1 数据。
+- 源数据检索可以按 Sentinel-1、IW、SLC、极化、升降轨、相对轨道过滤。
+- 每个 S1 scene 有 footprint，可在地图上显示。
+- 有匹配 `.EOF` 时 `has_orbit_data = true`，`orbit_file_path` 指向 EOF。
+- 配对结果不会跨 relative orbit。
+- 批次保存和数据分发能生成 `Task_*`，其中包含 master/slave SAFE 和可选 orbit EOF。
+- Sentinel-1 批次不会误提交到 LT1 专用生产 profile。
+
+## 14. 需要用户确认的输入
+
+开工前最好确认：
+
+1. Sentinel-1 数据池是 `.SAFE` 解包目录，还是 `.SAFE.zip` 为主。
+2. 精轨 `.EOF` 是否已经本地保存，还是希望后续系统自动下载。
+3. 第一阶段是否只做管理/配对/分发，不接生产。
+4. 是否接受新增少量数据库字段和一份幂等迁移。
+