跳转至

当前 Pipeline

最后更新：2026-07-24。

本页是当前可执行 HSI generation pipeline 的工程事实源。公开入口是 tools/run_hsi_generation.py；旧 tools/kimodo/legacy/run_kimodo_hoi_pipeline.py 和旧文档里的中间文件链不是主线。研究结论见 项目范围，结果见 Kinematic Generation。

Public interface

PYTHONPATH=/mnt/data/PhysHSI:/mnt/data/PhysHSI/submodules/kimodo \
python tools/run_hsi_generation.py \
  --task-plan <task_plan.json> \
  --layout-json <layout_*.json> \
  --out-dir <case_output_dir>

只有三个公开参数：

  • task_plan：动作语义、对象、目标和时序输入；
  • layout_json：场景与真实 object geometry 的 source of truth；
  • out_dir：canonical case output。

runtime/debug knob 不进入 public task semantics；未知 config field 由 normalize_config 拒绝。

当前数据流

task_plan + layout_json
  → planning.build_clips / build_execution_plan
  → anchors.build_anchors
  → kimodo.prepare_task_scaffold
  → constraint.prepare
  → contact.prepare_expected
  → kimodo.generate_scaffold       # 一次 full-body scaffold
  → hands.bake
  → object_motion.apply
  → evaluation.measure / render_and_audit
  → compact canonical artifacts

主实现位于 utils/hsi_generation/pipeline.py。stage runner 只编排；geometry、binding、hand/object interaction 和 metric 在各自 domain module 中。

落盘策略

成功 case root 只保留：

motion.npz
pipeline_manifest.json
validation.json
kinematic_video.mp4

debug/stage_files/ 只在 failure 时保留；成功后删除。stage 之间通过函数返回值和 case dict 传递状态，manifest 只在末端记录 provenance。

当前支持边界

  • planner 根据 task semantics 生成可复用 action-template execution plan；
  • pick/carry/place 是当前 regression case，不是 public API 中的硬编码版本号；
  • dynamic object 可以多对象序列化，但 canonical output 只保存 id/type/pose；
  • geometry consumer 必须用 layout_json + object_id 读取真实 mesh；
  • missing required input 直接失败。

Legacy 边界

以下内容只作历史追溯：

  • specialized tools/kimodo/legacy/run_kimodo_hoi_pipeline.py；
  • 以 pipeline_manifest.json 驱动下游 stage；
  • 为每个 stage 永久保留大量 .npz/.json；
  • v13/v20 等 one-off 行为作为 public default；
  • 旧 SOMA residual dataset/runner。

旧 spec 已归档为 legacy Kimodo pipeline spec，不得从其中复制运行命令。

验证

在项目指定环境中运行 focused suite：

PYTHONPATH=/mnt/data/PhysHSI:/mnt/data/PhysHSI/submodules/kimodo \
/mnt/data/PhysHSI/env_protomotions_isaaclab/bin/python -m pytest -q \
  tests/test_hsi_generation_pipeline.py \
  tests/test_hsi_generation_formal_boundary.py \
  tests/test_hsi_generation_hand_object_interaction.py \
  tests/test_hsi_generation_motion.py

本次审计中该组连同 tracking/metric focused tests 返回 exit code 0。系统 Python 缺 kimodo/torch 的失败不代表项目环境失败。

下一步

运行 case 后先读 validation.json，再进入 Tracking。不要只因 motion.npz 和视频存在就启动大规模 teacher 训练。