创建 3D 动画文件 - ComfyUI Built-in Node Documentation

此节点根据姿态数据构建一个可直接保存的 3D 动画文件。您可以导出多种视觉样式的动画 GLB —— 全身网格、仅关节预览、OpenPose 骨架或 SCAIL 胶囊绑定 —— 也可以改为保存 BVH 动作捕捉片段。

此节点根据姿态数据构建一个可直接保存的 3D 动画文件。您可以导出多种视觉样式的动画 GLB —— 全身网格、仅关节预览、OpenPose 骨架或 SCAIL 胶囊绑定 —— 也可以改为保存 BVH 动作捕捉片段。输出可接入文件保存节点（如 Save 3D Model）以将文件写入磁盘。

输入

参数	描述	数据类型	必填	范围
`pose_data`	3D 姿态数据。接受 MHR 姿态数据（模型/形状/表情参数、MHR70 关键点、规范颜色、手部顶点遮罩）或 Kimodo 姿态数据（外部 Y 轴朝上的绑定，带有逐帧预测的顶点和相机）。	MHR\_POSE\_DATA / KIMODO\_POSE\_DATA	是	—
`格式`	输出格式，将传入 Save 3D Model 以写入磁盘。'glb' = 动画 GLB（mesh / bones / openpose / scail）。'bvh' = BVH 动作捕捉片段（一个骨架；需要模型）。（默认：glb）	DYNAMIC\_COMBO	是	"glb" "bvh"
`sam3d_body_model`	可选的 SAM3D 身体模型。对于 'bvh'、'body\_mesh' 和 'bones\_only' 格式是必需的，除非姿态数据带有骨架覆盖。	SAM3D\_BODY\_MODEL	否	—
`fps`	动画帧率。（默认：24.0）	FLOAT	是	1.0-240.0
`camera_translation`	将 pred\_cam\_t 烘焙到根骨骼的平移中：'off' = 绑定位置；'centered' = 相对于第 0 帧的增量；'absolute' = 原始值（Z 为相机深度——通常是以米为单位的距离）。（默认：off）	COMBO	是	"off" "centered" "absolute"
`track_index`	轨道选择：-1 = 所有轨道；≥0 = 单条轨道。（默认：-1）	INT	是	-1 到 15

当 format 设置为 "glb" 时，显示这些输入。

参数	描述	数据类型	必填	范围
`mesh_style`	GLB 的视觉样式：'body\_mesh' = 真实 Armature（127 根骨骼、蒙皮、TRS 关键帧、72 个面部变形；需要模型）。'bones\_only' = 在每个关节处使用骨骼形状基元（预览骨架）。'openpose' = 基于关键点的 OpenPose-18 3D 骨架。'scail' = SCAIL 3D 胶囊绑定（开口圆柱体由关节球体齐平封口）。（默认：body\_mesh）	DYNAMIC\_COMBO	是	"body\_mesh" "bones\_only" "openpose" "scail"
`bone_smooth_window`	对每根骨骼的旋转关键帧/关键点轨道应用高斯平滑窗口。0 = 关闭。7-15 可抑制上游 Smooth 未处理的旋转/抖动尖峰。（默认：0）	INT	是	0-51 （步长：2）

当 mesh_style 为 "body\_mesh" 时显示。

参数	描述	数据类型	必填	范围
`bone_vis`	骨骼可视化形状，刚性蒙皮到每个关节。'off' = 不显示骨骼；'octahedrons' = Blender 风格的指向性骨骼。（默认：off）	DYNAMIC\_COMBO	是	"off" "octahedrons"
`bone_vis_radius_m`	当 `bone_vis` = "octahedrons" 时显示。半径（m）（球体半径 / 八面体半宽）。（默认：0.02）	FLOAT	是	0.005-0.5
`bone_vis_color`	当 `bone_vis` = "octahedrons" 时显示。逐骨骼顶点颜色（无光照材质）。'white' = 无，'rainbow\_y' = 从头到脚的 jet 渐变。（默认：rainbow\_y）	COMBO	是	"white" "rainbow\_y"
`shader`	烘焙与 Render 节点着色器匹配的逐顶点颜色（COLOR\_0 + KHR\_materials\_unlit）。'default' = 无颜色。（默认：default）	DYNAMIC\_COMBO	是	"default" "rainbow" "rainbow\_face\_normal" "rainbow\_face\_semantic"
`rainbow_tilt_z`	当 `shader` 为彩虹变体时显示。绕 Z 轴（前向）旋转彩虹 jet 轴。用于区分左右。（默认：-35.0）	FLOAT	是	-90.0 到 90.0
`rainbow_tilt_x`	当 `shader` 为彩虹变体时显示。绕 X 轴（右向）旋转彩虹 jet 轴。用于区分前后。（默认：0.0）	FLOAT	是	-90.0 到 90.0
`person_palette_falloff`	当 `shader` 为彩虹变体时显示。逐人减饱和：每条轨道获得 (1 - falloff^k) 的淡彩混合。（默认：0.6）	FLOAT	是	0.1-1.0

当 mesh_style 为 "bones\_only" 时显示。

参数	描述	数据类型	必填	范围
`bone_vis`	骨骼可视化形状，刚性蒙皮到每个关节。'octahedrons' = Blender 风格的指向性骨骼（关节 → 主要子级）。	DYNAMIC\_COMBO	是	"octahedrons"
`bone_vis_radius_m`	半径（m）（球体半径 / 八面体半宽）。（默认：0.02）	FLOAT	是	0.005-0.5
`bone_vis_color`	逐骨骼顶点颜色（无光照材质）。'white' = 无，'rainbow\_y' = 从头到脚的 jet 渐变。（默认：rainbow\_y）	COMBO	是	"white" "rainbow\_y"

当 mesh_style 为 "openpose" 时显示。

参数	描述	数据类型	必填	范围
`marker_radius_m`	球体半径（m）。（默认：0.010）	FLOAT	是	0.005-0.1
`stick_radius_m`	肢体半宽（m）。自动限制为 bone\_length × 0.1。（默认：0.008）	FLOAT	是	0.002-0.05
`include_hands`	附加 21+21 个 OpenPose 手部关键点（手腕 + 5 根手指 × 4 个关节，基部→指尖），来源于 pred\_keypoints\_3d。（默认：False）	BOOLEAN	是	True / False
`hand_marker_radius_m`	手部球体半径（m）。（默认：0.005）	FLOAT	是	0.001-0.1
`hand_stick_radius_m`	手部肢体半宽（m）。（默认：0.003）	FLOAT	是	0.001-0.05
`face_style`	面部轮廓特征点，从固定头部网格顶点 ID 处的 pred\_vertices 采样（需要 pose\_data 上的 canonical\_colors）。'full' = 全部约 30 个点；'eyes\_mouth' = 仅眼睛 + 外嘴唇。（默认：disabled）	COMBO	是	"disabled" "full" "eyes\_mouth"
`face_marker_radius_m`	面部点半径。0 = 自动 = 0.3 × marker\_radius\_m。（默认：0.0）	FLOAT	是	0.0-0.05

当 mesh_style 为 "scail" 时显示。

参数	描述	数据类型	必填	范围
`stick_radius_m`	圆柱体半径（m）。骨骼是等半径的开口圆柱体；关节球体（自动调整大小以匹配）封住开口端。SCAIL 参考值 = 0.0215 m。（默认：0.022）	FLOAT	是	0.002-0.1
`marker_radius_m`	关节球体半径。0 = 自动 = stick\_radius\_m（齐平封口）。（默认：0.0）	FLOAT	是	0.0-0.1
`material_roughness`	PBR 粗糙度。SCAIL 参考值 = 0.3。1 = 哑光；0 = 铬面。（默认：0.3）	FLOAT	是	0.0-1.0
`include_hands`	为每条轨道附加 21+21 个手部关键点和胶囊棒。（默认：False）	BOOLEAN	是	True / False
`hand_marker_radius_m`	手部球体半径（m）。（默认：0.005）	FLOAT	是	0.001-0.05
`hand_stick_radius_m`	手部圆柱体半径（m）。（默认：0.003）	FLOAT	是	0.001-0.05
`face_style`	面部轮廓特征点，从 pred\_vertices 采样（需要 pose\_data 上的 canonical\_colors）。'full' = 全部约 30 个点；'eyes\_mouth' = 仅眼睛 + 外嘴唇。（默认：disabled）	COMBO	是	"disabled" "full" "eyes\_mouth"

当 format 设置为 "bvh" 时显示。

参数	描述	数据类型	必填	范围
`units`	BVH OFFSET/位置单位。'cm' 是动作捕捉标准。（默认：cm）	COMBO	是	"cm" "m"

注意：

bvh 格式以及 body_mesh 和 bones_only 网格样式需要 sam3d_body_model 输入，除非 pose_data 自身带有骨架覆盖（例如来自 KimodoSample 节点的 _skeleton_override 字典）。如果两者均不可用，节点将引发错误。openpose 和 scail 样式与绑定无关，可直接基于关键点工作，无需身体模型。
在 bvh 格式中，输出包含单个骨架。当 track_index 为 -1（所有轨道）时，使用第一条轨道。
face_style 的 full 和 eyes_mouth 选项要求姿态数据带有 canonical_colors；当姿态数据与身体模型一同来自 MHR 流程时，该数据即存在。
bone_smooth_window 在 0 到 51 之间以 2 为步长递增。

输出名称	描述	数据类型
`model_3d`	生成的动画文件：动画 GLB 或 BVH 动作捕捉片段，可直接通过 Save 3D Model 等节点保存到磁盘。	3D\_FILE

本文档由 AI 生成。如果您发现任何错误或有改进建议，欢迎贡献！在 GitHub 上编辑

Source fingerprint (SHA-256): f3672f0749c4f9affcc92da98198c5b142f6fcd9f5e317ab43dd7e53533c0fa3