5.8 KiB
Hand Motion Pipeline
从 D405 RGB-D 视频重建人手动作,重定向到 L20 左右手,估计物体 6D 位姿,再进行配准、接触参考修复和 SPIDER 物理优化。
RGB-D + 相机内参 + 物体 CAD
→ RGB-D 里程计 + Dyn-HaMR 人手重建
→ dex-retargeting + L20 → 关节与腕部轨迹
→ FoundationPose 6D 跟踪 → 手物配准
→ 接触目标 / 碰撞修复 / 桌面约束 / 平滑投影
→ SPIDER / MuJoCo Warp 物理优化与审计
示例是 20260915_171525 的 352 帧双手红蓝盒子录制。主流程各阶段有代码与命令,当前仍固定部分序列名、帧数和物体映射。现有实验未实现稳定夹持、抬升和翻转,未验证真机。
获取代码、示例和模型
代码与示例资产通过 Git 获取;预训练权重和模型统计数据由使用者从上游获取,不再随当前版本分发。 MANO 需按官方条件申请;HaMeR checkpoint 包含 MANO 参数项,不能只检查是否提交了独立 .pkl。
git lfs install
GIT_LFS_SKIP_SMUDGE=1 git clone --depth 1 https://gitea.robotquan.com/liyang/hand-motion-pipeline.git
cd hand-motion-pipeline
git lfs pull # 示例视频/深度、CAD、机器人网格等当前版本资产
python3 scripts/check_pipeline_resources.py --prepare-example --recording-only
python3 scripts/external_resources.py list --scope all
按 外部模型获取说明 下载、解压或生成资源,恢复指定相对路径;再检查:
python3 scripts/external_resources.py check
python3 scripts/external_resources.py check --verify-sha256
python3 scripts/check_pipeline_resources.py
这些检查不加载 pickle、不自动联网、不替代模型前向和流程验证。参考哈希对应开发快照,部分权重此前来自镜像,未与官方文件独立比对;重新生成的 BMC 统计可能不同。
| 资源 | 获取入口 | 目标目录 |
|---|---|---|
| MANO | 官方申请 | third_party/hamer/_DATA/data/mano/ |
| HaMeR | 上游下载脚本 | third_party/hamer/_DATA/ |
| HMP | Dyn-HaMR 资源脚本 | third_party/Dyn-HaMR/_DATA/hmp_model/ |
| BMC | 上游数据与计算步骤 | third_party/Dyn-HaMR/dyn-hamr/optim/BMC/ |
| WiLoR 检测器 | 模型目录 | weights/detector.pt |
| FoundationPose | 官方安装与权重 | third_party/FoundationPose/weights/ |
L20 左右手的 URDF、网格与标定 JSON 已随本仓库提供,维护者已确认可以随项目上传和分发,无需接收者另找模型文件夹。 资源位于 third_party/l20_assets/,执行 git lfs pull 后即可使用;固定版本清单见 L20 资产说明。
configs/external_resources.json 提供下载入口、文件清单、参考大小与 SHA-256。旧 large_files.py assemble 只管理另行明确允许分发的分片,不能获取这些外部模型。
安装与运行
先按 四环境安装说明 配置,再按 逐阶段命令 运行。根目录 requirements.txt、setup_env.sh、setup_vipe_env.sh 仅服务旧 HandFlow / ViPE 单目分支。
| 环境 | 角色 | Python |
|---|---|---|
.venv |
FoundationPose、RGB-D、配准、修复、渲染 | 3.11 |
third_party/Dyn-HaMR/.dynhamr |
人手重建 | 3.10 |
.dex |
L20 重定向、HDF5 导出 | 3.11 |
.spider |
SPIDER 物理优化 | 上游新部署要求 ≥3.12;历史验证用 3.11 兼容环境 |
需要 NVIDIA GPU、匹配的 Torch/CUDA toolkit 和编译/离屏渲染依赖。路径从项目根目录定位,无需开发者的主目录或旧环境:
source configs/project_env.example.sh
# nvcc 不在 PATH 时:export CUDA_HOME=/path/to/your/cuda-toolkit
source scripts/foundationpose_env.sh
已验证范围
2026-10-29 的隔离源码与依赖副本中,已通过:352 帧 RGB-D 预处理、HaMeR 一次 GPU 前向、8 帧 L20 重定向、FoundationPose C++ 构建/光栅化/网络前向/CAD 初始化、SPIDER 两世界 60 步接触仿真。
这不是从零安装或完整串联通过的声明。 验证复用了本地已有依赖和合法取得的模型;未新跑完整 Dyn-HaMR 时序拟合→接触修复→L20 SPIDER 优化→HDF5。验收软件可运行与抓取成功分别记录,见 验证记录。
许可与其他说明
根 LICENSE 是原 HandFlow 的 MIT。第三方代码保留各自许可;FoundationPose、当前 nvdiffrast 快照、SPIDER 存在非商业使用限制。模型、数据和资产的条件不能由代码许可推定,见 第三方说明。L20 资产已由维护者确认随项目分发,固定版本以 资产清单 为准;与厂商最新模型的版本对应和示例数据许可分别记录,不把整个资源集合标成统一 MIT。
当前提交移除模型载荷不等于清除了旧提交或服务端 LFS。历史清理状态见 发布与历史边界。
发布前运行 python3 -m unittest discover -s tests -v 和 python3 scripts/check_release_policy.py,防止把外部模型或分片重新提交。