Friedrich-M/UniMate

UniMate – 一个统一模型，为多样化骨骼生成动画

它是什么

一个研究级深度学习模型，根据文本提示为任何绑定骨骼（人类、动物、机器人，甚至抽象对象）生成 3D 关节运动。
在 UniML3D 数据集上训练 – 13.8k 个文本配对运动片段，涵盖 7.4k 个多种拓扑结构的骨骼（双足、四足、鸟类、海洋、昆虫、蛇形、刚体绑定）。

为什么重要

现有的文本到动画系统仅限于单一角色拓扑。UniMate 学习关节的规范表示，可以应用于未见过的绑定，无需任何逐骨骼微调或测试时优化。
模型实时工作，适用于交互式应用（游戏、VR、机器人模拟）。

关键组件

组件	功能
模型架构	提供两种注意力变体：`graph_adaln`（时空图感知注意力）和 `full_cross_attn`（关节-时间标记上的标准 Transformer）。两者都可以通过冻结的 FLAN-T5 编码器进行文本条件化。
训练目标	流匹配扩散：网络预测噪声和目标运动之间线性插值的速度。损失结合了掩码 L2、测地旋转项和速度平滑项。
数据流程	`data_process/` 脚本将原始资产（Mixamo、Objaverse-XL、Truebones）转换为统一的 UniML3D 格式：导出、渲染、字幕、关节标注、特征提取。`rig_preprocess` 工具允许您将任何 GLB/FBX/GLTF 绑定导入相同格式，并提供 LLM 生成的关节标签以供审查。
推理	`unimate.inference.sample` 在绑定和提示上驱动训练好的检查点，输出动画 GLB/FBX 文件。支持批量采样、无分类器引导（`--cfg_scale`）和每个提示的多次重复。
工具	预计算文本嵌入、恢复训练、可视化调试渲染，以及一个简单脚本，用生成的运动驱动网格。

开始使用

创建环境

conda create -n unimate python=3.10 -y
conda activate unimate
pip install "setuptools<81"
pip install -r requirements.txt --no-build-isolation

下载数据集（约 88 GB）和发布的检查点：

hf download Linzhan/UniML3D --repo-type dataset --local-dir dataset
hf download Linzhan/UniMate --repo-type model --local-dir outputs \
    --include "unimate_uniml3d_f60_v3/*.json" \
    --include "unimate_uniml3d_f60_v3/*.npy" \
    --include "unimate_uniml3d_f60_v3/checkpoints/checkpoint_step_150000.pt"

运行快速演示（为几个预处理资产生成动画）：

python -m unimate.inference.sample \
    --exp_dir outputs/unimate_uniml3d_f60_v3 \
    --test_cases_json assets/examples/examples.json \
    --num_repetitions 3 \
    --output_dir outputs/samples/examples
SKIP_INVALID=1 bash scripts/run_animate_motion.sh outputs/samples/examples

您将获得诸如 Garfield 模型、Gundam、鲨鱼等对象的动画 GLB/FBX 文件。

训练您自己的模型

配置文件位于 configs/。它们编码数据集选择、帧长度、注意力类型和字幕条件（例如，uniml3d_60frames_graph_adaln.json）。

使用 🤗 Accelerate 启动：

accelerate launch -m unimate.training.train --config configs/uniml3d_60frames_graph_adaln.json

多 GPU：添加 --num_processes N。
流程处理跨非常不均匀骨骼计数的平衡采样、关节轴填充和数据增强（关节添加、叶移除、链池化、骨骼长度扰动）。
检查点、日志和可视化调试渲染写入 outputs/<experiment>/。

使用您自己的绑定（"自带绑定"）

将 GLB/FBX/GLTF 文件放在文件夹中。
运行预处理工具：
```
python -m data_process.rig_preprocess.process <path_to_folder>
```
该工具使用 LLM 标记关节，向您显示关节名称和朝向的审查 UI，并生成推理脚本期望的规范资产目录。
使用相同的 sample 命令进行动画，将 --asset 指向新创建的目录。

应用

游戏/VR 内容创作 – 无需手动编写动画即可快速为角色或道具生成多样化运动片段。
机器人模拟 – 为具有任意运动树的机器人生成合理的运动或操作序列。
电影与 VFX 原型设计 – 为奇幻生物或机械绑定探索运动想法。
该仓库还演示了使用相同模型的三个零样本下游任务（例如，运动编辑、风格迁移），但细节在论文中。

链接与资源

项目页面与论文：https://linzhanmou.com/unimate/ (arXiv: 2609.05415)
交互式演示：https://linzhanmou.com/unimate/interactive.html
数据集：https://huggingface.co/datasets/Linzhan/UniML3D
模型检查点：https://huggingface.co/Linzhan/UniMate
GitHub 仓库：https://github.com/Friedrich-M/UniMate (本 README)

TL;DR

UniMate 是一个开源的基于扩散的文本到动画模型，适用于任何绑定好的 3D 骨骼。它附带一个大型多拓扑数据集、完整训练代码、自定义资产预处理流程以及现成的推理脚本。非常适合需要通用、实时运动生成器的研究人员和开发人员。