BuildPoseFile - ComfyUI Built-in Node Documentation

此节点根据姿态数据构建一个可直接保存的 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

GLB 输入

当 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, step 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”

OpenPose 输入

当 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

SCAIL 输入

当 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”

BVH 输入

当 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

​输入

​通用输入

​GLB 输入

​身体网格输入

​仅骨骼输入

​OpenPose 输入

​SCAIL 输入

​BVH 输入

​输出

输入