UniMate：让多种骨骼共享文本生成动画
一个给研究者用的多骨骼文本动画模型，不必为每种骨骼单独训练。
GitHub Friedrich-M/UniMate 更新 2026-10-02 分支 main 星标 1.1K 分叉 101
Python 文本到动画 UniML3D Conda

🧭 决策指南

为什么现在热： README显示项目近期连续开放训练与推理代码、UniML3D数据集和HuggingFace preview checkpoints；同时2026-10-02当日新增217颗星，说明这些发布节点与SIGGRAPH Asia 2026消息共同带来了当前关注度。

适合，如果你

  • 你要用Python 3.10和UniML3D为不同骨骼生成文本动作。
    Environment Setup要求python=3.10；Dataset章节说明UniML3D覆盖多种骨骼拓扑。
  • 你希望直接使用HuggingFace上的UniMate preview checkpoints运行推理。
    News章节说明2026-09-27已发布HuggingFace preview checkpoints，Inference章节给出采样命令。
  • 你需要对已有动作做补间或保留指定关节后重新生成。
    Applications章节提供Motion in-betweening和Text-guided motion editing，并分别给出run_sample_motion_inbetween.sh与run_sample_motion_edit.sh。

不适合，如果你

  • 你的目标是保证所有新OOD骨骼都能稳定工作。
    README称许多motions和skeletons仍会失败，并说明官方新OOD rigs预处理pipeline仍为TODO。
  • 你的数据流程依赖未购买的Truebones动物动作原包。
    Dataset & Data Processing章节说明Truebones ZOO动物动作是不可再分发的商业资产包，需直接购买。
  • 你无法提供训练所用的dataset/features目录来运行checkpoint。
    Inference章节明确要求训练对应的dataset/features//目录存在，并包含目标骨骼条件数据。

前置条件

  • Conda环境名为unimate，Python版本为3.10。
  • 需执行pip install "setuptools<81"和pip install -r requirements.txt --no-build-isolation。
  • 推理输入来自包含config.json、dataset_stats.npy和checkpoints/的训练输出目录。
  • 目标骨骼对应的dataset/features//目录必须存在。
  • 动作网格导出流程使用stage 5，并可输出GLB与FBX。

第一步命令（README 原文）

conda create -n unimate python=3.10 -y

要注意

  • 不带test_cases_json时会枚举eval或train中的数据集样本。
    Inference章节说明缺少--test_cases_json时将枚举eval split，若无则回退到train中的唯一(object_type, caption)。
  • 使用test_cases_txt做无条件采样时必须设置--cfg_scale 1.0。
    Inference章节明确规定无条件采样 requires --cfg_scale 1.0。
  • 只保存npy时使用--only_save_motion，否则还会生成MP4渲染。
    Flags表说明--only_save_motion跳过MP4并只写.npy features。

材料未说明

  • README未说明GPU型号、显存最低要求或CPU是否支持完整推理。
  • README未提供UniMate与其他模型的定量质量、速度或失败率对比。
  • README未说明13,006条UniML3D处理数据何时完成完整开放发布。
  • README未说明HuggingFace preview checkpoints对应的具体模型规模和训练配置。
  • README未说明Interactive Demo与本地checkpoint在结果和性能上的差异。

💡 深度解析

6
不适合在未完成许可核查前整体纳入商业产品，因为代码许可与数据资产许可明确分离。 我可以接受 Python 3.10 和 GPU 部署，也准备使用 MIT 代码；但产品会商业化并可能再分发生成结果，我能否把 UniMate 及其数据资产整体纳入产品？
适合读者： 准备在商业动画产品中使用 UniMate 的工程负责人，计划依赖 MIT 代码、Truebones 动作和 Hugging Face 数据，并需要确认再分发与商业许可边界

不适合直接整体纳入商业产品；MIT 只说明项目代码的许可状态，不能覆盖训练数据、动作包和第三方资产。

  • 项目数据标注为 MIT License，但 README 特别说明 Truebones ZOO 动作是商业资产包，不允许随项目重新分发。
  • 使用 Truebones 动作必须直接向 Truebones 购买，并按原始 Truebone_Z-OO 文件夹布局提供给流水线。
  • UniML3D 的原始来源包括 Mixamo、Objaverse-XL Rigged Animated 和 Truebones，README 没有把所有来源资产声明为同一种商业许可。
  • 因此代码可否使用、训练数据能否商用、生成结果能否再分发，是三个不同的许可问题，README 没有给出统一商业授权。
  • 项目核心数据：license — MIT License
  • Dataset & Data Processing：Truebones ZOO animal motions themselves are a commercial asset pack whose license does not permit redistribution
  • Dataset & Data Processing：please purchase the pack directly from Truebones
  • README：raw source assets are available under Mixamo-Animations-Characters、Objaverse-XL-Rigged-Animated 和 Truebones-ZOO-Annotations
材料未说明：README 未说明 Mixamo 和 Objaverse-XL Rigged Animated 各自的商业使用、再分发及生成结果许可边界。；README 未说明生成的 NPY、GLB、FBX 和 MP4 是否继承任何来源资产限制。
适合，README 已提供对应的批量、复现、显存和 checkpoint 控制参数。 我需要在 GPU 上批量生成多个文本动作，每个测试用例要保留 3 个随机样本，并且必须固定 seed、限制 batch_size、指定 checkpoint；UniMate 的推理接口是否够用？
适合读者： 维护 GPU 推理脚本的 Python 工程师，需要批量生成多个文本动作样本，并通过 seed、batch_size 和 checkpoint 控制复现与显存

适合，因为命令行接口直接覆盖了你列出的批量生成和实验控制需求。

  • --num_repetitions 控制每个 test case 生成的样本数，可以设为 3。
  • --seed 可固定采样噪声，--model_path 可指定具体 checkpoint，避免默认使用最新 step。
  • --batch_size 控制分块推理并限制 GPU memory；README 特别说明它不会减少所有案例的总计算量。
  • 输出会同时保存每个 repetition 的 .npy、可选 MP4、T-pose 和 captions.json，便于把提示词与结果对应起来。
  • Inference flags：--num_repetitions、--batch_size、--seed、--model_path
  • Inference：batch_size — Per-chunk inference batch; caps GPU memory regardless of how many cases there are
  • Each run writes：motions/*.npy、animations/*.mp4、_tpos.png、captions.json
python -m unimate.inference.sample \
    --exp_dir outputs/uniml3d_60frames_graph_adaln \
    --test_cases_json test_cases.json \
    --num_repetitions 3
材料未说明：README 未给出不同 GPU 型号、序列长度和 batch_size 对应的显存表。；README 未说明相同 seed 在不同 CUDA、PyTorch 或 checkpoint 版本下是否完全确定性。
不适合直接投入使用，因为新 OOD 骨架的官方预处理流程尚未完成，且项目明确承认许多骨架仍会失败。 我的目标资产是数据集之外的新型机器人或幻想生物骨架，我只有绑定网格和 T-pose，希望直接输入自然语言生成动作；在当前版本中这是否适合？
适合读者： 想把 UniMate 用于新型 OOD 机器人或幻想生物绑定资产的技术美术，资产不属于现有数据集，且项目仍处于 Python 研究环境而非独立图形化工具

不适合直接投入使用，主要障碍不是文本输入，而是新骨架必须先转换为项目要求的规范化特征。

  • README 的 TODO 明确表示，面向新 out-of-distribution rigs 的官方 preprocessing pipeline 尚待发布。
  • 推理要求训练运行目录中的 dataset/features// 存在，因为 T-pose 和 topology conditioning 从该目录加载。
  • object_type 必须存在于数据集；一个全新的机器人或幻想生物类型不能仅靠 JSON 中增加名称就获得支持。
  • 项目还明确说明许多 motion 和 skeleton 仍会失败，因此当前版本更适合熟悉数据处理流水线的研究原型，而不是即插即用资产工具。
  • 顶部 TODO：We will release an official preprocessing pipeline for new (out-of-distribution) rigs
  • Inference：The target skeleton — T-pose and topology conditioning — is taken from the dataset
  • Inference：the dataset/features// directory the model was trained on must be present
  • Test cases：object_type must exist in the dataset
  • Note：many motions and skeletons still fail
conda create -n unimate python=3.10 -y
材料未说明：README 未说明 OOD rig 预处理何时发布、输入文件格式是什么，以及是否支持任意关节命名。；README 未给出机器人关节限位、物理约束、足端接触或碰撞处理能力。
适合，但更适合作为研究验证和原型基线，而不是生产级动画系统。 我已经有 Mixamo、Objaverse-XL Rigged Animated 和 Truebones 资产，并且接受 Python 3.10、Conda 和 GPU 推理；UniMate 是否适合用来验证不为每个骨架重新训练的文本到动作方案？
适合读者： 正在用 Mixamo、Objaverse-XL Rigged Animated 和 Truebones 资产验证跨骨架动作生成的研究人员，使用 Python 3.10、Conda 和 GPU 环境，不希望为每个骨架单独训练模型

适合，因为项目明确面向多种骨架拓扑，并宣称无需按骨架重新训练或在测试时优化。

  • UniML3D 包含 13,006 条带文本的动作序列，覆盖二足、四足、鸟类、海洋生物、昆虫、蛇形生物和关节式刚体对象。
  • 推理同时使用文本、T-pose 和骨架拓扑条件，目标骨架来自训练数据的特征目录。
  • 项目发布了训练和推理代码，并提供 Hugging Face preview checkpoints，便于复现实验。
  • 但 README 明确说这是“early step”，许多动作和骨架仍会失败，因此不能把跨骨架能力理解为稳定的通用保证。
  • Dataset & Data Processing：13,006 text-paired motion sequences；覆盖 bipedal、quadrupedal、avian、marine、insectoid、serpentine 和 articulated rigid objects
  • Inference：no per-skeleton retraining and no test-time optimization
  • News：The training and inference code is released；Preview checkpoints are released
  • Note：UniMate is an early step toward text-to-animation for any skeleton, and many motions and skeletons still fail
conda create -n unimate python=3.10 -y
材料未说明：README 未给出不同骨架类别上的定量成功率或动作质量基准。；README 未说明新骨架相对训练分布的最大关节数、拓扑复杂度或推理延迟。
视情况，项目能导出 GLB 和 FBX，但不能保证任意绑定资产无需预处理就能成功驱动。 我使用 Objaverse-XL Rigged Animated 的绑定资产，交付要求是 GLB 和 FBX，而不是只拿到 NPY 特征；UniMate 能否直接满足我的资产驱动流程？
适合读者： 负责把生成动作接入已有 GLB/FBX 资产的技术美术，资产来自 Objaverse-XL Rigged Animated，团队希望直接得到可驱动原始网格的动画文件

视情况，因为 UniMate 的输出链路支持 GLB/FBX，但生成阶段首先产出的是运动特征，不是已经绑定好的网格动画。

  • 推理结果写入 motions/*.npy，每个文件包含 (T, J, 12) 的运动特征。
  • README 指定要把 .npy 交给数据流水线第 5 阶段，才能导出 animated GLB + FBX。
  • 默认骨架从 dataset/features//cond.npy 读取，因此资产的 T-pose、拓扑、关节数量和顺序必须与条件骨架匹配。
  • 新的 OOD rig 预处理流程仍标记为 TODO，README 也没有承诺任意第三方绑定资产可直接兼容。
  • Inference：Each run writes motions/-rep_-.npy；Generated motion features (T, J, 12)
  • Driving a rigged mesh：hand the .npy files to stage 5 of the data pipeline, which exports an animated GLB + FBX
  • Driving a rigged mesh：reads the rig from dataset/features//cond.npy by default
  • README 顶部 TODO：release an official preprocessing pipeline for new (out-of-distribution) rigs
bash scripts/run_animate_motion.sh objaverse \
    outputs/uniml3d_60frames_graph_adaln/samples/motions/Dog-walk-rep_0-0.npy \
    outputs/animated
材料未说明：README 未说明 Objaverse 之外的 FBX/GLB 绑定规范、关节命名转换规则和自动重定向能力。；README 未给出导出失败时的错误恢复或资产修复流程。
适合，README 明确把补间和文本引导的局部编辑作为同一模型的无额外训练应用。 我已经能运行 UniMate 的已发布 checkpoint，希望固定首尾帧或部分关节，再用新文本编辑其余动作，而且不额外训练；这个项目是否支持？
适合读者： 研究动作补间和局部编辑的生成模型开发者，使用项目已发布 checkpoint，不想为 motion in-betweening 或 text-guided motion editing 额外训练模型

适合，因为项目将这些任务实现为 replacement-style sampling，而不是重新训练一个编辑模型。

  • README 说明同一个已训练模型还支持 motion in-betweening、text-guided motion editing 和 motion expansion。
  • 采样时可把已知运动信号的一部分固定住，flow ODE 只对剩余部分去噪，因此约束会在每一步保持。
  • 补间适合固定首尾或指定关键帧；局部编辑则固定指定关节的原始运动，并按新文本生成其余部分。
  • 这仍依赖正确的骨架特征和关节标识；README 的章节摘要没有给出完整参数名或复杂多关键帧示例。
  • Applications：The same trained model does three more tasks with no extra training
  • Applications：replacement-style sampling；the constraint holds exactly rather than being encouraged by a loss
  • 项目洞察：支持 motion in-betweening、text-guided motion editing 和 motion expansion
材料未说明：所提供的 README 片段未包含 in-betweening 和 editing 的完整命令、参数格式及输入文件布局。；README 未说明同时固定多少关键帧或关节后，生成质量和可编辑自由度如何变化。

✨ 核心亮点

  • UniML3D含13,006条文本配对动作序列
  • UniMate无需逐骨骼重训或测试时优化
  • 支持双足、四足、鸟类和蛇形骨骼
  • 提供HuggingFace预训练checkpoint与推理代码

🔧 工程化

  • 用python -m unimate.inference.sample按文本生成骨骼动作
  • 通过run_animate_motion.sh导出动画GLB与FBX
  • 支持动作补间与文本引导的关节编辑

⚠️ 风险

  • README明确说明许多动作和骨骼仍会失败
  • Truebones动物动作包禁止再分发且需单独购买
  • 新OOD骨骼预处理pipeline仍标记为TODO
  • 推理要求训练数据对应的dataset/features目录存在

👥 适合谁？

  • 需要Python 3.10和Conda环境的动画研究开发者
  • 处理Mixamo、Objaverse或Truebones资产的团队
  • 需要多种拓扑共享模型的文本动画实验者