> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-feat-openapi-i18n.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# SDPose：ComfyUI 中的姿态检测

> 学习如何使用 ComfyUI 原生支持的 SDPose 从图像和视频中提取姿态关键点和姿态图

<Tip>
  <Tabs>
    <Tab title="便携版或手动安装用户">
      请确保你的 ComfyUI 已经更新。

      * [ComfyUI 下载](https://www.comfy.org/download)
      * [ComfyUI 更新教程](/zh/installation/update_comfyui)

      本指南里的工作流可以在 ComfyUI 的[工作流模板](/zh/interface/features/template)中找到。如果找不到，可能是 ComfyUI 没有更新。

      如果加载工作流时有节点缺失，可能原因有：

      1. 你用的不是最新开发版（nightly）。
      2. 你用的是稳定版或桌面版（没有包含最新的更新）。
      3. 启动时有些节点导入失败。
    </Tab>

    <Tab title="桌面版或云端用户">
      * 桌面版是基于 ComfyUI 稳定版本构建的，它会在有新的桌面稳定版本发布时自动更新。
      * [Cloud](https://cloud.comfy.org) 会在 ComfyUI 稳定版本发布后更新，我们会同步更新 Cloud。

      所以，如果你发现本教程中有任何核心节点缺失，那是因为对应的节点支持还在开发中没有发布正式的稳定版，请等待下一个稳定版本发布。
    </Tab>
  </Tabs>
</Tip>

SDPose 是一种全身姿态检测模型，可从图像和视频中提取人体关键点。结合 RT-DETRv4 对象检测器，它支持多人检测和跨域（OOD）姿态估计，使其成为动画管线、姿态驱动生成和运动追踪工作流中的多功能工具。

SDPose + RT-DETRv4 已在 ComfyUI 中原生支持（PR [#12748](https://github.com/Comfy-Org/ComfyUI/pull/12748)）。模型权重可在 Hugging Face 上获取。

[Hugging Face 上的 SDPose 模型](https://huggingface.co/Comfy-Org/SDPose) | [RT-DETRv4 论文 (arXiv)](https://arxiv.org/abs/2504.05731) | [SDPose 论文 (arXiv)](https://arxiv.org/abs/2503.07740)

### 主要优势

* **全身关键点** — 在统一的模型中检测身体、手部、面部和脚部关键点
* **多人支持** — 在单张图像或视频中检测并标注多人
* **可配置的输出** — 可选择可视化哪些身体部位（身体、手部、面部、脚部），并控制骨架线宽和字体大小
* **边界框检测** — 包含对象检测，可调节阈值和类别选择
* **图像和视频支持** — 针对单张图像、视频和 OOD 姿态估计提供专门的工作流

> **局限性：** 检测精度取决于图像分辨率和目标可见性。极度遮挡或非常小的目标可能产生较少的关键点。

## SDPose 工作流

根据你的使用场景，提供了四种工作流：

| 工作流        | 输入   | 输出          | 应用场景         |
| ---------- | ---- | ----------- | ------------ |
| 多人（图像）     | 单张图像 | 姿态图 + 边界框   | 多人照片         |
| 多人（视频）     | 视频   | 逐帧姿态图 + 边界框 | 视频姿态追踪       |
| OOD 图像转姿态  | 单张图像 | 姿态图         | 风格迁移 / 图像转姿态 |
| OOD 视频转姿态图 | 视频   | 逐帧姿态图       | 视频转姿态动画      |

### 1. 下载工作流

将你的 ComfyUI 更新到最新版本，然后前往 `工作流` -> `浏览模板`，在“Utility”类别下找到 SDPose 工作流。

<CardGroup cols={2}>
  <Card title="多人（图像）" icon="image" href="https://cloud.comfy.org/?template=utility_sdpose_multi_person&utm_source=docs&utm_medium=referral&utm_campaign=sdpose">
    在 Comfy Cloud 中运行
  </Card>

  <Card title="下载图像工作流" icon="download" href="https://github.com/Comfy-Org/workflow_templates/blob/main/templates/utility_sdpose_multi_person.json">
    下载 JSON
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="多人（视频）" icon="video" href="https://cloud.comfy.org/?template=utility_sdpose_multi_person_video&utm_source=docs&utm_medium=referral&utm_campaign=sdpose">
    在 Comfy Cloud 中运行
  </Card>

  <Card title="下载视频工作流" icon="download" href="https://github.com/Comfy-Org/workflow_templates/blob/main/templates/utility_sdpose_multi_person_video.json">
    下载 JSON
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="OOD 图像转姿态" icon="image" href="https://cloud.comfy.org/?template=utility_sdpose_ood_image_to_pose&utm_source=docs&utm_medium=referral&utm_campaign=sdpose">
    在 Comfy Cloud 中运行
  </Card>

  <Card title="下载 OOD 图像工作流" icon="download" href="https://github.com/Comfy-Org/workflow_templates/blob/main/templates/utility_sdpose_ood_image_to_pose.json">
    下载 JSON
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="OOD 视频转姿态图" icon="video" href="https://cloud.comfy.org/?template=utility_sdpose_ood_video_to_pose_map&utm_source=docs&utm_medium=referral&utm_campaign=sdpose">
    在 Comfy Cloud 中运行
  </Card>

  <Card title="下载 OOD 视频工作流" icon="download" href="https://github.com/Comfy-Org/workflow_templates/blob/main/templates/utility_sdpose_ood_video_to_pose_map.json">
    下载 JSON
  </Card>
</CardGroup>

### 2. 下载模型

SDPose 和 RT-DETRv4 模型文件托管在 [Comfy-Org SDPose 模型仓库](https://huggingface.co/Comfy-Org/SDPose) 中。

**checkpoints**（SDPose 模型）：

* [sdpose\_wholebody\_fp16.safetensors](https://huggingface.co/Comfy-Org/SDPose/resolve/main/checkpoints/sdpose_wholebody_fp16.safetensors)

**diffusion\_models**（RT-DETRv4 检测器）：

* [rt\_detr\_v4-x-hgnet\_fp16.safetensors](https://huggingface.co/Comfy-Org/SDPose/resolve/main/diffusion_models/rt_detr_v4-x-hgnet_fp16.safetensors)（推荐）
* [rt\_detr\_v4-x-hgnet\_fp32.safetensors](https://huggingface.co/Comfy-Org/SDPose/resolve/main/diffusion_models/rt_detr_v4-x-hgnet_fp32.safetensors)（全精度，体积更大）

将模型放置在以下目录结构中：

```
📂 ComfyUI/
└── 📂 models/
    ├── 📂 checkpoints/
    │   └── sdpose_wholebody_fp16.safetensors
    └── 📂 diffusion_models/
        ├── rt_detr_v4-x-hgnet_fp16.safetensors
        └── rt_detr_v4-x-hgnet_fp32.safetensors
```

### 3. 使用工作流

#### 多人（图像）

* **输入** — 通过 `加载图像` 节点加载一张图像。使用包含一人或多人的图像（示例：`group_photo.png`）。
* **检测** — `Image to Pose Map (SDPose Multi-Person)` 子图处理图像并输出：
  * **IMAGE** — 叠加在图像上的姿态骨架可视化结果
  * **keypoints** — 原始全身关键点数据
  * **bboxes** — 边界框坐标
* **绘制选项** — 配置要绘制的身体部位：
  * `draw_body`、`draw_hands`、`draw_face`、`draw_feet` — 切换可见性
  * `stick_width`、`face_point_size` — 调整视觉样式
  * `score_threshold` — 显示关键点的最低置信度
* **检测选项**：
  * `resize_type.longer_size` — 检测前对较长边进行缩放
  * `max_detections` — 最大检测人数
  * `detect_threshold` — 检测置信度阈值
  * `detect_class` — 要检测的对象类别（默认：person）

#### 多人（视频）

与图像工作流相同，但会顺序处理视频帧。使用 `加载视频` 输入视频文件，并使用 `保存视频` 导出结果。

#### OOD 图像转姿态

利用 SDPose 模型从图像生成干净的人体姿态图，不包含边界框可视化。适用于风格迁移，即你想从一张图像中提取骨架姿态并应用到另一张图像上。

#### OOD 视频转姿态图

从视频生成逐帧姿态图。输出是一个视频文件，其中每一帧都包含提取的姿态骨架，适用于下游动画或 ControlNet 工作流。

<Card title="了解子图" icon="book-open" href="/zh/interface/features/subgraph">
  这些工作流使用子图节点进行模块化处理。请查阅子图文档，了解如何自定义和扩展工作流。
</Card>

## 附加说明

* **模型目录** — SDPose 模型文件放在 `models/checkpoints/` 中，RT-DETRv4 检测器放在 `models/diffusion_models/` 中
* **输入图像示例** — 工作流模板的 `input/` 目录中提供了 `group_photo.png` 文件以供测试
* **关键点输出** — POSE\_KEYPOINT 类型可以连接到接受姿态数据进行条件生成的下游节点
* **需要更新** — 较新的 ComfyUI 版本才支持 SDPose + RT-DETRv4。请确保你的 ComfyUI 是最新版本。