VRM-Addon-for-Blender 动画功能全指南：VRMA 文件的导入与导出

• 图形学
• 数字人

导读

VRM Animation（.vrma）是 VRM 规范体系中用于承载角色动作的动画文件格式，它独立于模型文件本身，允许你将一段动画从一个人物模型迁移到另一个人物模型上。本文以 VRM-Addon-for-Blender 官方动画文档为核心，完整讲解在 Blender 中导出与导入 VRM Animation 的完整流程：从前置条件（VRM 1.0 骨架）、被导出的动画数据范围，到菜单操作、前置检查，以及底层导出器与导入器在 vrm_animation_exporter.py 与 vrm_animation_importer.py 中的实现细节。读完本文，你将掌握 VRMA 文件在 Blender 中的端到端工作流，并理解其内部 GLB/glTF 结构、坐标系换算与关键帧重建原理。

VRM Animation 是什么

VRM Animation（.vrma）是由 VRMC_vrm_animation 1.0 扩展定义的动画格式，基于 glTF 2.0 / GLB 二进制容器承载。它只描述"动作"，不包含网格与材质，因此可以脱离具体模型分发，并在不同 VRM 模型之间复用。VRM-Addon-for-Blender 将其作为独立的导入/导出入口提供，与模型文件（.vrm）相互独立：

• 通过File→Export→VRM Animation (.vrma)导出（对应 EXPORT_SCENE_OT_vrma 操作符）；
• 通过File→Import→VRM Animation (.vrma)导入（对应 IMPORT_SCENE_OT_vrma 操作符）。

这两类操作还分别提供了前置检查操作符 WM_OT_vrma_export_prerequisite 与 WM_OT_vrma_import_prerequisite，在正式打开文件对话框前先校验目标骨架是否满足 VRM 1.0 导出/导入条件。

导出 VRM Animation 文件

前置条件：必须使用 VRM 1.0 骨架

官方文档明确指出，VRM Animation 的导出需要 VRM 1.0 的 Armature（骨架）。这一点在导出前置检查WM_OT_vrma_export_prerequisite.detect_errors中体现为两条硬性校验（见 export_scene.py）：

1. 目标 Armature 必须存在且为 Armature 类型；
2. 该 Armature 的 VRM 扩展版本必须为 VRM 1.0——如果检查到扩展不是 VRM 1.0，会直接报错 "Please set the version of VRM to 1.0"（请将 VRM 版本设置为 1.0）；
3. 在 VRM 1.0 的前提下，Humanoid 骨骼必须完成正确指定，否则报错 "Please assign required human bones"（请指定必需的 Humanoid 骨骼）。

检查通过后才会弹出保存对话框；检查不通过时，操作会改为调用前置检查对话框，列出所有错误并提示你逐个修正。

导出内容与数据范围

官方文档列出了 .vrma 文件实际包含的动画数据，共三类：

• Humanoid 骨骼的旋转值（rotation）：VRM Humanoid 体系内各骨骼的旋转动画；
• Humanoid Hips 骨骼的移动值（translation）：Hips 骨骼（人体重心）的位移动画；
• Expression 的预览值（preview value）：面部表情 BlendShape 的预览数值（注意：Look At 注视方向数值目前尚不支持导出）。

配套的英文 UI 文档 docs/en-us/ui/export_scene.vrma/index.md 对导出内容做了更精确的表述：满足以下条件的动画会被导出为 VRMA 文件——分配给 VRM Humanoid 骨骼的骨骼旋转值、分配给 Hips 骨骼的平移值、VRM Expression 的预览值，以及 VRM Look At 的 Preview Target 中指定对象的平移值。也就是说，Look At 目标物体的位移动画（而非 Look At 的朝向角度本身）也会被写入文件。

源码级导出实现

导出入口 VrmAnimationExporter.execute 的执行流程如下：

1. 在导出前自动将骨架切换到 T-Pose（调用setup_humanoid_t_pose），并保存当前工作区状态（save_workspace(context, armature, mode="POSE")），导出结束后恢复；
2. 调用_export_vrm_animation生成完整的 VRMA 二进制内容，最后通过path.write_bytes(output_bytes)落盘。

核心函数_export_vrm_animation（vrm_animation_exporter.py）内部的构建过程可以分为四条数据生产线：

• 骨骼节点与坐标系换算：_create_node_dicts从 VRM 1.0 的 Humanoid 骨骼规格（HumanBoneSpecifications）出发，以 Hips 为根递归生成 glTF 节点树；每块骨骼的平移与旋转会做 Blender（右手、Z-up）到 glTF（右手、Y-up）的坐标系换算——平移从(x, y, z)变为(x, z, -y)，四元数从(x, y, z, w)变为(x, z, -y, w)；
• Humanoid 骨骼旋转动画：_create_node_animation逐帧调用armature.pose.apply_pose_from_action(action, evaluation_time=frame)求值动作，随后递归收集每个 Humanoid 骨骼相对父骨骼的旋转四元数（_set_frame_rotations）。如果某块骨骼在整个时间范围内旋转角都近似为零（abs(quaternion.angle) < float_info.epsilon），该骨骼的 rotation 通道会被跳过不导出，以减小文件体积；
• Hips 位移动画：同一函数中逐帧记录 Hips 骨骼的平移向量，若所有帧的位移长度平方都小于浮点精度阈值，则同样跳过；
• Expression 预览动画：_create_expression_animation从 Armature data 的 Action 中读取 Expression 的preview曲线，将每个 Expression 映射为一个独立的动画节点，并把预览值钳制在[0, 1]区间后写入translation通道。所有 Expression 节点会同时挂入场景节点列表（scene_node_indices），保证导入方能够定位到它们。

最终，vrma_dict会被组装为标准的 GLB 结构：asset（含生成器标识 "VRM Add-on for Blender v版本号"）、nodes、scenes、animations、buffers/bufferViews/accessors，以及extensionsUsed: ["VRMC_vrm_animation"]与对应的extensions扩展块，随后由pack_glb打包为 .vrma 二进制文件。

值得注意的是，时间轴采样使用frame_to_timestamp_factor = fps_base / fps将帧号换算为秒级时间戳，因此动画时长严格依赖场景的渲染帧率设置（context.scene.render.fps/fps_base）。在默认 24 fps 下，1 秒动画对应 24 帧。

实际操作步骤

在 Blender 中导出 VRMA 的最小流程（对应原文档中的 15 张步骤截图）为：

1. 在场景中放置一个已完成 VRM 1.0 设置、Humanoid 骨骼指定正确的模型 Armature；
2. 选中该 Armature，进入 Pose 模式，为需要导出的骨骼旋转、Hips 位移与 Expression 预览值制作关键帧动画；
3. 执行File→Export→VRM Animation (.vrma)；
4. 在前置检查对话框中确认目标 Armature（默认取当前激活的 Armature），核对错误列表为空；
5. 选择保存路径，确认文件扩展名为.vrma，点击Save完成导出。

导出的 .vrma 文件即可被支持 VRMC_vrm_animation 的应用或引擎播放，或在 Blender 中再次导入复用。

导入 VRM Animation 文件

导入行为与自动建模

官方文档及配套 UI 文档 docs/en-us/ui/import_scene.vrma/index.md 描述了导入流程：通过File→Import→VRM Animation (.vrma)打开导入对话框，选择一个 VRMA 文件并点击Open后：

• 动画会应用到当前场景中的 VRM 1.0 模型上；
• 如果当前场景中没有 VRM 1.0 模型，插件会自动生成一个最小化模型（minimal model）来承载动画。

从源码看，这一"自动生成"逻辑位于 IMPORT_SCENE_OT_vrma.execute：当找不到目标 Armature 时，会调用ops.icyp.make_basic_armature()创建一个基础 Armature，并自动将其扩展版本设置为 VRM 1.0（ext.spec_version = ext.SPEC_VERSION_VRM1），然后继续执行导入。与导出对称，导入前置检查同样要求：目标 Armature 必须是 VRM 1.0，且 Humanoid 骨骼已正确指定（import_scene.py）。

源码级导入实现

导入入口 VrmAnimationImporter.execute 的核心步骤：

1. 与导出一致，先切 T-Pose 并保存工作区，导入结束后恢复 Look At 预览开关状态；
2. _import_vrm_animation完成主要工作，返回{"FINISHED"}。

_import_vrm_animation（vrm_animation_importer.py）是导入端的中枢，其处理链路包括：

• GLB 解析：通过parse_glb读取 .vrma 二进制，得到 JSON 字典与 buffer 数据；
• 结构校验：依次校验nodes、animations.channels、animations.samplers、extensions.VRMC_vrm_animation.humanoid.humanBones等字段是否存在且类型正确，缺失即返回{"CANCELLED"}；Hips 节点索引必须在节点数组范围内；
• 节点映射：解析humanBones与expressions（preset/custom）映射表，建立"节点索引 → Humanoid 骨骼名/Expression 名"的对应关系；通过_find_root_node_index沿 children 链向上回溯找到整棵节点树的根节点；
• 静止姿势重建：NodeRestPoseTree.build将 glTF 节点树还原为 Blender 坐标系下的静止姿势矩阵（把平移(x, z, -y)与四元数(w, x, -z, y)换算回 Blender 约定）；
• 采样数据读取：利用read_accessor_as_animation_sampler_input等工具从 accessor/bufferView/buffer 中读回各通道的时间戳、平移与旋转关键帧数据，并按时间戳排序；
• Action 与关键帧写入：为 Humanoid 骨骼创建名为 "Humanoid" 的 Action，为 Expression 创建名为 "Expressions" 的 Action；在时间范围内逐帧插值（平移用线性插值lerp、旋转用球面插值slerp），调用_assign_humanoid_keyframe、_assign_expression_keyframe、_assign_look_at_keyframe为骨骼、Expression 预览值和 Look At 目标物体写入关键帧；
• Hips 特殊处理：若文件中包含 Hips 位移动画，导入结束后会进入 Edit 模式，将 Hips 骨骼与其父骨骼的use_connect（连接）断开——这是为了让 Hips 的位移动画能够被正确反映（连接状态下的骨骼移动会被父骨骼约束吸收），源码注释明确说明此步必须放在最后执行，因为会改变骨骼状态。

导入时的帧号换算同样依赖场景帧率：frame_count = timestamp * fps / fps_base，即 VRMA 中的秒级时间戳按当前场景帧率映射为 Blender 帧号。

导入后的产物

导入完成后，Blender 场景中将出现：

• 目标 Armature（或自动生成的最小模型）上带有 "Humanoid" Action 的骨骼旋转/位移动画；
• Armature data 上带有 "Expressions" Action 的 Expression 预览动画（自动关联到 VRM Expression 的preview属性）；
• 若文件包含lookAt扩展且该节点存在位移动画，会新建一个名为 "LookAtTarget" 的空物体（Empty）作为 Look At 的 Preview Target（显示尺寸 0.125），自动开启 Look At 预览（look_at.enable_preview = True）并写入其位置关键帧。

验证与测试

仓库在 tests/importer/test_vrm_animation_importer.py 中提供了完整的导入测试套件，可用于验证上述行为：

• 测试通过pack_glb手工构造包含 rotation/translation 通道的最小 VRMA 文件（write_animation），再调用VrmAnimationImporter.execute导入到make_basic_armature生成的 VRM 1.0 骨架上；
• test_world_rotation_with_object_rotation验证了：当 Armature 物体自身带有旋转、甚至作为子物体被父物体旋转时，导入后的每帧骨骼世界旋转仍与参照模型一致，且 Armature 的matrix_world与静止姿势（matrix_local）在导入前后保持不变——这印证了导入器会妥善处理物体变换与静止姿势分离；
• 测试还覆盖了 Hips 位移动画导入后自动断开use_connect的行为（"Disconnecting hips enters edit mode"）。

在基准测试目录 benchmarks/src/io_scene_vrm_benchmarks/vrma_import_benchmark_test.py 中，还可以看到通过ops.import_scene.vrma(filepath=...)批量导入内置benchmark.vrma文件的性能测试用例，其中包含多次连续导入以衡量重复导入的耗时表现。

命令行 / 脚本调用

除菜单操作外，VRMA 的导入导出也支持通过 Python 脚本直接调用（对应自动生成的类型化包装 common/ops/export_scene.py 与 common/ops/import_scene.py）：

# 导出：导出 VRM 1.0 骨架的动画 bpy.ops.export_scene.vrma( filepath="/path/to/output.vrma", armature_object_name="ArmatureName", ) # 导入：将动画应用到当前场景中的 VRM 1.0 模型 bpy.ops.import_scene.vrma( filepath="/path/to/input.vrma", armature_object_name="ArmatureName", )

两个操作符共有的参数：

导入时若armature_object_name留空且场景中找不到 VRM 1.0 骨架，会自动生成一个最小 VRM 1.0 模型来承接动画，与菜单流程行为一致。

总结

围绕 VRM Animation 的导入导出，VRM-Addon-for-Blender 提供了完整且自洽的实现闭环：

• 导出端：以 VRM 1.0 骨架为前提，将 Humanoid 骨骼旋转、Hips 位移、Expression 预览值（以及 Look At 目标物体位移）采样为 glTF 动画通道，打包为 VRMC_vrm_animation 1.0 扩展的 GLB 文件；
• 导入端：解析 GLB 后重建节点树与静止姿势，通过逐帧插值把动画写回 Blender 的 Action 与关键帧，并针对 Hips 连接、物体变换、场景帧率等细节做了专门处理；
• 验证端：仓库提供独立的导入测试与基准测试，覆盖坐标系换算、物体旋转/父级变换、Hips 断开连接等边界场景。

需要特别留意的限制是：Look At 注视方向的数值本身目前尚未支持导出（仅支持导出 Look At 目标物体的位移动画），Humanoid 左右眼骨骼的旋转也不会被导出。在你将 VRMA 动画迁移到不同模型时，请确保目标模型同样是 VRM 1.0 且 Humanoid 骨骼指定完整，以保证动画能正确映射。

• 图形学
• 数字人