跳转至

Tracking 与 Physics Adapter

最后更新：2026-07-24。

本页负责当前 tracking CLI、adapter 边界和工程排错。当前 direct mainline 只支持 protomotions 与 phcx；shared residual refiner 位于 legacy，RePHO/InterMimic/OmniGrasp/GRAIL 使用各自实验 adapter。teacher 研究比较见 Physics Teacher Selection。

Direct tracker

python tools/run_refiner_tracking.py \
  --motion <case>/motion.npz \
  --layout-json <layout.json> \
  --out-dir <tracking_output> \
  --backend protomotions \
  --scene-mode physics

参数：

  • --backend protomotions|phcx；
  • --scene-mode physics|none；physics 必须提供 layout；
  • --checkpoint 可显式覆盖默认 tracker checkpoint；
  • --max-steps 只用于 bounded smoke/diagnostic；
  • --force 允许重跑目标目录。

mainline 直接执行：motion contract → conversion → physics scene → tracker → metrics。它不读取旧 case manifest 来驱动 control flow。

Baseline-specific entrypoints

Family Entry point 说明
InterMimic project tools/run_intermimic_baseline.py human/object/contact full-reference
InterMimic native tools/run_intermimic_native_single.py upstream native reproduction
OmniGrasp tools/run_omnigrasp_baseline.py object-centric pretrained control
Strict OmniGrasp tools/run_strict_omnigrasp.py current contract diagnostic
ResMimic-style tools/run_resmimic_strict_phcx.py frozen PHC-X + residual family
GRAIL tools/audit_grail_minimal_preflight.py 等 gate 未完成，不得直接训练
RePHO 尚无 PhysHSI entrypoint official source 仅已拉入

每个 baseline 的命令以其 canonical experiment 页为准，不把表中“入口存在”解释为 result。

强制 contract

Body shape

converter、simulator asset、mesh evaluator 和 reference 必须使用同一 SMPL-X beta/shape identity。旧 adapted result 若 shape mismatch，只能作为历史诊断。

Coordinate

  • source motion、SAGE layout、AMASS/PHC-X 与 simulator frame 的 transform 必须显式；
  • native Z-up/yaw convention 不通过视觉猜测；
  • body/joint mapping 按名字校验 set、uniqueness 和 round-trip；
  • object/support spawn 与 motion 的 scene_origin_xy 一致。

Geometry

  • target object 使用 layout 的 exact mesh/collision；
  • dynamic object mesh 不从 motion.npz fallback；
  • support/scene mode 在配置和结果中记录；
  • bbox 只可作 coarse diagnostic，不替代 final HOI geometry。

Legacy

src/refiner/legacy/ 保存早期 SOMA dataset、case runner 与 shared residual smoke。当前 src/refiner/pipeline.py 不依赖这些模块。若重新实现 shared refiner，应从当前 canonical motion/domain API 接入，不恢复 manifest-as-state。

排错顺序

  1. validation.json 是否通过输入 gate；
  2. body-shape identity 是否一致；
  3. object id、mesh、mass 和 support 是否正确；
  4. frame transform、spawn XY 与 heading；
  5. converter field/joint mapping；
  6. deterministic short smoke；
  7. telemetry completeness；
  8. 最后才调整 reward 或训练预算。