> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-comfy-docs-comfyapi-search.mintlify.site/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 或 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                     | 否  | —                                                                             |

### Mesh 输入

当 `render_style` 为 "mesh" 时，会出现这些参数。

| 参数                       | 描述                                                                                                                                                                       | 数据类型           | 必填 | 范围                                                                                                               |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- | -- | ---------------------------------------------------------------------------------------------------------------- |
| `shader`                 | 预设着色器。'normals' = 相机空间中的当前表面法线（OpenGL Y+ 法线贴图约定：+X→R、+Y→G、+Z→B）。'rainbow' = RealisDance 风格的身体 Y 轴喷色；'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`                | 网格在背景图像上的不透明度；未连接背景时则叠加在黑色之上。（默认值：1.0）                                                                                                                                   | FLOAT          | 否  | 0.0 至 1.0，步长 0.01                                                                                                |
| `person_palette_falloff` | 逐人去饱和，向白色过渡：轨道 k 得到 (1 - falloff^k) 的粉彩混合（SCAIL 的 'softer second person'）。1.0 = 关闭。（默认值：0.6）                                                                             | FLOAT          | 否  | 0.1 至 1.0，步长 0.05                                                                                                |
| `region`                 | 'hands\_only' 会通过预计算的 `hand_vert_mask`（针对标准手部 KPs 的 LBS 权重）过滤面片 —— 用于调试时分离出手部网格。若遮罩缺失，则回退为完整网格。（默认值："full\_body"）                                                        | COMBO          | 否  | "full\_body"<br />"hands\_only"                                                                                  |

### Silhouette 输入

当 `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`             | 逐肢体不透明度。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`          | 将 21+21 手部关键点绘制为 3D 胶囊。（默认值：True）                             | BOOLEAN | 否  | True 或 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 米）。（默认值：0.022）                                                                                                           | FLOAT | 否  | 0.005 至 0.2，步长 0.001                      |
| `hand_style`             | 将 2D OpenPose 手部合成到 3D 胶囊身体之上（与 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` 时，姿态将通过该相机重新投影，而非使用预测的相机。
* 在 mesh 模式下，仅当 `shader` 设置为 "rainbow"、"rainbow\_face\_normal" 或 "rainbow\_face\_semantic" 时，`rainbow_tilt_z` 和 `rainbow_tilt_x` 才可用。
* 在 mesh 模式下，当 `region` 为 "hands\_only" 时，手部区域过滤要求姿态数据包含手部顶点遮罩；若遮罩缺失，则改为渲染完整网格。
* 在 scail 模式下，手部以 2D OpenPose 叠加层的形式绘制在 3D 胶囊身体之上，而非 3D 胶囊；将 `hand_style` 设为 "disabled" 可将其完全移除。
* 当输出分辨率与姿态数据原生分辨率不同时，openpose\_2d 的标记点与骨骼线尺寸会按比例缩放。
* 若背景的帧数少于姿态数据，则剩余帧会复用背景的最后一帧。
* 输出中每个输入姿态帧对应一帧。若姿态数据不包含任何帧，则返回单张黑色图像。

## 输出

| 输出名     | 描述                                                                       | 数据类型  |
| ------- | ------------------------------------------------------------------------ | ----- |
| `image` | 渲染后的帧：以所选渲染样式绘制的姿态数据，在连接了背景时合成到背景之上，否则合成到黑色之上。每个输入姿态帧对应一帧，并以单张批量图像的形式返回。 | 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`