100 lines
5.5 KiB
Markdown
100 lines
5.5 KiB
Markdown
# Dyn-HaMR → dex-retargeting → SPIDER 集成说明
|
||
|
||
## 组件和职责
|
||
|
||
| 层 | 上游/实现 | 输入与输出 |
|
||
|---|---|---|
|
||
| 人手重建 | Dyn-HaMR、HaMeR、ViPE | 视频 → MANO 参数与估计世界轨迹 |
|
||
| 另一条重建入口 | HandFlow | 视频 → 时序 MANO 与相机/世界坐标结果 |
|
||
| 机器人重定向 | dex-retargeting 0.5.0 + scripts/l20_* | 21 点人手几何 → L20 右手关节及浮动腕部 |
|
||
| 接触优化实验 | SPIDER 上游 runner + L20 场景适配 | 机器人/物体参考轨迹 → 接触引导优化与回放检查 |
|
||
| 数据交付 | export_l20_right_hdf5.py | 机器人参考轨迹 → HDF5 |
|
||
|
||
集成脚本与上游项目分别保留；不能把上游算法或整个仓库归为本地个人实现。
|
||
|
||
## 当前入口和顺序
|
||
|
||
以下命令从项目根目录执行，输入文件、权重、模型和环境须先准备。这里只列出已存在入口，不代表干净机器已端到端复现。
|
||
|
||
### 1. 重建结果
|
||
|
||
Dyn-HaMR 原生入口为 `third_party/Dyn-HaMR/dyn-hamr/run_opt.py`，参数见其 README 和配置。`scripts/resume_dynhamr_2047635068.py` 是已有缓存的恢复脚本，依赖 `output/vipe_weights_downloads.txt` 及先前生成的缓存，不能当作新视频通用入口。
|
||
|
||
本地 ViPE 调用已采用 Python CLI；相关修改随源码快照保留。环境与数据路径仍需按部署机器配置。
|
||
|
||
本例期望重建产物位于 `output/results_2047635068/world_results.npz`。
|
||
|
||
```bash
|
||
third_party/Dyn-HaMR/.dynhamr/bin/python scripts/export_dynhamr_dex.py
|
||
```
|
||
|
||
产物：`output/dex_2047635068/human_joints.npz`。导出器要求恰好一条完整右手轨迹；MANO convention 按 Dyn-HaMR 原模型计算。
|
||
|
||
### 2. 重定向与平滑
|
||
|
||
```bash
|
||
MUJOCO_GL=osmesa .dex/bin/python scripts/run_dex_l20.py
|
||
MUJOCO_GL=osmesa .dex/bin/python scripts/run_dex_l20.py \
|
||
--output-dir output/l20_2047635068/jitter_audit/corrected
|
||
MUJOCO_GL=osmesa .dex/bin/python scripts/smooth_l20_offline.py
|
||
```
|
||
|
||
该分支使用 JSON 非线性标定联动。后续 SPIDER/完整回放构建器按原 URDF 重新展开线性联动；两种约束不能混称为同一个模型。
|
||
|
||
HandFlow 分支的入口为 `scripts/demo.py` → `export_handflow_dex.py` → `retarget_l20_video.py`；后者支持 `--input` 和 `--output-dir`，直接使用 URDF 线性联动。
|
||
|
||
### 3. SPIDER 实验
|
||
|
||
先准备 `third_party/l20_assets/L20/RIGHT/` 和 `third_party/bottle_model_parametric/bottle.xml` 及依赖资源。
|
||
|
||
```bash
|
||
MUJOCO_GL=osmesa .spider/bin/python scripts/prepare_spider_l20.py
|
||
MUJOCO_GL=osmesa .spider/bin/python scripts/run_spider_l20_contact.py
|
||
MUJOCO_GL=osmesa .spider/bin/python scripts/evaluate_spider_l20.py
|
||
```
|
||
|
||
准备脚本选择第 600–659 帧的 2 秒片段，并估算瓶子相对位姿。必须查看实际运行日志和评估结果；程序开始运行不等于优化完成或稳定抓取。
|
||
|
||
### 4. 1333 帧完整运动学回放和导出
|
||
|
||
```bash
|
||
MUJOCO_GL=osmesa .spider/bin/python scripts/build_l20_full_replay.py
|
||
MUJOCO_GL=osmesa .spider/bin/python scripts/verify_l20_full_replay.py
|
||
MUJOCO_GL=osmesa .spider/bin/python scripts/play_l20_full.py --render
|
||
MUJOCO_GL=osmesa .dex/bin/python scripts/export_l20_right_hdf5.py \
|
||
--source output/l20_full_replay/motion.npz \
|
||
--scene output/l20_full_replay/scene.xml \
|
||
--output output/hdf5_delivery/right_1333
|
||
```
|
||
|
||
`.dex` 环境还需可导入 h5py。最终完整回放为运动学指定状态及接触配准，不是 44 秒 SPIDER 动力学成功轨迹。瓶子位姿是估计注册；HDF5 只导出手部状态，右手约定与原左手验收要求不同。详见 HDF5 根属性和 `docs/HDF5_REQUIREMENTS.md`。
|
||
|
||
## 环境
|
||
|
||
本机使用独立环境：`.venv`（HandFlow/ViPE）、`third_party/Dyn-HaMR/.dynhamr`、`.dex`、`.spider`。保留兼容的 Torch/CUDA，避免将多个上游依赖盲目装入一个环境。
|
||
|
||
- 原 HandFlow 的 `requirements.txt` 和 setup 脚本保留历史默认值，不代表当前集成环境锁。
|
||
- `requirements/retarget.txt` 为重定向与导出依赖列表；`retarget_observed.json` 为本机观测版本，不是完整锁文件。
|
||
- Dyn-HaMR/SPIDER/ViPE 的安装步骤分别见所附上游 README、requirements 或 pyproject 文件；GPU 扩展需匹配实际 Python、Torch、CUDA。
|
||
- 示例解释器路径表示角色约定，可替换为部署环境的对应解释器。不要复制本机 venv 或其中的绝对路径 `.pth` 文件。
|
||
|
||
## 资源与代码托管
|
||
|
||
权重、MANO 参数、用户视频、缓存和实验输出不进源码包。L20 模型及标定文件也作为独立资源管理，接收方按 `EXTERNAL_ASSETS.json` 恢复原相对路径。资源使用条件分别由提供方约定；根 LICENSE 不覆盖所有第三方资源。
|
||
|
||
源码导出脚本将本机实际第三方源码以普通目录快照保存，包含本地改动，保留 LICENSE。它不依赖平台能递归拉取 Git 子模块。第三方版本和文件 SHA-256 记录在交付清单中；dex-retargeting 通过版本依赖安装。被排除的上游文件记录在 `EXCLUDED_FILES.json`，不可把源码包误认为含全部运行资源的离线安装包。
|
||
|
||
## 上传到本地代码托管平台
|
||
|
||
先在平台创建空仓库，解压源码包，在解压后的项目目录执行：
|
||
|
||
```bash
|
||
git init -b main
|
||
git add .
|
||
git commit -m "Import integrated hand reconstruction and L20 retargeting pipeline"
|
||
git remote add origin <本地平台仓库地址>
|
||
git push -u origin main
|
||
```
|
||
|
||
源码包没有原 Git 历史或 remote；当前工作目录的上游 origin 未修改。提交前可查看 `git status --short`；大数据放平台附件或独立存储。
|