> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comfy.org/llms.txt
> Use this file to discover all available pages before exploring further.
# BuildPoseFile - ComfyUI Built-in Node Documentation
> This node builds a ready-to-save 3D animation file from pose data.
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](https://github.com/Comfy-Org/embedded-docs/blob/main/comfyui_embedded_docs/docs/BuildPoseFile/en.md)
***
**Source fingerprint (SHA-256):** `f3672f0749c4f9affcc92da98198c5b142f6fcd9f5e317ab43dd7e53533c0fa3`