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

# SAM3DBody_Render - ComfyUI Built-in Node Documentation

> 将 3D 身体姿态数据以可选样式渲染到图像中。

将 3D 身体姿态数据以可选样式渲染到图像中。该节点接受来自 SAM3D 身体追踪器（MHR）或外部 Y-up 骨骼（如 Kimodo）的姿态数据，并可将结果合成到可选背景图像上（未提供时为黑色画布）。可用的渲染样式包括着色 3D 网格、二值剪影、2D 和 3D OpenPose 风格骨架，以及 SCAIL 风格身体胶囊。

## 输入

### 通用输入

| 参数          | 描述                                                                                                                                                              | 数据类型                                  | 是否必需 | 范围                                                                            |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ---- | ----------------------------------------------------------------------------- |
| `渲染风格`      | 渲染模式。'mesh' = 通过相机栅格化的 3D MHR 网格。'silhouette' = 网格的二值掩码。'openpose\_2d' = 平面 2D 骨架。'openpose\_3d' = 以平面着色 3D 模型显示的 OpenPose 骨架。'scail' = SCAIL 3D 胶囊。（默认："mesh"） | DYNAMIC\_COMBO                        | 是    | "mesh"<br />"silhouette"<br />"openpose\_2d"<br />"openpose\_3d"<br />"scail" |
| `pose_data` | MHR 姿态数据，或外部 Y-up 骨骼姿态数据（KimodoSample）。所有渲染样式均适用于在 `_skeleton_override` 中携带 OpenPose 关节点映射的外部骨骼（KimodoSample 即如此）。                                              | MHR\_POSE\_DATA or KIMODO\_POSE\_DATA | 是    | —                                                                             |
| `背景`        | 逐帧背景。省略该输入时使用黑色画布。                                                                                                                                              | IMAGE                                 | 否    | —                                                                             |
| `宽度`        | 输出宽度（像素）。0 = 使用姿态数据的原生 image\_size。若 width/height 仅设置其中一个，则另一个按原始宽高比自动推导。（默认：0）                                                                                 | INT                                   | 否    | 0 至 16384，步长 8                                                                |
| `高度`        | 输出高度（像素）。0 = 使用姿态数据的原生 image\_size。若 width/height 仅设置其中一个，则另一个按原始宽高比自动推导。（默认：0）                                                                                 | INT                                   | 否    | 0 至 16384，步长 8                                                                |
| `相机信息`      | 自由 6DOF 相机覆盖。接入后，姿态将改为通过该相机（position/target/zoom/rotation/FoV）重新投影，而不是使用预测相机。                                                                                   | LOAD\_3D\_CAMERA                      | 否    | —                                                                             |

### 网格输入

当 `render_style` 为 "mesh" 时显示以下参数。

| 参数                       | 描述                                                                                                                                                                             | 数据类型           | 是否必需 | 范围                                                                                                               |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- | ---- | ---------------------------------------------------------------------------------------------------------------- |
| `shader`                 | 预设着色器。'normals' = 相机空间中的当前表面法线（OpenGL Y+ 法线贴图约定：+X→R，+Y→G，+Z→B）。'rainbow' = RealisDance 风格的沿身体 Y 轴 jet 渐变；'rainbow\_face\_\*' 变体使用法线/分区域颜色覆盖面部顶点；'depth' = 线性灰度。（默认："default"） | DYNAMIC\_COMBO | 否    | "default"<br />"normals"<br />"rainbow"<br />"rainbow\_face\_normal"<br />"rainbow\_face\_semantic"<br />"depth" |
| `rainbow_tilt_z`         | 绕 Z 轴（前向）旋转彩虹渐变轴。用于区分左右。仅当 `shader` 为 "rainbow"、"rainbow\_face\_normal" 或 "rainbow\_face\_semantic" 时可用。（默认：-35.0）                                                             | FLOAT          | 否    | -90.0 至 90.0，步长 0.5                                                                                              |
| `rainbow_tilt_x`         | 绕 X 轴（右向）旋转彩虹渐变轴。用于区分前后。仅当 `shader` 为 "rainbow"、"rainbow\_face\_normal" 或 "rainbow\_face\_semantic" 时可用。（默认：0.0）                                                               | FLOAT          | 否    | -90.0 至 90.0，步长 0.5                                                                                              |
| `opacity`                | 网格在背景图像上的 Alpha 透明度；未连接背景时则叠加在黑色上。（默认：1.0）                                                                                                                                     | FLOAT          | 否    | 0.0 至 1.0，步长 0.01                                                                                                |
| `person_palette_falloff` | 逐人向白色去饱和：轨道 k 会按 (1 - falloff^k) 混合出粉彩效果（SCAIL 的“第二人更柔和”效果）。1.0 = 关闭。（默认：0.6）                                                                                                  | FLOAT          | 否    | 0.1 至 1.0，步长 0.05                                                                                                |
| `region`                 | 'hands\_only' 通过预计算的 `hand_vert_mask`（基于标准手部关键点的 LBS 权重）过滤网格面片，从而单独提取手部网格，便于调试。若缺少该掩码，则回退为完整网格。（默认："full\_body"）                                                               | COMBO          | 否    | "full\_body"<br />"hands\_only"                                                                                  |

### 剪影输入

当 `render_style` 为 "silhouette" 时，该节点渲染 3D 网格的二值掩码。此模式没有额外参数。

### OpenPose 2D 输入

当 `render_style` 为 "openpose\_2d" 时显示以下参数。

| 参数                       | 描述                                                                                                                            | 数据类型  | 是否必需 | 范围                                        |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | ----- | ---- | ----------------------------------------- |
| `marker_radius_px`       | 身体关键点圆点半径（像素）。（默认：4）                                                                                                          | INT   | 否    | 1 至 32，步长 1                               |
| `stick_width_px`         | 肢体连线椭圆半宽（像素）。DWPose 默认值为 4。（默认：4）                                                                                             | INT   | 否    | 1 至 32，步长 1                               |
| `limb_alpha`             | 每条肢体的 Alpha 透明度。DWPose 默认值为 0.6。（默认：0.6）                                                                                      | FLOAT | 否    | 0.0 至 1.0，步长 0.05                         |
| `face_style`             | 'full' = 所有面部特征点（若有 sapiens-238，否则使用骨骼回退的大约 30 个点）。'eyes\_mouth' = 骨骼回退子集（约 12 个点：仅眼睛和外唇）。'disabled' = 不绘制面部点。（默认："disabled"） | COMBO | 否    | "disabled"<br />"full"<br />"eyes\_mouth" |
| `hand_style`             | 绘制 21+21 手部关键点及连线。'disabled' = 不画手。'dwpose' = 纯蓝色圆点；'openpose' = 彩虹色圆点。（默认："disabled"）                                        | COMBO | 否    | "disabled"<br />"dwpose"<br />"openpose"  |
| `person_palette_falloff` | 逐人去饱和：轨道 k 按 1 - falloff^k 向白色混合。轨道 0 保持鲜艳；1.0 禁用衰减。（默认：0.6）                                                                  | FLOAT | 否    | 0.1 至 1.0，步长 0.05                         |

### OpenPose 3D 输入

当 `render_style` 为 "openpose\_3d" 时显示以下参数。

| 参数                       | 描述                                                           | 数据类型    | 是否必需 | 范围                   |
| ------------------------ | ------------------------------------------------------------ | ------- | ---- | -------------------- |
| `radius_m`               | 肢体胶囊半径（米）（细时类似杆状）。（默认：0.015）                                 | FLOAT   | 否    | 0.004 至 0.1，步长 0.001 |
| `include_hands`          | 以 3D 胶囊形式绘制 21+21 手部关键点。（默认：True）                            | BOOLEAN | 否    | True or False        |
| `person_palette_falloff` | 逐人去饱和：轨道 k 按 1 - falloff^k 向白色混合。轨道 0 保持鲜艳；1.0 禁用衰减。（默认：0.6） | FLOAT   | 否    | 0.1 至 1.0，步长 0.05    |

### SCAIL 输入

当 `render_style` 为 "scail" 时显示以下参数。

| 参数                       | 描述                                                                                                                                         | 数据类型  | 是否必需 | 范围                                        |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | ----- | ---- | ----------------------------------------- |
| `radius_m`               | 胶囊半径（米）（SCAIL 参考值：约 0.022 m）。（默认：0.022）                                                                                                    | FLOAT | 否    | 0.005 至 0.2，步长 0.001                      |
| `hand_style`             | 在 3D 胶囊身体上方合成 2D OpenPose 手部（与 SCAIL 一致——无 3D 手部胶囊）。'disabled' = 不画手。'dwpose' = 纯蓝色手部点；'openpose' = 彩虹色点。无论哪种模式，手指连线都保持逐指彩虹色。（默认："dwpose"） | COMBO | 否    | "disabled"<br />"dwpose"<br />"openpose"  |
| `face_style`             | 'full' = 所有面部特征点（若有 sapiens-238，否则使用骨骼回退的大约 30 个点）。'eyes\_mouth' = 骨骼回退子集（约 12 个点：仅眼睛和外唇）。'disabled' = 不绘制面部点。（默认："disabled"）              | COMBO | 否    | "disabled"<br />"full"<br />"eyes\_mouth" |
| `person_palette_falloff` | 逐人去饱和：轨道 k 按 1 - falloff^k 向白色混合。轨道 0 保持鲜艳；1.0 禁用衰减。（默认：0.6）                                                                               | FLOAT | 否    | 0.1 至 1.0，步长 0.05                         |

### 说明

* 如果 `width` 和 `height` 都为 0，则输出使用姿态数据的原生图像尺寸。若仅设置其中一个，另一个按原始宽高比推导。已连接的 `background` 会被缩放以匹配渲染分辨率。
* 当连接 `camera_info` 时，姿态改为通过该相机重新投影，而不是使用预测相机。
* 在网格模式下，`rainbow_tilt_z` 和 `rainbow_tilt_x` 仅在 `shader` 设置为 "rainbow"、"rainbow\_face\_normal" 或 "rainbow\_face\_semantic" 时可用。
* 在网格模式下，当 `region` 为 "hands\_only" 时，手部区域过滤要求姿态数据包含手部顶点掩码；若缺少该掩码，则渲染完整网格。
* 在 scail 模式下，手部始终以 2D 叠加层绘制；没有 3D 手部胶囊。
* 当输出分辨率与姿态数据的原生分辨率不同时，openpose\_2d 的标记点和线段尺寸会按比例缩放。
* 如果背景帧数少于姿态数据帧数，则最后一帧背景会重复用于剩余帧。
* 输出为每个输入姿态帧生成一帧。如果姿态数据不包含任何帧，则返回一张黑色图像。

## 输出

| 输出名称 | 描述                                                                 | 数据类型  |
| ---- | ------------------------------------------------------------------ | ----- |
| `图像` | 渲染后的帧：以所选渲染样式绘制的姿态数据，在连接背景时合成到背景上，否则合成到黑色上。每个输入姿态帧对应一帧，作为单个批次图像返回。 | IMAGE |

> 本文档由 AI 生成。如果您发现任何错误或有改进建议，欢迎贡献！ [在 GitHub 上编辑](https://github.com/Comfy-Org/embedded-docs/blob/main/comfyui_embedded_docs/docs/SAM3DBody_Render/zh.md)

***

**Source fingerprint (SHA-256):** `96556283cf07727e6b4bb3549537bf925ed771bab8607f65c93ab54a5f0e9ba5`