hand-motion-pipeline/docs/PIPELINE_LATEST.md

# 最新流程（2026-09-17）：RGB-D 双手视频 → Dyn-HaMR → L20 重定向 → FoundationPose → 参考修复 → SPIDER 物理

本文是 `docs/20260915_171525`（D405 头戴 RGB-D，352 帧，双手 + 红/蓝两个盒子）这条数据上**实际跑通并交付**的链路，按执行顺序给出每一步的脚本、输入、输出、关键参数和验证文件。旧的单手 / 瓶子链路见 [INTEGRATED_PROJECT.md](INTEGRATED_PROJECT.md)，此处不再重复。RL 跟踪训练线不在本文范围。

**当前状态**

- 运动学参考已交付：`output/final_smooth_20260915/`。手-盒 / 手-桌穿透 0（含 2.5 mm 间隙、400 Hz 插值 4681 步），精确 CAD 探针侵入 0，腕位置二阶差分 0.4 mm，手指 0.35°。
- SPIDER 物理滚动：`output/final_spider_run_20260915/`。4680 步全部有限、穿透 0、CAD 探针 0；**但手不真正合拢（实际接触步 20/4680），红盒抬起与蓝盒翻转都未复现**。这是当前主问题。
- 所有"接触"都是几何假设（人手指尖到 CAD 表面最近点），没有触觉真值；蓝盒第 177 帧后被遮挡，位姿只是保持最后可靠值。

## 0. 总览

```text
docs/<seq>/{color.mp4, depth/*.png, intrinsics.json}          docs/上半.stl（红盒）  docs/下半.stl（蓝盒）
        │
 [0] RGB-D 预处理 + 静态背景相机里程计   prepare_rgbd_20260915.py      → output/<seq>/rgbd_camera.npz
        │
 [1] Dyn-HaMR 双手重建                   run_dynhamr_rgbd_20260915.py  → output/<seq>_dynhamr/optimization/
     时序修正（SO(3) 局部均值 + 高斯）    correct_dynhamr_rgbd.py       → .../corrected/prior/*_world_results.npz
     导出人手 21 关节                     export_dynhamr_bimanual_rgbd.py → .../human_joints_{left,right}.npz
        │
 [2] L20 重定向（左右手各跑一次）         retarget_l20_video.py         → .../l20_{left,right}_stable/motion.npz
        │
 [3] FoundationPose 物体 6D 逐帧跟踪      track_yesterday_boxes.py      → output/foundationpose_spider_20260915/foundationpose_objects.npz
     碰撞资产（CoACD）                   decompose_yesterday_boxes.py / build_box_collision_v2.py / build_palm_collision_v2.py
        │
 [4] 手物配准 ①（世界系 + 尺度 + 深度）   register_hands_rgbd.py        → .../registered/
     SPIDER 任务初版                     prepare_yesterday_spider.py   → output/registered_spider_20260915/
     物体参考物理自洽                    smooth_object_reference.py    → output/final_spider_20260915/foundationpose_objects.npz
     手物配准 ②（指根对齐）              register_hands_rgbd.py  HF_ALIGN=mcp → .../aligned/
     SPIDER 任务（最终）                 prepare_yesterday_spider.py   → output/final_spider_20260915/
        │
 [5] 碰撞修复 + 桌面约束                 fix_yesterday_hand_collision.py → output/final_collision_fix_20260915/
     验证 / 审计 / 渲染                  verify_fix_interpolation.py · audit_collision_fix.py · render_collision_fix.py
     分开平滑 + 逐帧联合投影             smooth_project_reference.py   → output/final_smooth_20260915/   ← 最终运动学参考
        │
 [6] SPIDER 物理滚动                     configure_spider_task.py → run_yesterday_spider.py → output/final_spider_run_20260915/
     独立审计 / 重放 / 渲染 / 交互回放    audit_collision_physics.py · check_spider_dynamics_replay.py · audit_spider_dynamic_surfaces.py · render_collision_fix.py --physics · play_spider_result.py
```

### 解释器

| 解释器 | 用在哪 |
|---|---|
| `.venv/bin/python`（执行 `source scripts/foundationpose_env.sh` 后就是 `python`） | FoundationPose、RGB-D 预处理、Dyn-HaMR 启动/修正/导出、配准、prepare / fix / verify / audit / smooth / render、交互回放 |
| `third_party/Dyn-HaMR/.dynhamr/bin/python` | Dyn-HaMR `run_opt.py`（由 `run_dynhamr_rgbd_20260915.py` 内部调用，不用手动进） |
| `.dex/bin/python` | dex-retargeting 0.5.0：`retarget_l20_video.py` |
| `.spider/bin/python` | SPIDER / MuJoCo Warp：`run_yesterday_spider.py`、`audit_collision_physics.py`、`check_spider_dynamics_replay.py` |

离屏渲染脚本默认 `MUJOCO_GL=osmesa`；交互回放脚本自动切 `glfw`。所有脚本从项目根目录执行。环境安装见 [SETUP_AND_WEIGHTS.md](SETUP_AND_WEIGHTS.md)、[FOUNDATIONPOSE_SETUP.md](FOUNDATIONPOSE_SETUP.md)。

### 输入数据

- `docs/20260915_171525/color.mp4`（848×480，标称 30 fps，真实硬件时间跨度 11.70 s）、`depth/`（352 张对齐深度 PNG）、`intrinsics.json`（fx fy cx cy、帧数、时间戳）。RGB / 深度逐帧时间差 < 0.31 ms。
- `docs/上半.stl` = 红盒，`docs/下半.stl` = 蓝盒。米制，18.16×16.60×4.69 cm。**红盒网格不封闭**（一条 T 形边），碰撞资产阶段在副本上修复，原文件不改。
- L20 模型：`third_party/l20_assets/L20/{LEFT,RIGHT}/linkerhand_g20_{left,right}.urdf` 与网格。左右手各用自己的 URDF，不是镜像。

## 1. 各阶段

### [0] RGB-D 预处理与相机里程计

```bash
source scripts/foundationpose_env.sh
python scripts/prepare_rgbd_20260915.py
```

- 输出 `output/20260915_171525/rgbd_camera.npz`：`c2w [352,4,4]`、`intrinsics`、`time`、`valid`、`method`；另有 `rgbd_preflight.json`、`object_assets/`。
- 方法：静态背景 RGB-D 里程计，屏蔽皮肤、红蓝物体和画面底部；无闭环、无外部定位真值。
- **相机是头戴的**，背景帧间移动约 17 px，里程计不能省略；后面所有"世界系"都指这个里程计世界（首帧相机系）。

### [1] Dyn-HaMR 双手重建

```bash
python scripts/run_dynhamr_rgbd_20260915.py        # 内部调用 .dynhamr 解释器
python scripts/correct_dynhamr_rgbd.py
python scripts/export_dynhamr_bimanual_rgbd.py
python scripts/render_corrected_dynhamr_rgbd.py     # 可选：多视角回放视频
```

- `run_dynhamr_rgbd_20260915.py` 把 `rgbd_camera.npz` 写成 ViPE 文件格式（`rgbd_cameras/{pose,intrinsics}/`），然后跑上游 `run_opt.py`：`data=video_vipe is_static=False model.opt_scale=False run_opt=True run_prior=True run_vis=True +data.vipe_pipeline=dynhamr_cameras`，Hugging Face / Torch 缓存离线（`.hf_cache`、`.torch_cache`），EGL 渲染。原始结果在 `output/20260915_171525_dynhamr/optimization/`，逐帧检测在 `dataset/dynhamr/track_preds/<seq>/{000,001}/`。
- `correct_dynhamr_rgbd.py` → `corrected/prior/20260915_171525_000000_world_results.npz`、`comparison_joints.npz`、`validation.json`。腕与手指旋转做合法旋转空间局部加权平均（σ 1.2 帧），平移高斯 σ 1.5 帧（用未来帧，非实时滤波）。腕位置二阶差分 RMS 左 5.38→0.65、右 6.04→0.67 mm。**这一步的 RGB-D 深度门槛把所有帧都拒了（`depth_accepted_frames = 0`），深度修正实际在 [4] 完成。**
- `export_dynhamr_bimanual_rgbd.py` → `human_joints_{left,right}.npz`：`joints [352,21,3]`（腕相对、世界朝向）、`wrist_world`、`time`、`detection_valid`；并把 `rgbd_camera.npz`、`object_assets/` 复制进 `_dynhamr` 目录供后续使用。
- 诊断（只读）：`diagnose_dynhamr_rgbd.py`（`diagnosis/report.md`）、`diagnose_yesterday_hand_depth.py`（留出像素深度残差，`output/hand_depth_diagnosis_20260915/`）。

### [2] L20 重定向

```bash
MUJOCO_GL=osmesa .dex/bin/python scripts/retarget_l20_video.py \
  --input output/20260915_171525_dynhamr/human_joints_right.npz \
  --output-dir output/20260915_171525_dynhamr/l20_right_stable --side right
MUJOCO_GL=osmesa .dex/bin/python scripts/retarget_l20_video.py \
  --input output/20260915_171525_dynhamr/human_joints_left.npz \
  --output-dir output/20260915_171525_dynhamr/l20_left_stable --side left
```

- dex-retargeting 0.5.0 `PositionOptimizer`，16 个独立关节，其余按原 URDF **线性 mimic** 精确展开（`l20_consistent_optimizer.py` 修正了 0.5.0 目标函数与梯度不一致）。离线平滑 `--sigma 2.5` 帧。
- 输出：`motion.npz`（腕位姿 + 关节角）、`trajectory.csv`、`l20_{side}.xml` / `l20_moving.xml`（MuJoCo）、`l20_dex.urdf`、`dex_config.json`、`retarget_validation.json`（指尖拟合误差、最大关节步长、限位越界、mimic 误差、Pinocchio 与 MuJoCo FK 一致性）。日志 `retarget_{side}.log`。
- 手指重定向只用关节**方向**，所以 [4] 的相似变换配准不需要重跑重定向（`register_hands_rgbd.py` 只改写 `motion.npz` 里的腕位置）。

### [3] FoundationPose 物体跟踪与碰撞资产

```bash
source scripts/foundationpose_env.sh
python scripts/track_yesterday_boxes.py       # → output/foundationpose_spider_20260915/foundationpose_objects.npz, foundationpose_overlay.mp4
python scripts/decompose_yesterday_boxes.py   # → output/foundationpose_spider_20260915/collision/{upper,lower}_NNN.obj（CoACD ≤20 块，初版，prepare 用）
python scripts/build_box_collision_v2.py      # → output/collision_fix_20260915/collision_v2/（修 T 形边后的封闭 CAD *_closed.ply + 不限块数 CoACD + manifest.json，fix/smooth 用）
python scripts/build_palm_collision_v2.py     # → output/collision_fix_20260915/hand_collision/（L20 手部网格 CoACD + manifest.json）
```

- 逐帧模型法 RGB-D 位姿，两个 STL 各自跟踪；`T_world = c2w @ T_cam`，c2w 来自 [0]。
- 接受判据（非外部真值）：可见颜色像素 > 500、投影覆盖 > 65%、重叠像素深度中位残差 < 20 mm。红盒 307/352 帧接受，未接受帧插值；蓝盒 177/352，第 177 帧后遮挡，**保持最后可靠位姿并停止作为接触目标来源**。
- 实测噪声：静止红盒逐帧 2nd-diff 5.3 mm、0.56°；遮挡时静止物体会漂 2 cm。这些在 [4] 的物体参考自洽里处理。
- 环境验证：`python scripts/verify_foundationpose_setup.py`，说明见 [FOUNDATIONPOSE_SETUP.md](FOUNDATIONPOSE_SETUP.md)。

### [4] 手物配准、物体参考自洽、SPIDER 任务构建

按下面顺序，5 条命令：

```bash
source scripts/foundationpose_env.sh
# ① 配准（默认：腕对齐，原始里程计相机）→ output/20260915_171525_dynhamr/registered/
python scripts/register_hands_rgbd.py
# ② 任务初版（供物体自洽读取手 / 桌面 / 接触目标）
HF_SPIDER_OUT=$PWD/output/registered_spider_20260915 \
HF_HAND_BASE=$PWD/output/20260915_171525_dynhamr/registered \
python scripts/prepare_yesterday_spider.py
# ③ 物体参考物理自洽（输入/输出路径写死：registered_spider_20260915 + registered/ → final_spider_20260915/）
python scripts/smooth_object_reference.py
# ④ 配准第二遍：指根对齐 + 平滑后的相机 → output/20260915_171525_dynhamr/aligned/
HF_REG_OUT=$PWD/output/20260915_171525_dynhamr/aligned \
HF_CAMERA_FILE=$PWD/output/final_spider_20260915/rgbd_camera_smooth.npz \
HF_ALIGN=mcp python scripts/register_hands_rgbd.py
# ⑤ 最终任务（同目录里已有 ③ 写好的自洽物体参考）
HF_SPIDER_OUT=$PWD/output/final_spider_20260915 \
HF_HAND_BASE=$PWD/output/20260915_171525_dynhamr/aligned \
python scripts/prepare_yesterday_spider.py
```

**① `register_hands_rgbd.py`**（三项刚体/相似修正，不改手指关节；`registration.json`）

1. 世界系：Dyn-HaMR world 与里程计 world 差常量平移 (−0.048, −0.023, −0.115) m，模 12.6 cm，逐帧标准差 < 4 mm。旧流程当同一个 world 用，手物错位 12.6 cm，这是此前腕修正量 8–10 cm 的主因。
2. 尺度：MANO 手在错的深度上与图像轮廓重合（渲染/皮肤面积比 ≈ 1.0），说明真手比 MANO 大；绕相机中心常量缩放，右 1.105、左 1.047，轮廓不变、深度对齐。
3. 残余深度：沿腕射线的逐帧留出像素残差，σ 2 帧平滑。留出残差右 42→9.4 mm、左 20→10 mm。
   环境变量：`HF_ALIGN`（`wrist` | `mcp`）、`HF_CAMERA_FILE`、`HF_REG_OUT`。

**② / ⑤ `prepare_yesterday_spider.py`**：由深度拟合桌面（z-up 是桌面法线，不是 IMU 重力）；逐指尖选最近可观测物体生成可切换接触目标（进入 25 mm / 释放 35 mm）；有界关节/腕平移热启动。输出 `datasets/processed/current/l20/bimanual/boxes/{scene_act.xml, task_info.json, 0/trajectory_kinematic_act.npz}`、`reference_video_rate.npz`、`config.json`、`model_{side}/l20_{side}.xml`、`object_reference.npz`、`preparation.json`。`collision/`、`foundationpose_objects.npz` 缺省时符号链接到 `foundationpose_spider_20260915`。环境变量：`HF_SPIDER_OUT`、`HF_HAND_BASE`。

**③ `smooth_object_reference.py`**：物体只允许两种状态。静止段（0.5 s 窗内位移 < 6 mm、旋转 < 2°、无手接触）冻结在"深度共识"位姿，深度驱动分裂（连续 ≥ 9 帧比原观测差 3 mm 判定真动过），贴桌吸附只在深度残差不变差时接受（深度拟合的桌面只准到 ~1 cm）；握持段（≥ 2 指尖进入 25 mm）在腕系 σ 4 帧平滑后随手刚性运动，比纯平滑差 > 1 mm 则退回；自由段 σ 2；里程计 c2w σ 2。红盒 2nd-diff 4.7→1.5 mm，蓝盒 8.8→2.6 mm，深度残差不劣于原始。输出 `foundationpose_objects.npz`（同 schema）、`rgbd_camera_smooth.npz`、`object_segments.npz`、`object_smoothing.json`。

**④ `HF_ALIGN=mcp`**：L20 比缩放后的人手大 35–60%，差异几乎全在手掌（腕到指根 148 vs 90 mm）。改为 L20 指根中心对齐人手指根，腕自动后退 58–61 mm；人手指尖（接触目标）不变。L20 base 系约定已数值验证（`landmark_world = wrist_R @ local + wrist_pos`，误差 0）。

### [5] 碰撞修复 + 桌面约束 + 平滑投影 → 最终运动学参考

```bash
source scripts/foundationpose_env.sh
export HF_FIX_OLD=$PWD/output/final_spider_20260915 \
       HF_FIX_OUT=$PWD/output/final_collision_fix_20260915 \
       HF_WRIST_WEIGHT=200 HF_MARGIN=0.0025 HF_TABLE=1 \
       SPIDER_TASK_OUT=$PWD/output/final_collision_fix_20260915
python scripts/fix_yesterday_hand_collision.py                 # 修复
python scripts/verify_fix_interpolation.py --video --buffer    # 视频率状态检查 + 投影
python scripts/verify_fix_interpolation.py --buffer            # 400 Hz 插值 4681 步检查 + 投影（物体固定）
python scripts/audit_collision_fix.py                          # 独立审计 → validation.json
python scripts/render_collision_fix.py                         # hand_collision_before_after.mp4

export HF_SMOOTH_OUT=$PWD/output/final_smooth_20260915
python scripts/smooth_project_reference.py                     # 平滑 + 联合投影
export HF_FIX_OUT=$HF_SMOOTH_OUT SPIDER_TASK_OUT=$HF_SMOOTH_OUT
python scripts/verify_fix_interpolation.py --buffer
python scripts/audit_collision_fix.py
python scripts/render_collision_fix.py
```

- `fix_yesterday_hand_collision.py`：解析接触雅可比 + 精确 mimic，逐帧最小改动求解，目标 = 接触目标 + 腕先验（`HF_WRIST_WEIGHT`，默认 25，本链 200）+ 关节限位；间隙放进求解器（`HF_MARGIN`，默认 0.5 mm，本链 2.5 mm）而不是事后投影（事后投影曾在 201–203 帧产生 88 mm 跳变）；`HF_TABLE=1` 把桌面变成硬约束（floor conaffinity 3）。碰撞体来自 `collision_v2/` + `hand_collision/`。
- `verify_fix_interpolation.py` / `audit_collision_fix.py`：分别检查视频率与 400 Hz 插值状态、全连杆碰撞、限位、连续性和**精确闭合 CAD 采样探针**（CoACD 近似之外的独立检查）。都吃 `HF_FIX_OLD / HF_FIX_OUT / HF_TABLE`。
- `smooth_project_reference.py`：腕位置高斯 σ 2 帧、腕旋转 SO(3) 局部加权均值 σ 2、16 个独立手指关节 Savitzky–Golay（窗 11、二阶）后精确 mimic 展开、物体不动；再逐帧最小改动投影：线性化接触距离 ≥ 2.5 mm（盒 + 桌）、关节限位、相对上一帧步长上限（8 mm / 7° / 8.6°）。环境变量 `HF_SMOOTH_OUT HF_SIGMA_POS HF_SIGMA_ROT HF_SG_WINDOW HF_CLEARANCE`。
- 交付目录 `output/final_smooth_20260915/`（README 在内）：`reference_video_rate.npz`、`datasets/.../0/trajectory_kinematic_act.npz`（400 Hz）、`validation.json`、`smoothing_report.json`、`hand_collision_before_after.mp4`。交互回放：`python scripts/play_spider_result.py --directory output/final_smooth_20260915 --mode reference`（空格暂停，← → 逐帧）。

| 指标（右 / 左） | 修复后（final_collision_fix） | 平滑投影后（final_smooth） |
|---|---:|---:|
| 腕位置二阶差分 RMS | 3.05 · 3.15 mm | 0.41 · 0.37 mm |
| 手指二阶差分 RMS | 1.49° · 1.33° | 0.38° · 0.32° |
| 右腕修正中位 / 118–235 帧段 | 11 / 45 mm | — |
| 接触间隙中位 | 7.1 · 5.7 mm | 8.0 · 7.8 mm |
| 最大穿透（盒 + 桌，含 400 Hz 插值） | 0 | 0 |
| 精确 CAD 探针最大侵入（红 / 蓝） | — | 0.00 / 0.00 mm |

### [6] SPIDER 物理滚动

```bash
export SPIDER_SRC=$PWD/output/final_smooth_20260915 \
       SPIDER_TASK_OUT=$PWD/output/final_spider_run_20260915 \
       HF_FIX_OLD=$PWD/output/final_spider_20260915
source scripts/foundationpose_env.sh
python scripts/configure_spider_task.py                       # 复制任务 + 施加物理参数 → physics_parameters.json
.spider/bin/python scripts/run_yesterday_spider.py --pilot    # 冒烟：80 步、32 样本、2 轮
.spider/bin/python scripts/run_yesterday_spider.py            # 全程：64 样本 × 3 轮，horizon 0.4 s，ctrl_dt 0.1 s，4680 步
.spider/bin/python scripts/audit_collision_physics.py         # CPU 独立碰撞逐步检查 → physics_validation.json, physics_motion.npz
.spider/bin/python scripts/check_spider_dynamics_replay.py    # 保存控制量在全新 GPU 世界 + CPU 重放 → control_replay.json
python scripts/audit_spider_dynamic_surfaces.py               # 原始手部可视网格 vs 精确封闭 CAD 探针 → dynamic_surface_validation.json
python scripts/render_collision_fix.py --physics              # spider_collision_rollout.mp4（原视频 / 运动学参考 / 物理结果）
python scripts/play_spider_result.py --directory output/final_spider_run_20260915 --mode physics   # 交互回放
```

- `configure_spider_task.py`：从 `SPIDER_SRC` 复制 `scene_act.xml`、`task_info.json`、`trajectory_kinematic_act.npz`、`reference_video_rate.npz`、`config.json`（只改 `dataset_dir`），并写入经 GPU/CPU 短段重放选出的物理设置（仿真假设，非硬件标定）：求解 80 / 线搜索 50；所有 geom `solimp .9 .95 .001 .5 2`、`solref .02 1`；手/物/桌 `margin 4 mm gap 2 mm`（2 mm 提前激活）；腕平移 kp 500 kv 30 ±20 N，腕旋转 kp 15 kv 2 ±2 Nm，手指 kp 4 kv 0.15 ±0.1 Nm（`HF_FINGER_KP / HF_FINGER_KV / HF_FINGER_TORQUE` 可改）；物体执行器零增益（真实滚动无物体辅助）；桌面与手碰撞。`SPIDER_CONFIG_OVERRIDES='{"contact_rew_scale": 8, "num_samples": 128}'` 可覆盖 SPIDER config。
- `run_yesterday_spider.py`：调用上游 `third_party/spider/examples/run_mjwp.py`（MuJoCo Warp 采样优化），本地补丁：双手含被动关节的奖励权重划分、跨物体换握时关闭"单手固定物体"启发式、非有限状态即停。物体质量 0.12 kg、摩擦 0.8 是假设。上游 SPIDER 的其余本地修改（辅助弹簧力公式、接触奖励权重、重采样漏控制量、GPU 接触参数）随 `third_party/spider` 源码快照保留。
- 结果（`final_spider_run_20260915/README.md`）：

| 指标 | 值 |
|---|---:|
| 物理步 / 全部有限 | 4680 / 是 |
| 最大手物穿透（CPU 独立检测）/ CAD 探针 | 0 / 0 mm |
| 实际接触步数（< 1 mm） | 20 / 4680 |
| 红盒观测段位置误差均值 / 旋转误差 | 93 mm / 8.1°（0–5 s 跟得住，6 s 参考抬起后物理盒留桌上） |
| 蓝盒观测段位置误差均值 / 旋转误差 | 39 mm / 123°（1–2 s 参考翻转，物理盒不翻） |
| 保存控制量独立 GPU 重放最大状态差 | 0.456 |

结论：参考干净之后，失败模式变清楚，**手不真正合拢握住物体**，位置伺服跟参考就是"悬着"。参考间隙 0.5 mm + `contact_rew_scale 8` + 128 样本 × 5 轮的变体（`output/final_spider_run_v2_20260915/`）**无实质变化**（接触步 20→5），说明不是采样量问题，是参考/奖励只要求指尖到表面、不要求夹紧。

## 2. 已知问题与候选方向（运动学 / SPIDER 线）

- 接触语义：L20 比人手大，接触目标取人手指尖最近点，右手 118–235 帧腕仍要抬 45 mm 才能不进盒。候选：用 L20 指尖自身最近点做目标、按手长比例外推、或该段降接触权重。
- 夹紧：参考里给 on-接触帧手指多屈几度（目标进入物体一点）；手指力矩上限 0.1→0.3 Nm / kp 4→8；或奖励加法向力项。这些都改变仿真假设，需要决定。
- 右手指尖到红盒表面配准后仍约 4 cm（遮挡下 MANO 手指姿态误差），接触目标本身有此量级不确定性。
- 蓝盒 177 帧后无观测；红蓝相对装配不是已验证事实。
- 未验证真机；未做力/摩擦标定。

## 3. 换一段新视频要改什么

脚本里序列名和输入路径大多写死为 `20260915_171525`（或 `yesterday` 命名），环境变量只覆盖**输出**目录。新视频需要：

1. 放到 `docs/<seq>/{color.mp4, depth/, intrinsics.json}`，物体 CAD 放 `docs/`。
2. 改这些脚本里的常量：`prepare_rgbd_20260915.py`（`SRC/OUT`）、`run_dynhamr_rgbd_20260915.py`（`SEQ`）、`correct_dynhamr_rgbd.py` / `export_dynhamr_bimanual_rgbd.py`（`BASE/SRC`）、`track_yesterday_boxes.py`（`SRC/OUT`、STL 名）、`decompose_yesterday_boxes.py`（STL 名）、`smooth_object_reference.py`（`SRC/OLD/HAND/OUT`）、`register_hands_rgbd.py`（`BASE`）。
3. `prepare_yesterday_spider.py` 里颜色→CAD 映射（红 = `上半`/upper，蓝 = `下半`/lower）和物体质量 / 摩擦假设。
4. 之后 [4]–[6] 只靠环境变量指路径，不用改代码。

## 4. 脚本索引

| 阶段 | 脚本 | 解释器 | 输入 → 输出 | 环境变量 / 参数 |
|---|---|---|---|---|
| 0 | `prepare_rgbd_20260915.py` | .venv | docs/<seq> → output/<seq>/rgbd_camera.npz | — |
| 1 | `run_dynhamr_rgbd_20260915.py` | .venv（内部 .dynhamr） | color.mp4 + rgbd_camera → <seq>_dynhamr/optimization | — |
| 1 | `correct_dynhamr_rgbd.py` | .venv | optimization → corrected/prior/*_world_results.npz | — |
| 1 | `export_dynhamr_bimanual_rgbd.py` | .venv | corrected → human_joints_{left,right}.npz | — |
| 1 | `render_corrected_dynhamr_rgbd.py`、`diagnose_dynhamr_rgbd.py`、`diagnose_yesterday_hand_depth.py` | .venv | 可视化 / 诊断（只读） | — |
| 2 | `retarget_l20_video.py` | .dex | human_joints_{side}.npz → l20_{side}_stable/ | `--input --output-dir --side --sigma` |
| 3 | `track_yesterday_boxes.py` | .venv (foundationpose_env) | RGB-D + STL → foundationpose_objects.npz | — |
| 3 | `decompose_yesterday_boxes.py`、`build_box_collision_v2.py`、`build_palm_collision_v2.py` | .venv | STL / L20 网格 → CoACD 凸块 | — |
| 4 | `register_hands_rgbd.py` | .venv | human_joints + rgbd_camera → registered/ 或 aligned/ | `HF_ALIGN HF_CAMERA_FILE HF_REG_OUT` |
| 4 | `prepare_yesterday_spider.py` | .venv | 手 + 物体 → SPIDER 任务目录 | `HF_SPIDER_OUT HF_HAND_BASE` |
| 4 | `smooth_object_reference.py` | .venv | registered_spider + registered → final_spider（物体参考） | — |
| 5 | `fix_yesterday_hand_collision.py` | .venv | 任务目录 → 无穿透参考 | `HF_FIX_OLD HF_FIX_OUT HF_WRIST_WEIGHT HF_MARGIN HF_TABLE`；`--pilot` |
| 5 | `verify_fix_interpolation.py` | .venv | 视频率 / 400 Hz 检查投影 | `HF_FIX_OLD HF_FIX_OUT HF_TABLE`；`--video --buffer` |
| 5 | `audit_collision_fix.py` | .venv | 独立审计 → validation.json | `HF_FIX_OLD HF_FIX_OUT HF_TABLE` |
| 5 | `smooth_project_reference.py` | .venv | 修复参考 → 平滑投影参考 | `HF_FIX_OLD HF_FIX_OUT HF_SMOOTH_OUT HF_TABLE HF_SIGMA_POS HF_SIGMA_ROT HF_SG_WINDOW HF_CLEARANCE` |
| 5/6 | `render_collision_fix.py` | .venv | 三栏对比视频 | `SPIDER_TASK_OUT HF_FIX_OLD`；`--physics` |
| 6 | `configure_spider_task.py` | .venv | 参考目录 → SPIDER 任务 + 物理参数 | `SPIDER_SRC SPIDER_TASK_OUT HF_FINGER_KP/KV/TORQUE SPIDER_CONFIG_OVERRIDES` |
| 6 | `run_yesterday_spider.py` | .spider | 任务目录 → trajectory_mjwp_act.npz | `SPIDER_TASK_OUT`；`--pilot --steps` |
| 6 | `audit_collision_physics.py`、`check_spider_dynamics_replay.py` | .spider | 物理轨迹审计 / 控制量重放 | `SPIDER_TASK_OUT` |
| 6 | `audit_spider_dynamic_surfaces.py` | .venv | 精确 CAD 探针 | `SPIDER_TASK_OUT` |
| 6 | `play_spider_result.py` | .venv | 交互回放 | `--directory --mode {reference,physics} --check` |

## 5. 历史 / 对照目录（不要误用）

| 目录 | 说明 |
|---|---|
| `output/20260915_171525/` | HandFlow 分支的双手初版（镜像左手 + ICP 物体位姿），已被 Dyn-HaMR + FoundationPose 链路取代 |
| `output/foundationpose_spider_20260915/` | 首次全链路（配准前）。手物错位 12.6 cm，Spider 红盒误差 61 mm |
| `output/collision_fix_20260915/` | 配准前的碰撞修复，腕修正中位 82 / 100 mm；其 `collision_v2/`、`hand_collision/` 资产仍被后续目录符号链接 |
| `output/registered_collision_fix_*_20260915/` | 配准后三个修复变体，推荐 `w200m25`（腕先验 200 + 内置 2.5 mm 间隙） |
| `output/desktop_smooth_fix_20260915/` | `smooth_table_constrained.py` 只抬腕出桌面，手盒穿透回到 24.5 mm，**失败对照** |
| `output/final_smooth_c05_20260915/`、`output/final_spider_run_v2_20260915/` | 间隙 0.5 mm + 接触奖励 8 + 128 样本变体，无实质变化 |
| `output/spider_dynamics_fix_20260915/` | Codex 的 SPIDER 动力学修复轮（物理参数从这里选出） |