Skip to content

Add SDPose pose detection tutorial docs #995

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lin-bot23 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add SDPose pose detection tutorial docs #995

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -293,7 +293,8 @@
"tutorials/utility/video-upscale",
"tutorials/utility/void-video-inpainting",
"tutorials/utility/video-segment-sam3",
"tutorials/utility/remove-background-birefnet"
"tutorials/utility/remove-background-birefnet",
"tutorials/utility/pose-detection-sdpose"
]
},
{
Expand Down Expand Up @@ -2415,7 +2416,8 @@
"zh/tutorials/utility/video-upscale",
"zh/tutorials/utility/void-video-inpainting",
"zh/tutorials/utility/video-segment-sam3",
"zh/tutorials/utility/remove-background-birefnet"
"zh/tutorials/utility/remove-background-birefnet",
"zh/tutorials/utility/pose-detection-sdpose"
]
},
{
Expand Down Expand Up @@ -4542,7 +4544,8 @@
"ja/tutorials/utility/video-upscale",
"ja/tutorials/utility/void-video-inpainting",
"ja/tutorials/utility/video-segment-sam3",
"ja/tutorials/utility/remove-background-birefnet"
"ja/tutorials/utility/remove-background-birefnet",
"ja/tutorials/utility/pose-detection-sdpose"
]
},
{
Expand Down
141 changes: 141 additions & 0 deletions ja/tutorials/utility/pose-detection-sdpose.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
---
title: "SDPose：ComfyUI ポーズ検出ワークフロー"
sidebarTitle: "SDPose ポーズ検出"
description: "SDPose モデルを使って、ComfyUI で画像や動画からポーズキーポイントとポーズマップを抽出する方法を学びます"
---

import UpdateReminder from '/snippets/tutorials/update-reminder.mdx'

<UpdateReminder />

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)

### 主な強み

- **全身キーポイント** — 身体、手、顔、足のキーポイントを統合モデルで検出
- **複数人対応** — 1 枚の画像や動画で複数人を検出・ラベル付け
- **設定可能な出力** — 描写する身体部位（身体・手・顔・足）の選択、線の太さやサイズの調整
- **バウンディングボックス検出** — しきい値とクラス選択が可能な物体検出機能内蔵
- **画像と動画対応** — 画像、動画、OOD ポーズ推定にそれぞれ専用ワークフロー

> **制限事項：** 検出精度は画像解像度と被写体の視認性に依存します。極端に遮蔽された被写体や非常に小さい被写体ではキーポイントが少なくなる可能性があります。

## SDPose ワークフロー

ユースケースに応じて 4 つのワークフローが利用可能です：

| ワークフロー | 入力 | 出力 | 用途 |
|------------|------|------|------|
| 複数人（画像） | 1 枚の画像 | ポーズマップ + BBox | 集合写真 |
| 複数人（動画） | 動画 | フレームごとのポーズマップ + BBox | 動画ポーズ追跡 |
| OOD 画像→ポーズ | 1 枚の画像 | ポーズマップ | スタイル変換 / 画像→ポーズ |
| 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. ワークフローの使い方

#### 複数人（画像）

- **入力** — `Load Image` ノードで画像を読み込む（例：`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）

#### 複数人（動画）

画像ワークフローと同じノード構成で、動画フレームを逐次処理します。`Load Video` で動画を入力し、`Save Video` で結果を出力します。

#### OOD 画像→ポーズ

SDPose モデルを使用し、画像からバウンディングボックスなしのクリーンなポーズマップを生成します。スタイル変換など、1 つの画像からスケルトンポーズを抽出して別の画像に適用する用途に適しています。

#### OOD 動画→ポーズマップ

動画からフレームごとのポーズマップを生成します。出力は各フレームにポーズスケルトンが含まれた動画ファイルで、下流のアニメーションや ControlNet ワークフローで使用できます。

<Card title="Subgraph について学ぶ" icon="book-open" href="/ja/interface/features/subgraph">
これらのワークフローは Subgraph ノードを使用してモジュール化された処理を実現しています。Subgraph ドキュメントでワークフローのカスタマイズと拡張方法を学んでください。
</Card>

## 補足説明

- **モデルディレクトリ** — SDPose チェックポイントは `models/checkpoints/`、RT-DETRv4 検出器は `models/diffusion_models/` に配置
- **テスト画像** — `group_photo.png` は workflow template の `input/` ディレクトリで提供されています
- **キーポイント出力** — POSE_KEYPOINT タイプは姿勢データを受け入れる下流ノードに接続可能
- **更新が必要** — SDPose + RT-DETRv4 を利用するには最新バージョンの ComfyUI が必要です
141 changes: 141 additions & 0 deletions tutorials/utility/pose-detection-sdpose.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
---
title: "SDPose: Pose Detection in ComfyUI"
sidebarTitle: "SDPose pose detection"
description: "Learn how to extract pose keypoints and maps from images and videos using SDPose, natively supported in ComfyUI"
---

import UpdateReminder from '/snippets/tutorials/update-reminder.mdx'

<UpdateReminder />

SDPose is a whole-body pose detection model that extracts human keypoints from images and videos. Combined with the RT-DETRv4 object detector, it supports multi-person detection and out-of-domain (OOD) pose estimation, making it a versatile tool for animation pipelines, pose-driven generation, and motion tracking workflows.

SDPose + RT-DETRv4 are natively supported in ComfyUI (PR [#12748](https://github.com/Comfy-Org/ComfyUI/pull/12748)). The model weights are available on Hugging Face.

[SDPose Model on Hugging Face](https://huggingface.co/Comfy-Org/SDPose) | [RT-DETRv4 Paper (arXiv)](https://arxiv.org/abs/2504.05731) | [SDPose Paper (arXiv)](https://arxiv.org/abs/2503.07740)

### Key strengths

- **Whole-body keypoints** — detects body, hands, face, and feet keypoints in a unified model
- **Multi-person support** — detects and labels multiple people in a single image or video
- **Configurable outputs** — choose which body parts to visualize (body, hands, face, feet) and control stick/font size
- **Bounding box detection** — includes object detection with tunable thresholds and class selection
- **Image and video support** — dedicated workflows for single images, videos, and OOD pose estimation

> **Limitations:** Detection accuracy depends on image resolution and subject visibility. Extremely occluded or very small subjects may produce fewer keypoints.

## SDPose Workflows

Four workflows are available depending on your use case:

| Workflow | Input | Output | Use Case |
|----------|-------|--------|----------|
| Multi-Person (Image) | Single image | Pose map + BBoxes | Photos with multiple people |
| Multi-Person (Video) | Video | Per-frame pose map + BBoxes | Video pose tracking |
| OOD Image to Pose | Single image | Pose map | Style transfer / image-to-pose |
| OOD Video to Pose Map | Video | Per-frame pose map | Video-to-pose animation |

### 1. Download Workflows

Update your ComfyUI to the latest version, then go to `Workflow` -> `Browse Templates` and find SDPose workflows under the Utility category.

<CardGroup cols={2}>
<Card title="Multi-Person (Image)" icon="image" href="https://cloud.comfy.org/?template=utility_sdpose_multi_person&utm_source=docs&utm_medium=referral&utm_campaign=sdpose">
Run in Comfy Cloud
</Card>
<Card title="Download Image Workflow" icon="download" href="https://github.com/Comfy-Org/workflow_templates/blob/main/templates/utility_sdpose_multi_person.json">
Download JSON
</Card>
</CardGroup>

<CardGroup cols={2}>
<Card title="Multi-Person (Video)" icon="video" href="https://cloud.comfy.org/?template=utility_sdpose_multi_person_video&utm_source=docs&utm_medium=referral&utm_campaign=sdpose">
Run in Comfy Cloud
</Card>
<Card title="Download Video Workflow" icon="download" href="https://github.com/Comfy-Org/workflow_templates/blob/main/templates/utility_sdpose_multi_person_video.json">
Download JSON
</Card>
</CardGroup>

<CardGroup cols={2}>
<Card title="OOD Image to Pose" icon="image" href="https://cloud.comfy.org/?template=utility_sdpose_ood_image_to_pose&utm_source=docs&utm_medium=referral&utm_campaign=sdpose">
Run in Comfy Cloud
</Card>
<Card title="Download OOD Image Workflow" icon="download" href="https://github.com/Comfy-Org/workflow_templates/blob/main/templates/utility_sdpose_ood_image_to_pose.json">
Download JSON
</Card>
</CardGroup>

<CardGroup cols={2}>
<Card title="OOD Video to Pose Map" icon="video" href="https://cloud.comfy.org/?template=utility_sdpose_ood_video_to_pose_map&utm_source=docs&utm_medium=referral&utm_campaign=sdpose">
Run in Comfy Cloud
</Card>
<Card title="Download OOD Video Workflow" icon="download" href="https://github.com/Comfy-Org/workflow_templates/blob/main/templates/utility_sdpose_ood_video_to_pose_map.json">
Download JSON
</Card>
</CardGroup>

### 2. Download Models

The SDPose and RT-DETRv4 model checkpoints are hosted on the [Comfy-Org SDPose model repository](https://huggingface.co/Comfy-Org/SDPose).

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

**diffusion_models** (RT-DETRv4 detector):
- [rt_detr_v4-x-hgnet_fp16.safetensors](https://huggingface.co/Comfy-Org/SDPose/resolve/main/diffusion_models/rt_detr_v4-x-hgnet_fp16.safetensors) (recommended)
- [rt_detr_v4-x-hgnet_fp32.safetensors](https://huggingface.co/Comfy-Org/SDPose/resolve/main/diffusion_models/rt_detr_v4-x-hgnet_fp32.safetensors) (full precision, larger)

Place them in the following directory structure:

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

### 3. Using the Workflows

#### Multi-Person (Image)

- **Input** — Load an image via the `Load Image` node. Use an image with one or more people (example: `group_photo.png`).
- **Detection** — The `Image to Pose Map (SDPose Multi-Person)` subgraph processes the image and outputs:
- **IMAGE** — pose skeleton visualization overlaid on the image
- **keypoints** — raw whole-body keypoint data
- **bboxes** — bounding box coordinates
- **Drawing Options** — Configure which body parts to draw:
- `draw_body`, `draw_hands`, `draw_face`, `draw_feet` — toggle visibility
- `stick_width`, `face_point_size` — adjust visual style
- `score_threshold` — minimum confidence for displaying keypoints
- **Detection Options**:
- `resize_type.longer_size` — scale the longer dimension before detection
- `max_detections` — maximum number of people to detect
- `detect_threshold` — detection confidence threshold
- `detect_class` — object class to detect (default: person)

#### Multi-Person (Video)

Same as the image workflow but processes video frames sequentially. Use `Load Video` to input a video file and `Save Video` to export the result.

#### OOD Image to Pose

Uses the SDPose model to generate a clean pose map from an image, without bounding box visualization. This is useful for style transfer where you want to extract the skeleton pose from one image and apply it to another.

#### OOD Video to Pose Map

Generates per-frame pose maps from a video. The output is a video file where each frame contains the extracted pose skeleton, suitable for downstream animation or ControlNet workflows.

<Card title="Learn about Subgraph" icon="book-open" href="/interface/features/subgraph">
These workflows use Subgraph nodes for modular processing. Check out the Subgraph documentation to learn how to customize and extend the workflows.
</Card>

## Additional Notes

- **Model directory** — the SDPose checkpoint goes in `models/checkpoints/`, and the RT-DETRv4 detector goes in `models/diffusion_models/`
- **Input image example** — the `group_photo.png` file is available in the workflow template's `input/` directory for testing
- **Keypoint output** — the POSE_KEYPOINT type can be connected to downstream nodes that accept pose data for conditional generation
- **Update required** — SDPose + RT-DETRv4 support is available in recent ComfyUI versions. Make sure your ComfyUI is up to date.
Loading
Loading