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,防止把外部模型或分片重新提交。

S
Description
Hand motion pipeline: Dyn-HaMR + dex-retargeting + SPIDER
Readme MIT 5.8 GiB
Languages
Python 99%
Shell 1%