Harmon/insar-management-system-v2

Fork 0

Files

T

Harmon cb518b431f Apply current workspace changes

2026-04-22 01:52:21 +08:00

18 KiB

Raw Blame History

PyINT 输入资产适配设计

日期: 2026-04-19
状态: 总体设计
范围: Task_* 路径适配、PyINT DEM 管理、LT-1 精密轨道治理、Gamma 配对前置条件、运维自检与前端入口

1. 结论

本次设计的核心结论如下：

用户侧继续沿用现有的 Task_* 输入模式，不要求手工准备原生 PyINT 项目目录，也不允许直接把任意外部路径当作长期运行依赖。
需要在现有 pyint_engine -> run_lt1_pyint_pipeline.py 之间补一层“输入资产适配层”，把 Task_*、DEM、精密轨道统一解析为系统托管的运行输入。
DEM 可以在一期做到“系统托管且真实参与计算”，推荐优先走“本地 FABDEM/DEM 瓦片源 + PyINT 本地生成 DEM 产物”的方案，而不是直接复用 ISCE2 的 .wgs84 成品 DEM。
LT-1 精密轨道在当前 PyINT 原生 LT-1 导入链路里，还没有现成的“接入系统轨道池并直接参与计算”的钩子。一期先做“治理级校验 + 按任务解析 + 随跑记录 + 可选准入阻断”，二期再补“真正参与 PyINT/Gamma 计算”的桥接。
一期不必改数据库结构，先把输入资产记录写入 .dinsar_run.json、pyint_run_summary.json 和结果 manifest 的扩展摘要。二期只有在需要按 DEM/轨道版本检索历史时才改库，并且必须走现有数据库自维护迁移机制。
前端主入口应放在现有 D-InSAR 生产面板的 PyINT 引擎区域；运维自检面板只保留状态摘要，不再堆叠新的操作区。

2. 现状与缺口

2.1 已经具备的部分

PyINT 代码已经收编到仓库内 third_party/PyINT，不再依赖仓库外绝对路径。
当前后端已经支持：
- root_dir 为单个任务目录，或为包含多个 Task_* 子目录的父目录
- 对每个任务递归发现 master/、slave/ 下的 LT1*.tar.gz
- 自动生成 ifgram_list.txt
- 自动生成 PyINT template
- 在 backend/runtime/pyint_work 下构造 PyINT 工作区并调用 pyintApp.py
当前系统已有成型的精轨治理链路：
- MONITOR_ORBIT_DIR 作为源目录
- ORBIT_POOL_ENVI 作为 LT-1 .txt 精轨池
- ORBIT_POOL_ISCE2 作为 ISCE2 .xml 精轨池
- orbit_converter.py 已支持同步、修复、隔离和一致性检查
当前系统已有成型的健康检查和目录治理链路：
- health_service.py
- root_registry_service.py
- 结果目录扫描和 manifest catalog

2.2 目前还没有解决的部分

当前 PyINT 集成只解决了“Task_* 到 PyINT 工作区”的映射，没有解决“系统托管 DEM / 系统托管精轨资产如何进入 PyINT”。
当前 PYINT_DEM_ROOT 只是 PyINT 的运行目录或缓存目录，不等价于“系统已经为本次任务解析好了 DEM 输入策略”。
当前 LT-1 PyINT 导入脚本并没有直接消费系统里的 LT1*_GpsData_GAS_C_YYYYMMDD.txt 精轨池。
当前前端也没有给 PyINT 提供“提交前资产预检/预览”的位置。

2.3 一个必须明确的现实约束

当前 vendored PyINT 的 LT-1 流程里：

DEM 侧已有明确入口，makedem_pyint.py 可以走本地 fabdem_dir 或 OpenTopography。
精轨侧对 LT-1 没有现成的“使用系统 .txt 精轨池”的显式接口，现有 LT-1 导入脚本更接近“从压缩包和 XML 元数据生成 SLC 参数”。

因此本方案必须分两层描述精轨：

治理层接入：系统知道本次任务应该使用哪份精轨，能阻断缺失任务，能把依赖记录下来。
计算层接入：该精轨是否真的被 PyINT/Gamma 的 LT-1 导入过程消费。

一期只能承诺第一层，第二层需要专门桥接。

3. 总体方案

3.1 新增一层输入资产适配服务

建议在 pyint_service.py 旁边新增或内聚出一层输入资产适配职责，例如：

resolve_pyint_tasks(root_dir)
resolve_pyint_dem_asset(task_context)
resolve_pyint_orbit_assets(task_context)
materialize_pyint_input_assets(run_context)
build_pyint_input_preview(root_dir)

其职责不是替代 PyINT，而是在系统生产语义和 PyINT 原生语义之间做转换。

3.2 总体执行链路

建议链路如下：

前端生产面板 root_dir -> validate_pyint_root_dir() -> PyINT 输入资产适配层 -> 每个 Task_* 解析任务身份、DEM、精轨 -> 运行目录 materialize -> run_lt1_pyint_pipeline.py -> PyINT / Gamma -> pyint_run_summary.json + .dinsar_run.json -> 结果发布 / catalog

3.3 不再要求用户准备 PyINT 原生目录

用户仍然只需要提供：

单个 Task_YYYYMMDD_YYYYMMDD
或者一个包含多个 Task_* 的批次根目录

系统内部自行生成：

project_name
template
DOWNLOAD/
ifgram_list.txt
input_assets/
native output

这保证 PyINT 继续是“受控执行器”，不是“要求用户手工维护目录结构的第二套系统”。

4. 与现有 `Task_*` 路径的配合方式

4.1 用户输入模式

沿用当前模式，不新增新的路径输入方式：

模式 A：直接选一个 Task_*
模式 B：选一个包含多个 Task_* 的父目录

任务目录仍要求至少满足：

master/
slave/
目录下可递归发现 LT1*.tar.gz

可选但推荐继续保留：

.dinsar_pair.json

4.2 任务解析规则

建议继续沿用当前逻辑，并把它明确固化为正式约束：

Task_* 是业务输入根，不是 PyINT 工作区。
master/、slave/ 下面允许多层子目录，但最终必须能发现原始压缩包。
任务身份优先从 .dinsar_pair.json 读取。
缺失时再从任务目录名和压缩包文件名推导：
- task_alias
- pair_key
- master_date
- slave_date

4.3 运行期目录建议

建议把每次运行的托管结构固定为：

backend/runtime/pyint_work/<pair_key>/<run_key>/
  input_assets/
    task_manifest.json
    orbits/
    dem/
  <project_name>/
    DOWNLOAD/
    ifgram_list.txt
    ...

backend/runtime/pyint_templates/<pair_key>/<run_key>/
  <project_name>.template

backend/runtime/pyint_output/<pair_key>/<run_key>/native/
  pyint_run_summary.json
  .dinsar_run.json
  ifgrams/
  ...

原则：

原始 Task_* 只读，不回写。
每次运行独立目录，避免不同 run 相互污染。
DEM、轨道、任务解析结果要在 input_assets/ 下留痕。

5. DEM 方案

5.1 不建议直接把 ISCE2 DEM 方案硬套给 PyINT

当前系统已有 ISCE2_DEM_PATH，它对应的是 ISCE2 直接消费的成品 DEM。

但当前 PyINT 的 DEM 处理逻辑更接近：

先根据 master SLC 范围解析 DEM 覆盖区域
再通过 makedem_pyint.py
结合 fabdem_dir 或 OpenTopography
在 DEMDIR 下生成 PyINT / Gamma 所需的 DEM 产物

因此一期不建议把 PYINT_DEM_SOURCE 简单绑定为 ISCE2_DEM_PATH。

5.2 推荐的 DEM 分层

建议把 PyINT 的 DEM 分成三层：

DEM 源
- 本地 FABDEM/DEM 瓦片根目录
- 或 OpenTopography 在线源
DEM 运行缓存
- 即当前 PYINT_DEM_ROOT
本次任务解析后的 DEM 产物
- 位于 PYINT_DEM_ROOT/<project_name>/...
- 被 generate_rdc_dem.py、geocode_gamma.py 等步骤消费

5.3 推荐配置

建议新增或明确以下配置：

PYINT_DEM_MODE=local_fabdem|opentopo
PYINT_FABDEM_ROOT=
PYINT_OPENTOPO_DEM_TYPE=SRTMGL1
PYINT_DEM_ROOT=
PYINT_DEM_STRICT=true

说明：

PYINT_DEM_MODE=local_fabdem 为推荐默认值。
PYINT_FABDEM_ROOT 指向本机统一维护的 FABDEM/DEM 瓦片目录。
PYINT_DEM_ROOT 继续作为 PyINT DEM 运行缓存根。
若后续确实验证可直接复用某个成品 DEM，再新增单独模式，不要和一期混在一起。

5.4 运行时行为

当用户提交 PyINT 任务时：

适配层先解析 DEM 模式。
若为 local_fabdem：
- 把 fabdem_dir 写入本次运行生成的 template
- DEMDIR 指向本次受控缓存根
若为 opentopo：
- 只在运行时注入 API key，不把敏感值写入仓库文档或 .env.example
运行完成后记录：
- DEM 模式
- DEM 源根目录
- 生成产物目录
- 关键 DEM 文件是否生成成功

5.5 DEM 与前端的关系

不建议在前端让用户手工输入单次 DEM 路径。

推荐做法是：

前端只展示“当前 DEM 策略”
例如：
- 本地 FABDEM
- OpenTopography
- 未配置
如果 DEM 不可用，则在 PyINT 引擎区阻断提交

6. 精密轨道方案

6.1 一期目标不是“假装已经真正进计算”

当前 LT-1 PyINT 原生脚本没有明确消费系统精轨池的接口，因此一期要把目标定义准确：

系统必须能按任务解析 master/slave 对应的精轨文件
系统必须能知道精轨是否缺失
系统必须把这次运行实际匹配到的精轨记录下来
系统必须能根据策略决定“警告放行”还是“阻断提交”

但不能在未完成桥接前，对外宣称“精轨已经真实参与 LT-1 PyINT 计算”。

6.2 一期建议的精轨策略

建议精轨配置分为：

PYINT_ORBIT_POLICY=validate_only|require_txt|stage_txt
PYINT_ORBIT_POOL_TXT=
PYINT_RECORD_INPUT_ASSETS=true

默认建议：

PYINT_ORBIT_POOL_TXT 为空时默认继承 ORBIT_POOL_ENVI
PYINT_ORBIT_POLICY=require_txt

三种策略含义：

validate_only
- 找得到则记录
- 找不到只警告
require_txt
- 找不到直接阻断运行
stage_txt
- 除了要求存在，还把匹配到的轨道文件复制或硬链接到本次运行目录

6.3 轨道解析规则

对每个 task，按如下顺序解析：

从 .dinsar_pair.json、原始压缩包文件名或元数据确定：
- 卫星 LT1A/LT1B
- master_date
- slave_date
到系统轨道池中查找：
- LT1A_GpsData_GAS_C_YYYYMMDD.txt
- LT1B_GpsData_GAS_C_YYYYMMDD.txt
分别解析 master/slave 结果
形成本次运行的轨道摘要

6.4 与现有轨道治理链路的关系

PyINT 不应新建第二套精轨目录。

应直接复用现有治理链路：

源目录：MONITOR_ORBIT_DIR
运行池：ORBIT_POOL_ENVI
一致性修复：orbit_converter.py
健康检查：health_service.py

也就是说：

PyINT 的精轨输入来源仍应是系统托管的轨道池
不是让用户每次在前端再手工填一条轨道路径

6.5 一期的落地方式

建议每次运行都在 input_assets/orbits/ 下落盘一个轨道摘要，例如：

{
  "policy": "require_txt",
  "pool_root": "D:\\orbit_pools\\envi",
  "master": {
    "date": "20250112",
    "satellite": "LT1A",
    "path": "D:\\orbit_pools\\envi\\LT1A\\LT1A_GpsData_GAS_C_20250112.txt",
    "staged_path": "...\\input_assets\\orbits\\LT1A_GpsData_GAS_C_20250112.txt",
    "resolved": true
  },
  "slave": {
    "date": "20250309",
    "satellite": "LT1A",
    "path": "D:\\orbit_pools\\envi\\LT1A\\LT1A_GpsData_GAS_C_20250309.txt",
    "staged_path": "...\\input_assets\\orbits\\LT1A_GpsData_GAS_C_20250309.txt",
    "resolved": true
  }
}

这一步先解决：

任务是否可跑
运行可追溯
后续桥接可复用

6.6 二期的“真正参与计算”桥接

如果要让系统精轨真实参与 LT-1 PyINT/Gamma 计算，建议单独做一个技术 Spike，候选方向有两个：

修改或包装 PyINT 的 LT-1 导入步骤
- 在 down2slc_LT1.py / LT1_import_SLC_from_zipfiles1 前后插入系统精轨桥接步骤
在 PyINT 前增加一个 LT-1 预处理适配器
- 先把系统精轨和原始场景解析成更稳定的中间输入
- 再把中间输入交给 PyINT 后续流程

建议优先方向是第 1 种，因为它改动面更小。

但在明确 Gamma 对 LT-1 外部精轨的实际消费方式之前，不建议直接承诺实现周期。

7. Gamma 配对集成的关系

select_pairs.py / Gamma 精配对本身是可集成的，但它不应绕开输入资产治理。

建议关系如下：

生产引擎侧先把 PyINT 的 DEM / 轨道输入治理打通。
Gamma 精配对继续作为“配对规划之后的精化步骤”存在。
精配对任务默认继承同一套：
- WSL 环境
- PyINT vendored 代码
- 轨道治理配置
前端入口仍放在 PairPlanningPanel，不放进运维自检。

换句话说：

“生产引擎接入”是必要前置。
“Gamma 配对接入”是可行的，但它应复用同一套输入资产治理，而不是另起一套路径和配置。

8. 运行元数据、结果治理与数据库策略

8.1 一期不改数据库主结构

一期建议不改库，原因是：

当前已有 .dinsar_run.json
当前已有 pyint_run_summary.json
当前已有结果 manifest / catalog

这些已经足够承载输入资产摘要。

8.2 一期建议记录的内容

建议把以下信息写入运行元数据：

input_assets.task_source
- root_dir
- task_dir
- archives.master[]
- archives.slave[]
input_assets.dem
- mode
- source_root
- cache_root
- resolved_output_dir
- key_outputs
input_assets.orbits
- policy
- pool_root
- master
- slave
- stage_mode

8.3 二期改库触发条件

只有出现以下需求时再改库：

需要按 DEM 版本检索历史 PyINT 结果
需要按轨道版本检索历史 PyINT 结果
需要统计“某批结果使用了哪套轨道/DEM”
需要把 PyINT 输入资产做成后台长期查询对象

8.4 如果改库，必须走现有数据库自维护机制

如果进入二期改库，必须：

在 backend/migrations/ 新增 SQL 迁移文件
在 backend/app/db_maintenance.py 的迁移列表中登记
让现有数据库自维护机制自动执行

不允许手工改表绕过现有机制。

9. 健康检查、接口与前端位置

9.1 运维自检面板只做状态，不做主操作入口

当前健康页已经比较重，因此新增内容应控制在“状态摘要”层面：

PyINT enabled
PyINT home
PyINT WSL
PyINT DEM strategy
PyINT orbit policy
PYINT_FABDEM_ROOT 可读
PYINT_ORBIT_POOL_TXT / ORBIT_POOL_ENVI 可读

不建议新增：

手工触发 PyINT 任务按钮
手工填 DEM 路径
手工填轨道路径

9.2 生产页的建议位置

在 DinsarProductionPanel 的 PyINT 引擎区域增加“输入资产预检摘要”，展示：

识别到的任务数
无效任务数
DEM 策略
轨道策略
已解析轨道数量
缺失轨道数量
是否允许提交

9.3 建议新增一个轻量预检接口

建议新增：

POST /dinsar-production/engines/pyint/preview-input-assets

任务解析结果
DEM 配置状态
轨道解析状态
阻断原因
警告列表

这样前端可以在正式提交前给出明确反馈，而不是等任务进入队列后才失败。

9.4 PairPlanning 页的位置

Gamma 精配对仍建议放在 PairPlanningPanel：

先显示已有粗配对网络
再提供 Gamma 精配对入口
不把它塞回健康检查页

10. 推荐实施顺序

Phase 1：输入资产适配层

固化 Task_* 路径解析规则
新增输入资产预检模型
生成 task_manifest.json
生成 input_assets/orbits/ 与 input_assets/dem/ 目录

Phase 2：DEM 正式接入

增加 PYINT_DEM_MODE
增加 PYINT_FABDEM_ROOT
在 template 生成时注入 fabdem_dir / opentopo_*
把 DEM 解析摘要写入 run metadata

Phase 3：精轨治理接入

增加 PYINT_ORBIT_POLICY
复用 ORBIT_POOL_ENVI
运行前做 master/slave 精轨解析
缺失时按策略阻断
把轨道文件 staging 到运行目录

Phase 4：前端预检入口

生产面板显示资产预检摘要
健康页只增加状态项

Phase 5：精轨计算桥接 Spike

研究 LT-1 PyINT/Gamma 当前导入链路如何真正消费外部精轨
决定是补包装步骤还是补脚本修改

Phase 6：Gamma 精配对集成

在配对规划页复用同一套 PyINT/Gamma 环境和资产治理策略

11. 最终建议

对于你提出的三个问题，建议明确回答如下：

Task_* 路径怎么配合
继续沿用现在的任务目录，不改用户输入方式；系统内部新增适配层把任务目录转换为 PyINT 工作区。
DEM 怎么处理
一期就做系统托管，推荐以本地 FABDEM/DEM 源目录为标准输入，由 PyINT 在受控 DEMDIR 下生成本次任务真正使用的 DEM 产物。
精密轨道怎么处理
一期先接入系统精轨池做校验、阻断、记录和 staging；二期再补“真实参与 LT-1 PyINT/Gamma 计算”的桥接。当前实现还不能直接把这一步视为已经完成。

基于当前代码现状，最稳妥的方向不是“删掉 Task_* 模式重新发明一套 PyINT 路径”，而是“把 Task_* 保留为业务输入，把 DEM/精轨补成系统托管资产适配层”。

补充：现有 DEM 复用实现（2026-04-19）

当前代码已补充 PYINT_DEM_MODE=prepared_file，用于复用系统现有 DEM 资产。

PYINT_PREPARED_DEM_PATH 可显式指定现有 DEM 基础文件。
若该值为空，运行时会按顺序回退解析 ISCE2_DEM_PATH 和 IDL_DINSAR_DEM_BASE_FILE。
如果目标文件同名存在 .par，则视为现成的 Gamma DEM，直接写入 PyINT 模板中的 DEM=...。
如果目标文件没有 .par，但同名存在 .xml、.hdr 或 .vrt，则视为系统现有源 DEM。
对“系统现有源 DEM”，PyINT 在 makedem_pyint.py 中会根据 master 的 SLC_par 覆盖范围先裁剪局部窗口，再转换为本次任务使用的 Gamma DEM。
这样可以复用系统已经维护的中国区或全局 DEM，不必强制切回 FABDEM 或重新在线下载。

这个实现的约束也需要明确：

现有源 DEM 仍必须是可被 GDAL 打开的本地文件。
运行环境里仍需要 gdal_translate 可用，因为裁剪发生在 WSL/PyINT 侧。
该模式的本质不是“直接把 ISCE2 DEM 原样交给 Gamma”，而是“把系统现有 DEM 当作受控源，再为每次 PyINT 任务生成 Gamma 可消费的局部 DEM 产物”。

18 KiB Raw Blame History Unescape Escape