BuildPoseFile - ComfyUI Built-in Node Documentation

This node builds a ready-to-save 3D animation file from pose data. You can export an animated GLB in several visual styles — a full body mesh, joints-only preview, OpenPose skeleton, or SCAIL capsule rig — or save a BVH motion-capture clip instead. The output plugs into a file-saving node such as Save 3D Model to write the file to disk.

Inputs

Common Inputs

Parameter	Description	Data Type	Required	Range
`pose_data`	3D pose data. Accepts MHR pose data (model/shape/expression parameters, MHR70 keypoints, canonical colors, hand vertex mask) or Kimodo pose data (external Y-up rig with per-frame predicted vertices and camera).	MHR_POSE_DATA / KIMODO_POSE_DATA	Yes	—
`format`	Output format, both fed to Save 3D Model to write to disk. ‘glb’ = animated GLB (mesh / bones / openpose / scail). ‘bvh’ = BVH mocap clip (one skeleton; needs the model). (default: glb)	DYNAMIC_COMBO	Yes	”glb" "bvh”
`sam3d_body_model`	Optional SAM3D body model. Required for the ‘bvh’, ‘body_mesh’, and ‘bones_only’ formats unless the pose data carries a skeleton override.	SAM3D_BODY_MODEL	No	—
`fps`	Animation frame rate. (default: 24.0)	FLOAT	Yes	1.0-240.0
`camera_translation`	Bake pred_cam_t into the root’s translation: ‘off’ = bind position; ‘centered’ = delta from frame 0; ‘absolute’ = raw (Z is camera depth — usually meters away). (default: off)	COMBO	Yes	”off" "centered" "absolute”
`track_index`	Track selection: -1 = all tracks; ≥0 = single track. (default: -1)	INT	Yes	-1 to 15

GLB Inputs

These inputs appear when format is set to “glb”.

Parameter	Description	Data Type	Required	Range
`mesh_style`	Visual style of the GLB: ‘body_mesh’ = real Armature (127 bones, skinning, TRS keyframes, 72 face morphs; needs model). ‘bones_only’ = bone-shape primitives at each joint (preview armature). ‘openpose’ = OpenPose-18 3D skeleton from keypoints. ‘scail’ = SCAIL 3D capsule rig (open cylinders capped flush by joint spheres). (default: body_mesh)	DYNAMIC_COMBO	Yes	”body_mesh" "bones_only" "openpose" "scail”
`bone_smooth_window`	Gaussian smoothing window on per-bone rotation keyframes / keypoint tracks. 0 = off. 7-15 calms spins/jitter where upstream Smooth misses spikes. (default: 0)	INT	Yes	0-51, step 2

Body Mesh Inputs

Appear when mesh_style is “body_mesh”.

Parameter	Description	Data Type	Required	Range
`bone_vis`	Bone vis shape, rigidly skinned to each joint. ‘off’ = no bone visualization; ‘octahedrons’ = Blender-style directional bones. (default: off)	DYNAMIC_COMBO	Yes	”off" "octahedrons”
`bone_vis_radius_m`	Appears when `bone_vis` = “octahedrons”. Radius in m (sphere radius / octahedron half-width). (default: 0.02)	FLOAT	Yes	0.005-0.5
`bone_vis_color`	Appears when `bone_vis` = “octahedrons”. Per-bone vertex colors (unlit material). ‘white’ = none, ‘rainbow_y’ = head-to-toe jet. (default: rainbow_y)	COMBO	Yes	”white" "rainbow_y”
`shader`	Bake per-vertex colors matching the Render node’s shaders (COLOR_0 + KHR_materials_unlit). ‘default’ = no colors. (default: default)	DYNAMIC_COMBO	Yes	”default" "rainbow" "rainbow_face_normal" "rainbow_face_semantic”
`rainbow_tilt_z`	Appears when `shader` is a rainbow variant. Rotate rainbow jet axis around Z (forward). Differentiates left/right. (default: -35.0)	FLOAT	Yes	-90.0 to 90.0
`rainbow_tilt_x`	Appears when `shader` is a rainbow variant. Rotate rainbow jet axis around X (right). Differentiates front/back. (default: 0.0)	FLOAT	Yes	-90.0 to 90.0
`person_palette_falloff`	Appears when `shader` is a rainbow variant. Per-person desaturation: each track gets (1 - falloff^k) pastel mix. (default: 0.6)	FLOAT	Yes	0.1-1.0

Bones Only Inputs

Appear when mesh_style is “bones_only”.

Parameter	Description	Data Type	Required	Range
`bone_vis`	Bone vis shape, rigidly skinned to each joint. ‘octahedrons’ = Blender-style directional bones (joint → primary child).	DYNAMIC_COMBO	Yes	”octahedrons”
`bone_vis_radius_m`	Radius in m (sphere radius / octahedron half-width). (default: 0.02)	FLOAT	Yes	0.005-0.5
`bone_vis_color`	Per-bone vertex colors (unlit material). ‘white’ = none, ‘rainbow_y’ = head-to-toe jet. (default: rainbow_y)	COMBO	Yes	”white" "rainbow_y”

OpenPose Inputs

Appear when mesh_style is “openpose”.

Parameter	Description	Data Type	Required	Range
`marker_radius_m`	Sphere radius in m. (default: 0.010)	FLOAT	Yes	0.005-0.1
`stick_radius_m`	Limb half-width in m. Auto-clamped to bone_length x 0.1. (default: 0.008)	FLOAT	Yes	0.002-0.05
`include_hands`	Append 21+21 OpenPose hands (wrist + 5 fingers x 4 joints, base→tip) sourced from pred_keypoints_3d. (default: False)	BOOLEAN	Yes	True / False
`hand_marker_radius_m`	Hand sphere radius in m. (default: 0.005)	FLOAT	Yes	0.001-0.1
`hand_stick_radius_m`	Hand limb half-width in m. (default: 0.003)	FLOAT	Yes	0.001-0.05
`face_style`	Face-contour landmarks sampled from pred_vertices at fixed head-mesh vertex IDs (needs canonical_colors on pose_data). ‘full’ = all ~30 points; ‘eyes_mouth’ = eyes + outer lips only. (default: disabled)	COMBO	Yes	”disabled" "full" "eyes_mouth”
`face_marker_radius_m`	Face dot radius. 0 = auto = 0.3 x marker_radius_m. (default: 0.0)	FLOAT	Yes	0.0-0.05

SCAIL Inputs

Appear when mesh_style is “scail”.

Parameter	Description	Data Type	Required	Range
`stick_radius_m`	Cylinder radius in m. Bones are open cylinders at constant radius; joint spheres (auto-sized to match) cap the open ends. SCAIL reference = 0.0215 m. (default: 0.022)	FLOAT	Yes	0.002-0.1
`marker_radius_m`	Joint sphere radius. 0 = auto = stick_radius_m (flush cap). (default: 0.0)	FLOAT	Yes	0.0-0.1
`material_roughness`	PBR roughness. SCAIL ref = 0.3. 1 = matte; 0 = chrome. (default: 0.3)	FLOAT	Yes	0.0-1.0
`include_hands`	Append 21+21 hand keypoints + capsule sticks per track. (default: False)	BOOLEAN	Yes	True / False
`hand_marker_radius_m`	Hand sphere radius in m. (default: 0.005)	FLOAT	Yes	0.001-0.05
`hand_stick_radius_m`	Hand cylinder radius in m. (default: 0.003)	FLOAT	Yes	0.001-0.05
`face_style`	Face-contour landmarks sampled from pred_vertices (needs canonical_colors on pose_data). ‘full’ = all ~30 points; ‘eyes_mouth’ = eyes + outer lips only. (default: disabled)	COMBO	Yes	”disabled" "full" "eyes_mouth”

BVH Inputs

Appear when format is set to “bvh”.

Parameter	Description	Data Type	Required	Range
`units`	BVH OFFSET/position units. ‘cm’ is the mocap standard. (default: cm)	COMBO	Yes	”cm" "m”

Notes:

The bvh format and the body_mesh and bones_only mesh styles require the sam3d_body_model input, unless the pose_data itself carries a skeleton override (a _skeleton_override dict, for example from a KimodoSample node). The node raises an error if neither is available. The openpose and scail styles are rig-independent and work directly from keypoints without the body model.
In bvh format, the output contains a single skeleton. When track_index is -1 (all tracks), the first track is used.
The full and eyes_mouth face_style options require canonical_colors on the pose data, which is present when the pose data comes from the MHR pipeline together with the body model.
bone_smooth_window advances in steps of 2 between 0 and 51.

Outputs

Output Name	Description	Data Type
`model_3d`	The generated animation file: an animated GLB or a BVH mocap clip, ready to be saved to disk with a node such as Save 3D Model.	3D_FILE

This documentation was AI-generated. If you find any errors or have suggestions for improvement, please feel free to contribute! Edit on GitHub

Source fingerprint (SHA-256): f3672f0749c4f9affcc92da98198c5b142f6fcd9f5e317ab43dd7e53533c0fa3

​Inputs

​Common Inputs

​GLB Inputs

​Body Mesh Inputs

​Bones Only Inputs

​OpenPose Inputs

​SCAIL Inputs

​BVH Inputs

​Outputs