Files

T

liyang 7e4ef6f98b Initial snapshot: hand motion pipeline (Dyn-HaMR + dex-retargeting + SPIDER)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-09-15 14:13:49 +08:00

5.5 KiB

Raw Blame History

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。

third_party/Dyn-HaMR/.dynhamr/bin/python scripts/export_dynhamr_dex.py

产物：output/dex_2047635068/human_joints.npz。导出器要求恰好一条完整右手轨迹；MANO convention 按 Dyn-HaMR 原模型计算。

2. 重定向与平滑

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 及依赖资源。

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 帧完整运动学回放和导出

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，不可把源码包误认为含全部运行资源的离线安装包。

上传到本地代码托管平台

先在平台创建空仓库，解压源码包，在解压后的项目目录执行：

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；大数据放平台附件或独立存储。

5.5 KiB Raw Blame History Unescape Escape