> ## 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

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