> ## 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)
      * [업데이트 가이드](/ko/installation/update_comfyui)

      이 가이드의 워크플로우는 [워크플로우 템플릿](/ko/interface/features/template)에서 확인할 수 있습니다.
      템플릿에서 찾을 수 없다면, 귀하의 ComfyUI가 오래된 버전일 수 있습니다. (데스크톱 버전의 업데이트는 다소 지연될 수 있습니다)

      워크플로우를 로드할 때 노드가 누락되는 경우, 가능한 원인:

      1. 최신 ComfyUI 버전(야간 빌드)을 사용하고 있지 않음
      2. 일부 노드가 시작 시 가져오기에 실패함
    </Tab>

    <Tab title="데스크톱 또는 클라우드 사용자">
      * 데스크톱 버전은 ComfyUI 안정판 기반으로, 새로운 데스크톱 안정판이 출시되면 자동으로 업데이트됩니다.
      * [클라우드](https://cloud.comfy.org)는 ComfyUI 안정판 출시 후 업데이트됩니다.

      따라서 이 문서에서 핵심 노드가 누락된 것을 발견했다면, 그 이유는 새로운 핵심 노드가 아직 최신 안정판에 공개되지 않았기 때문일 수 있습니다. 다음 안정판 출시를 기다려 주세요.
    </Tab>
  </Tabs>
</Tip>

SDPose는 이미지와 비디오에서 사람의 키포인트를 추출하는 전신 포즈 감지 모델입니다. RT-DETRv4 객체 감지기와 결합하여 다중 인물 감지 및 OOD(Out-of-Domain) 포즈 추정을 지원하므로 애니메이션 파이프라인, 포즈 기반 생성 및 모션 추적 워크플로에 다용도로 활용할 수 있습니다.

SDPose + RT-DETRv4는 ComfyUI에 기본 지원됩니다 (PR [#12748](https://github.com/Comfy-Org/ComfyUI/pull/12748)). 모델 가중치는 Hugging Face에서 제공됩니다.

[SDPose 모델 on Hugging Face](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를 최신 버전으로 업데이트한 다음, `Workflow` -> `Browse Templates`로 이동하여 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)에 호스팅되어 있습니다.

**체크포인트** (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 모델을 사용하여 바운딩 박스 시각화 없이 이미지에서 깨끗한 포즈 맵을 생성합니다. 이는 한 이미지에서 스켈레톤 포즈를 추출하여 다른 이미지에 적용하는 스타일 전이에 유용합니다.

#### OOD 비디오 → 포즈 맵

비디오에서 프레임별 포즈 맵을 생성합니다. 출력은 각 프레임에 추출된 포즈 스켈레톤이 포함된 비디오 파일로, 다운스트림 애니메이션이나 컨트롤넷 워크플로에 적합합니다.

<Card title="서브그래프에 대해 알아보기" icon="book-open" href="/ko/interface/features/subgraph">
  이 워크플로는 모듈식 처리를 위해 서브그래프 노드를 사용합니다. 서브그래프 문서를 확인하여 워크플로를 사용자 정의하고 확장하는 방법을 알아보세요.
</Card>

## 추가 참고 사항

* **모델 디렉토리** — SDPose 체크포인트는 `models/checkpoints/`에, RT-DETRv4 감지기는 `models/diffusion_models/`에 넣습니다.
* **입력 이미지 예시** — `group_photo.png` 파일은 워크플로 템플릿의 `input/` 디렉토리에서 테스트용으로 제공됩니다.
* **키포인트 출력** — POSE\_KEYPOINT 유형은 조건부 생성을 위해 포즈 데이터를 허용하는 다운스트림 노드에 연결할 수 있습니다.
* **업데이트 필수** — SDPose + RT-DETRv4 지원은 최근 ComfyUI 버전에서 사용 가능합니다. ComfyUI가 최신 상태인지 확인하세요.