hand-motion-pipeline/README.md

Hand Motion Pipeline：Dyn-HaMR · dex-retargeting · SPIDER

在 HandFlow 工作区中集成单目人手重建、L20 右手重定向、接触优化实验和 HDF5 轨迹导出。

视频 → Dyn-HaMR / HandFlow + ViPE → 人手世界轨迹
     → dex-retargeting + L20 模型约束 → 机器人腕部与关节轨迹
     → SPIDER 接触引导实验 / 完整运动学回放 → HDF5

从这里开始

• 集成结构、环境、运行顺序与上传步骤
• 重定向方法、验证与限制
• HDF5 原始接口要求：原文为左手；当前导出为明确标记的右手变体。
• HandFlow 原始 README

当前能力

• 已有 L20 右手重定向、腕部运动、平滑、模型约束检查、可视化及 HDF5 导出代码。
• 1333 帧完整回放包含运动学接触配准，不能等同于完整 SPIDER 动力学抓取成功。
• SPIDER 实验和完整运动学回放是不同产物；只根据各自的实际评估结果作结论。
• 部分脚本仍使用 2047635068 / 15886123 示例路径，需要按数据修改；尚未整理为任意视频的一键通用工具。

目录

目录	内容
scripts/	重建导出、L20 适配、SPIDER 场景/运行、回放验证、HDF5 导出
model/、utils/、preprocessing/、visualization/	HandFlow 推理代码
third_party/	上游源码；源码交付包使用带来源记录的普通目录快照
configs/、requirements/	配置、重定向依赖和本机观测版本
docs/	集成、数据与方法说明
output/、权重和本地环境	本地运行资源，不进入源码交付

生成源码交付包

在当前完整开发工作区运行：

python3 scripts/package_source_release.py

输出至 dist/hand-motion-pipeline/ 和同名 .tar.gz。包中保存第三方版本、源码文件哈希、外部资源清单、排除文件及可移植性检查报告。此命令只整理文件，不运行推理，不上传远程仓库。

来源和授权

保留 HandFlow 原 LICENSE；Dyn-HaMR、HaMeR、ViPE、SPIDER 等使用各自目录的上游 LICENSE。dex-retargeting 作为版本依赖使用。本地代码是组件适配与实验集成，上游算法和资源保持原归属。