Human-Humanoid-Tools

Human-humanoid-tools (hhtools) 是 RoboParty Lab 开源的人形机器人动作数据工具链。它能用30s的时间，把人体动作（动捕数据、公开数据集、单目视频）或另一台机器人的动作，重映射到任意 URDF 人形机器人上，并提供批量处理和数据集分析。

输出的是目标机器人的关节轨迹（CSV 或 PKL），可以作为 MimicLite、UFO 等控制策略训练的动作数据（接入各训练框架时可能需要格式转换）。单段复杂动作的重映射约 30 秒即可完成。

资源入口：

本节介绍 hhtools 的功能、使用方式和环境配置。完成本节后，你可以在浏览器或桌面应用中打开 hhtools，并用命令行检查各组件是否就绪。

hhtools 有四种使用方式。它们共享同一套动作、机器人和重映射核心，可以按场景选择：

WebUI 和桌面 GUI 使用同一套界面：桌面 GUI 是一个 Electron 应用，在本机启动 hhtools 的 Python 服务，再加载同一个页面。数据始终留在本机。

推荐用 uv 管理环境。先安装 uv，再克隆仓库：

安装全部功能（格式、机器人、重映射、WebUI、Agent / MCP）：

如果只需要部分功能，可以按需选择 extra：

缺少某个依赖时，启动程序会列出缺失的包和修复命令。

注意 all 安装的是 Python 集成库，不包含 GVHMR 和 SMPL 系的模型权重，这两者需要自行准备。

安装内置机器人。 hhtools 提供 7 款精选机器人，从各自上游仓库的固定版本下载：

每款机器人都保留上游许可证和带校验和的来源记录。其他机器人可以在 WebUI 中导入（见 2.2 节）。

准备人体模型权重。 在 SMPL、SMPL+H、SMPL-X 官网注册并下载后，放到以下目录：

hhtools 会先查找这个目录，再查找 ~/.cache/hhtools/body_models/；也可以用环境变量 HHTOOLS_BODY_MODELS 指定其他位置。没有权重时，SMPL 系动作仍能以简化骨架加载和播放，但没有真实的人体网格和精确的关节位置。（请注意mac无法安装）

检查环境。 运行以下命令，检查 WebUI、机器人、重映射、MCP、人体模型和 GVHMR 是否就绪。它只做检查，不会运行任务：

在浏览器中打开 http://127.0.0.1:8009。

常用启动参数：

界面布局。 左侧导航分三组：

中间的舞台用 three.js 显示动作和机器人，右侧是当前工作流的控制面板。所有后台任务（加载、重映射、批处理、分析）都会显示在任务抽屉中，完成后可以从这里导出。

工作区设置。 可以切换界面语言（简体中文 / English，默认跟随系统）、显示或隐藏左右面板、更换动作资源库目录、查看 GVHMR 是否就绪、强制重新分析，以及调整后台任务调度。

注意 在远程服务器上运行时，请通过 SSH 本地端口转发访问 WebUI。在实现远程管理鉴权之前，普通远程浏览器中的设置页为只读。

桌面 GUI 目前为 0.1.0 预览版：

• Windows： 安装程序已打包 Python 运行环境和应用源码，不需要另外准备 Python 或源码仓库。

• Linux： 安装后启动：

  sudo apt install ./hhtools-0.1.0-amd64.deb
  hhtools-desktop
  

• macOS： 把 Human-Humanoid Tools 拖入“应用程序”后启动，按首次启动页提示安装（需保持联网，无需预装 Python 或 Homebrew）。预览版尚未经过 Apple 公证，如果被系统阻止，请在 系统设置 → 隐私与安全性 中选择“仍要打开”。

三个平台的安装包都内置 30 段示例动作和 6 款机器人，但都不包含 GVHMR 和 SMPL 系权重。

注意 macOS 版的重映射使用 CPU，不支持 Intel Mac，也不支持 Video to Motion。

命令行与 WebUI 使用同一套核心。处理上万条数据时，请使用命令行或离线脚本，不要在浏览器中拖入。

各命令的用法见 uv run hhtools \<命令> --help，具体示例见第 2–5 节。

hhtools 为脚本和 AI Agent 提供两种接口，背后是同一套带版本的任务契约：

覆盖范围： 人体到机器人重映射（纯动作、人–物交互、地形场景）、不含场景的机器人到机器人重映射、两者的批处理，以及标定辅助。标定辅助可以生成标定建议、做确定性校验，并输出前视和侧视预览图，供具备视觉能力的模型检查。

暂不覆盖： 含场景的机器人到机器人重映射、Video to Motion、Analysis，以及真机部署。

安装与检查：

hhtools-mcp 是 stdio server，需要由 MCP 客户端启动，而不是在终端中直接运行。仓库自带 Codex 的项目配置（.codex/config.toml），在可信的仓库目录中打开 Codex 后，用 /mcp 确认 hhtools 已连接。

推荐流程： 查询能力 → 登记并检查动作和机器人 → 检查标定状态（缺失时走标定建议、校验、预览、保存）→ 用 smoke 模式预检，得到可执行的计划 → 启动任务并等待 → 查看评估结果和清单 → 确认无误后，重新做一次完整预检，并经用户明确同意再运行全量任务。

注意

• 任务“完成”不代表动作质量合格，最终质量和全量运行都需要人来确认。

• 同一个保存目录只能被一个运行实例占用。不要让 MCP server 和 WebUI 同时使用同一个目录；需要切换时，先断开一个再打开另一个。

完整说明见仓库中的 Agent interfaces。

本节把一段人体动作重映射到目标机器人。在 WebUI 中打开 工作流 → 人体 → 机器人，按“动作 → 目标机器人 → 标定 → 结果”四步完成。

hhtools 能自动识别以下来源的动作，并统一转换成内部的 Motion 格式：

在 资源 → 动作 中管理动作资源库：

• 内置动作： 仓库自带 30 段示例动作，覆盖上表三种类型。

• 导入： 选择导入类型（动作 / 物体交互 / 地形场景），然后选择或拖入文件、文件夹。

• 扫描目录： WebUI 会递归扫描 --source 指定的目录，也可以在工作区设置中更换资源库目录。

注意 hhtools 只提供格式适配，不重新分发数据集。完整数据请从各数据集官网下载，并遵守其许可证。

在 资源 → 机器人 中管理机器人资源库。除 1.5 节的 6 款内置机器人外，可以导入任意 URDF 人形机器人：

1. 选择 .urdf 文件；

2. 选择对应的网格文件夹；

3. hhtools 自动识别关节结构，生成配置文件 robot.yaml（包括人体关节到机器人连杆的映射 ik_map），无需手动调参。

导入的机器人保存在用户配置目录（Linux 下为 ~/.config/hhtools/robots/\<名称>/），不再需要时可以从资源库中移除。

人和机器人的身高、比例和零位姿态都不同。标定用来确定两者之间的缩放和对应关系。每款机器人、每种参考姿势只需标定一次，之后同类动作都会复用。

参考姿势按动作来源区分，例如 SMPL、SMPL-X、GVHMR、LAFAN BVH、SOMA BVH、动捕 BVH、Xsens（100STYLE）、GLB。hhtools 会根据所选动作自动推荐。

标定的步骤：

1. 选择参考姿势，点击 编辑标定；

2. 调整关节值，让机器人姿态与参考骨架对齐；也可以让 hhtools 生成标定建议，它会给出一个评分，并高亮仍需调整的关节；

3. 检查无误后保存。

标定保存在机器人 URDF 旁的 retarget_calibration_\<参考姿势>.yaml 中。

hhtools 有两个求解器，WebUI 会根据动作是否带物体或地形自动推荐，也可以手动切换：

设置 重定向 FPS 后，点击 开始重定向。首次为某款机器人运行时，加载时间会长一些。

完成后，可以在舞台上切换 源、目标、结果 和 叠加 四种视图，对比人体动作和机器人动作。

结果诊断 给出以下指标，并标出“稳定 / 需检查 / 偏差较大”：

注意 结果诊断只用于发现跟踪和接触上的异常。用于真机之前，请先在仿真中验证最终动作。

CSV 的列依次为时间、根部位置（x, y, z）、根部四元数（qx, qy, qz, qw），以及各关节角 dof_\<关节名>。

带物体或地形的结果会打包成 ZIP，其中包括机器人轨迹、各物体轨迹，以及物体和地形的网格。这些都已换算到机器人的尺度和坐标系。

如果重映射效果不理想，可以修改机器人的 robot.yaml。内置机器人在 configs/robots/\<名称>/，导入的机器人在 ~/.config/hhtools/robots/\<名称>/。修改后，下次重映射即生效，不需要重启 WebUI。

提示 人体手臂已经下垂、机器人却仍张着手臂时，优先把 smooth_joint_filter_masks 中 \*_shoulder_roll_link 的值降到 0.1–0.3，而不是只调高 weights。

注意 重新上传 URDF 会重新生成 robot.yaml，手动修改的 ik_map 和权重可能被覆盖；标定文件会保留。

完整模板见仓库中的 configs/robots/_template/robot.yaml，原理见 framework.md。

\<机器人名> 可以用 uv run hhtools robot list 查看。命令行重映射前，需要先在 WebUI 中完成标定，或在 URDF 旁准备好对应的标定文件。

本节把一台机器人已有的动作迁移到另一台机器人上。适合手里只有某款机器人的动作数据（例如已重映射到 RP1 的数据集），想用在另一款机器人上的情况。在 WebUI 中打开 工作流 → 机器人 → 机器人，按五步完成。

hhtools 把源机器人当作“人”来处理：

1. 用源机器人的 URDF 对每一帧做正运动学，得到关键关节的空间位置和朝向；

2. 按源机器人 robot.yaml 中的 ik_map，把它们整理成标准骨架，等同于一段人体动作；

3. 以源机器人零位姿态为参考，标定目标机器人；

4. 用 Newton IK 求解目标机器人的关节轨迹。

注意 如果源文件中没有时间列或采样率（例如 MotionDecode），必须手动设置 源轨迹 FPS。MotionDecode 应设为 120；按默认的 50 Hz 处理会导致播放和重映射速度错误。

这里的操作步骤和Human -> Robot类似，参照Chapter2操作即可。

1. 源机器人： 选择并加载轨迹原本所属的机器人。

2. 源轨迹： 从机器人轨迹资源库加载，或上传文件、文件夹；按需设置源轨迹 FPS。

3. 目标机器人： 选择并加载要迁移到的机器人。

4. 标定： 对这一组机器人做一次标定，保存后会自动复用。标定按“源机器人 + 目标机器人”成对保存，换一组机器人需要重新标定。

5. 结果： 设置重定向 FPS，开始重映射。查看和导出的方式与 2.5、2.6 节相同。

命令行迁移前，需要先在 WebUI 中完成这组机器人的标定，或用 --calibration 指定标定文件。

本节从一段单目视频估计人体动作，生成的动作会自动存入动作资源库，之后可以按第 2 节重映射到机器人。hhtools 使用 GVHMR 的官方发布权重完成推理。

hhtools 不打包 GVHMR 的源码、权重和 Python 环境，需要按 GVHMR 官方说明 单独安装。

Linux： hhtools 会用独立子进程调用已安装好的 GVHMR 环境。启动 WebUI 前指定路径：

需要满足：

• GVHMR 目录保留官方的 inputs/checkpoints 结构，包括已获授权的 inputs/checkpoints/body_models/smplx/SMPLX_NEUTRAL.npz；

• 所选 Python 环境具备 GVHMR 的依赖和 CUDA；

• ffmpeg 在 PATH 中。

不设置路径时，hhtools 会尝试查找 ~/GVHMR、仓库中的虚拟环境，以及名为 gvhmr 的 Conda 环境，但显式指定最可靠。推理默认超时两小时，可以用 HHTOOLS_GVHMR_TIMEOUT_SECONDS 调整。

Windows： GVHMR 作为可选的 Docker 组件运行。用 HHTOOLS_GVHMR_ROOT 指向官方源码目录，HHTOOLS_GVHMR_IMAGE 指向准备好的镜像；人体模型单独存放时，用 HHTOOLS_GVHMR_BODY_MODELS 挂载。

桌面 GUI： 可以在工作区设置的“可选组件”中配置或修复 GVHMR。

注意 macOS 不支持 Video to Motion。

打开 工作流 → 视频 → 动作：

1. 选择视频： 支持 MP4、MOV、MKV、AVI、WebM 和 M4V。

2. 运行环境： 确认 GVHMR 和官方权重显示为“就绪”；未就绪时，页面会列出缺少的项目。

3. 生成动作： 按拍摄情况选择是否为 静态相机，焦距可以设为自动或手动填写，然后点击 启动 GVHMR。

4. 动作结果： 显示帧数、时长和帧率，生成的动作已登记到动作资源库。

已经用 GVHMR 跑出的结果（hmr4d_results.pt），可以直接在 资源 → 动作 中导入，或用命令行转换：

转换需要本地已获授权的 SMPL 系人体模型（见 1.5 节）。

注意 Video to Motion 只使用 GVHMR 官方发布的权重，不支持自定义权重或训练。

本节批量处理多段动作。几十到几百段数据可以在 WebUI 的 工作流 → 批处理 中完成；整套数据集（上万段）请使用离线脚本。

注意 批处理前，请先在 Motion to Robot 或 Robot to Robot 中完成相应的标定。批处理不会弹出标定界面。

批处理页面支持三种任务：

人体 → 机器人批处理

1. 输入： 拖入动作文件或文件夹，或从动作资源库添加，重复项会自动跳过。

2. 目标机器人与校准： 加载目标机器人。页面按参考姿势分组列出输入动作，并检查每一组是否已标定。

3. 运行设置：

   设置	说明
   求解器	Newton IK 在 GPU 上分块并行；Interaction-Mesh 依次处理各段动作
   GPU 批大小	Newton IK 每块的动作数（1–256），留空时自动调整
   源帧率 / 重定向帧率 / 导出帧率	导出帧率默认跟随重定向帧率
   开始 / 结束时间	只处理每段动作中的一段
   输出格式	CSV 或 PKL，可选是否包含 CSV 表头
   结果名称	下载的 ZIP 名称

4. 点击 启动 H2R 批处理。页面显示总体和当前进度，完成后列出失败项和原因，可以下载 ZIP。

机器人 → 机器人批处理

拖入源轨迹（CSV、PKL、NPZ 或数据集文件夹），加载源机器人和目标机器人，设置帧率后点击 启动 R2R 批处理。这组机器人必须先在 机器人 → 机器人 中完成标定。

视频 → 动作批处理

拖入多个视频或文件夹，确认 GVHMR 运行环境，设置静态相机和焦距后点击 启动 V2M 批处理。视频按队列依次处理，生成的动作存入动作资源库；中途失败的可以点击 重试未完成项。

离线脚本适合大规模数据。它们支持断点续跑，每段动作在独立子进程中处理，导出内容与 WebUI 一致。

常用参数：

输出结构：纯动作为 \<out>/…/\<名称>.csv；带场景的片段为 \<out>/\<名称>/\<名称>.csv，旁边附有机器人坐标系下的物体或地形文件。

提示 Newton IK 批量求解失败时，会自动退回到逐段处理。翻滚类动作请关闭脚底贴地修正（见 2.7 节）。

WebUI 中的后台任务默认不限并发。在共享服务器上或显存紧张时，可以启用先进先出的排队：

也可以在 工作区设置 → 后台任务调度 中修改，保存后立即生效，不中断正在运行的任务。命令行参数和环境变量会在下次启动时覆盖界面中保存的值。

注意 并发上限只约束排队的 Web 任务，不包括选择机器人时可能触发的求解器预热，因此不是整个进程的 GPU 并发上限。

本节分析一个动作数据集：计算每段动作的运动学和物理质量指标，打上可解释的标签，在嵌入空间中聚类，并推荐一个多样又有难度的训练子集。在 WebUI 中打开 分析 → 数据分析。

分析不会删除或移动任何源文件。质量差的动作只会被打上标签，是否保留由你决定。

1. 选择数据： 选择数据集文件夹（可以多次添加到上传篮），或使用内置资源库。人体动作和已重映射的机器人轨迹可以放在同一个目录中一起分析。

2. 配置： 选择嵌入方法。当前使用手工特征，PAE 为预留选项。

3. 分析： 点击 开始分析，计算动力学、质量、标签、嵌入和聚类。分析过的数据会缓存，下次可以直接 加载已有结果；输入、场景文件或配置变化后，缓存会自动失效。

4. 结果： 用直方图、散点图和筛选器探索数据，推荐并导出子集。

物理质量 S_phy。 从 100 分中按六类问题扣分：

90 分及以上标为 quality_ok，70–90 分为 quality_warn（建议人工复核），70 分以下为 quality_bad。带地形的动作会按局部地形高度计算漂浮、穿透和滑动。

动态程度。 用关节速度和加速度计算运动复杂度，再按全库分位数分为 static、low_dynamic、mid_dynamic、high_dynamic、burst 五档。

行为标签：

此外还有根部速度、转向速率、腾空比例、步频、腿部与手臂能量、躯干最大倾角、地形起伏等标量指标，可以在界面中逐项查看。

• 指标直方图： 查看任一指标在全库的分布，框选一个区间即可筛选出对应的片段。例如找出水平速度在某个范围内的所有动作。

• 筛选： 按标签、来源（人体 / 机器人）和文件夹筛选。

• 嵌入散点图： 每个点是一段动作，距离越近行为越相似，颜色表示聚类。嵌入由 15 个手工特征标准化后降到二维（安装了 UMAP 时用 UMAP，否则用 PCA），聚类优先使用 HDBSCAN，否则使用 KMeans。

• 预览： 点击任一片段，在舞台上播放；机器人轨迹会自动识别所属的机器人。

推荐子集 从当前筛选出的片段中，选出一部分既多样、又偏向高难度的动作：

每次选出得分最高的片段，直到达到设定的比例。默认比例为 10%，α 为 0.99；α 越小，越偏向复杂的动作。推荐结果只是高亮，不会删除其他片段，也可以在此基础上手动增减。

选中的片段可以导出为 JSON 或 CSV 清单；机器人轨迹还可以 导出机器人 ZIP。

分析的阈值和权重在 configs/analysis/default.yaml 中，包括漂浮和接触的高度阈值、脚滑速度阈值、质量扣分权重、子集推荐的 α 和默认比例，以及并行进程数。

注意 Analysis 目前只能在 WebUI 中使用，命令行和 Agent 接口暂不支持。