> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-matt-router-pricing-pika-and-guard.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# BuildPoseFile - ComfyUI Built-in Node Documentation

> 此节点根据姿态数据构建一个可直接保存的 3D 动画文件。

此节点根据姿态数据构建一个可直接保存的 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"<br />"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"<br />"centered"<br />"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"<br />"bones\_only"<br />"openpose"<br />"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"<br />"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"<br />"rainbow\_y" |
| `shader` | 烘焙与 Render 节点着色器匹配的逐顶点颜色（COLOR\_0 + KHR\_materials\_unlit）。'default' = 无颜色。（默认：default） | DYNAMIC\_COMBO | 是 | "default"<br />"rainbow"<br />"rainbow\_face\_normal"<br />"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"<br />"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"<br />"full"<br />"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"<br />"full"<br />"eyes\_mouth" |

### BVH 输入

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

| 参数 | 描述 | 数据类型 | 必填 | 范围 |
| - | - | - | - | - |
| `units` | BVH OFFSET/位置单位。'cm' 是动作捕捉标准。（默认：cm） | COMBO | 是 | "cm"<br />"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 上编辑](https://github.com/Comfy-Org/embedded-docs/blob/main/comfyui_embedded_docs/docs/BuildPoseFile/zh.md)

***

**Source fingerprint (SHA-256):** `f3672f0749c4f9affcc92da98198c5b142f6fcd9f5e317ab43dd7e53533c0fa3`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.