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

# BuildPoseFile - ComfyUI Built-in Node Documentation

> 이 노드는 포즈 데이터로부터 저장 준비가 완료된 3D 애니메이션 파일을 생성합니다. 전체 바디 메시, 관절만 미리보기, OpenPose 스켈레톤 또는 SCAIL 캡슐 리그 등 여러 시각적 스타일로 애니메이션 GLB를 내보내거나, BVH 모션캡처 클립을 대신 저장할 수 있습니다. 출력은 Save 3D Model과 같은 파일

이 노드는 포즈 데이터로부터 저장 준비가 완료된 3D 애니메이션 파일을 생성합니다. 전체 바디 메시, 관절만 미리보기, OpenPose 스켈레톤 또는 SCAIL 캡슐 리그 등 여러 시각적 스타일로 애니메이션 GLB를 내보내거나, BVH 모션캡처 클립을 대신 저장할 수 있습니다. 출력은 Save 3D Model과 같은 파일 저장 노드에 연결하여 디스크에 파일을 기록할 수 있습니다.

## 입력

### 공통 입력

| 매개변수                 | 설명                                                                                                                                  | 데이터 타입                               | 필수  | 범위                                    |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | --- | ------------------------------------- |
| `pose_data`          | 3D 포즈 데이터. MHR 포즈 데이터(모델/셰이프/표정 파라미터, MHR70 키포인트, 표준 색상, 손 정점 마스크) 또는 Kimodo 포즈 데이터(프레임별 예측 정점 및 카메라가 포함된 외부 Y-up 리그)를 허용합니다.       | MHR\_POSE\_DATA / KIMODO\_POSE\_DATA | 예   | —                                     |
| `format`             | 출력 형식. 둘 다 Save 3D Model에 전달되어 디스크에 기록됩니다. 'glb' = 애니메이션 GLB(메시/본/OpenPose/SCAIL). 'bvh' = BVH 모션캡처 클립(단일 스켈레톤, 모델 필요). (기본값: glb)  | DYNAMIC\_COMBO                       | 예   | "glb"<br />"bvh"                      |
| `sam3d_body_model`   | 선택적 SAM3D 바디 모델. 포즈 데이터에 스켈레톤 오버라이드가 포함되어 있지 않은 한 'bvh', 'body\_mesh', 'bones\_only' 형식에 필요합니다.                                     | SAM3D\_BODY\_MODEL                   | 아니요 | —                                     |
| `fps`                | 애니메이션 프레임 레이트. (기본값: 24.0)                                                                                                          | FLOAT                                | 예   | 1.0-240.0                             |
| `camera_translation` | pred\_cam\_t를 루트의 트랜슬레이션에 베이크합니다. 'off' = 바인드 위치, 'centered' = 프레임 0 기준 델타, 'absolute' = 원시 값(Z는 카메라 깊이이며, 보통 미터 단위 거리). (기본값: off) | COMBO                                | 예   | "off"<br />"centered"<br />"absolute" |
| `track_index`        | 트랙 선택: -1 = 모든 트랙, ≥0 = 단일 트랙. (기본값: -1)                                                                                            | INT                                  | 예   | -1 \~ 15                              |

### GLB 입력

이 입력들은 `format`이 "glb"로 설정된 경우 나타납니다.

| 매개변수                 | 설명                                                                                                                                                                                                                                        | 데이터 타입         | 필수 | 범위                                                           |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | -- | ------------------------------------------------------------ |
| `mesh_style`         | GLB의 시각적 스타일: 'body\_mesh' = 실제 Armature(127개 본, 스키닝, TRS 키프레임, 72개 페이스 모프, 모델 필요). 'bones\_only' = 각 관절의 본 형태 프리미티브(미리보기 아마추어). 'openpose' = 키포인트 기반 OpenPose-18 3D 스켈레톤. 'scail' = SCAIL 3D 캡슐 리그(관절 구로 끝이 막힌 열린 원통). (기본값: body\_mesh) | DYNAMIC\_COMBO | 예  | "body\_mesh"<br />"bones\_only"<br />"openpose"<br />"scail" |
| `bone_smooth_window` | 본별 회전 키프레임/키포인트 트랙에 적용되는 가우시안 평활화 윈도우. 0 = 끄기. 7-15는 업스트림 Smooth가 스파이크를 놓칠 때 회전/떨림을 진정시킵니다. (기본값: 0)                                                                                                                                      | INT            | 예  | 0-51, step 2                                                 |

#### Body Mesh 입력

`mesh_style`이 "body\_mesh"일 때 나타납니다.

| 매개변수                     | 설명                                                                                                                       | 데이터 타입         | 필수 | 범위                                                                                   |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------ | -------------- | -- | ------------------------------------------------------------------------------------ |
| `bone_vis`               | 각 관절에 리지드하게 스키닝된 본 시각화 형태. 'off' = 본 시각화 없음, 'octahedrons' = Blender 스타일 방향성 본. (기본값: off)                               | DYNAMIC\_COMBO | 예  | "off"<br />"octahedrons"                                                             |
| `bone_vis_radius_m`      | `bone_vis` = "octahedrons"일 때 나타납니다. 반지름(m). (구 반지름 / 팔면체 절반 너비). (기본값: 0.02)                                            | FLOAT          | 예  | 0.005-0.5                                                                            |
| `bone_vis_color`         | `bone_vis` = "octahedrons"일 때 나타납니다. 본별 정점 색상(무광 재질). 'white' = 없음, 'rainbow\_y' = 머리부터 발끝까지 제트 그라데이션. (기본값: rainbow\_y) | COMBO          | 예  | "white"<br />"rainbow\_y"                                                            |
| `shader`                 | Render 노드의 셰이더와 일치하는 정점별 색상 베이크(COLOR\_0 + KHR\_materials\_unlit). 'default' = 색상 없음. (기본값: default)                     | DYNAMIC\_COMBO | 예  | "default"<br />"rainbow"<br />"rainbow\_face\_normal"<br />"rainbow\_face\_semantic" |
| `rainbow_tilt_z`         | `shader`가 rainbow 변형일 때 나타납니다. 무지개 축을 Z(앞) 주위로 회전합니다. 좌/우를 구분합니다. (기본값: -35.0)                                           | FLOAT          | 예  | -90.0 \~ 90.0                                                                        |
| `rainbow_tilt_x`         | `shader`가 rainbow 변형일 때 나타납니다. 무지개 축을 X(오른쪽) 주위로 회전합니다. 앞/뒤를 구분합니다. (기본값: 0.0)                                           | FLOAT          | 예  | -90.0 \~ 90.0                                                                        |
| `person_palette_falloff` | `shader`가 rainbow 변형일 때 나타납니다. 인물별 탈색: 각 트랙은 (1 - falloff^k) 파스텔 혼합을 얻습니다. (기본값: 0.6)                                    | FLOAT          | 예  | 0.1-1.0                                                                              |

#### Bones Only 입력

`mesh_style`이 "bones\_only"일 때 나타납니다.

| 매개변수                | 설명                                                                                  | 데이터 타입         | 필수 | 범위                        |
| ------------------- | ----------------------------------------------------------------------------------- | -------------- | -- | ------------------------- |
| `bone_vis`          | 각 관절에 리지드하게 스키닝된 본 시각화 형태. 'octahedrons' = Blender 스타일 방향성 본(관절 → 기본 자식).           | DYNAMIC\_COMBO | 예  | "octahedrons"             |
| `bone_vis_radius_m` | 반지름(m). (구 반지름 / 팔면체 절반 너비). (기본값: 0.02)                                            | FLOAT          | 예  | 0.005-0.5                 |
| `bone_vis_color`    | 본별 정점 색상(무광 재질). 'white' = 없음, 'rainbow\_y' = 머리부터 발끝까지 제트 그라데이션. (기본값: rainbow\_y) | COMBO          | 예  | "white"<br />"rainbow\_y" |

#### OpenPose 입력

`mesh_style`이 "openpose"일 때 나타납니다.

| 매개변수                   | 설명                                                                                                                                                     | 데이터 타입  | 필수 | 범위                                        |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | -- | ----------------------------------------- |
| `marker_radius_m`      | 구 반지름(m). (기본값: 0.010)                                                                                                                                 | FLOAT   | 예  | 0.005-0.1                                 |
| `stick_radius_m`       | 팔다리 절반 너비(m). 본 길이 x 0.1로 자동 제한됩니다. (기본값: 0.008)                                                                                                       | FLOAT   | 예  | 0.002-0.05                                |
| `include_hands`        | pred\_keypoints\_3d에서 가져온 21+21 OpenPose 손(손목 + 5개 손가락 x 4개 관절, 기저→끝)을 추가합니다. (기본값: False)                                                             | BOOLEAN | 예  | True / False                              |
| `hand_marker_radius_m` | 손 구 반지름(m). (기본값: 0.005)                                                                                                                               | FLOAT   | 예  | 0.001-0.1                                 |
| `hand_stick_radius_m`  | 손 팔다리 절반 너비(m). (기본값: 0.003)                                                                                                                           | FLOAT   | 예  | 0.001-0.05                                |
| `face_style`           | 고정된 머리 메시 정점 ID에서 pred\_vertices로 샘플링한 얼굴 윤곽 랜드마크(pose\_data에 canonical\_colors 필요). 'full' = 전체 약 30개 점, 'eyes\_mouth' = 눈 + 바깥쪽 입술만. (기본값: disabled) | COMBO   | 예  | "disabled"<br />"full"<br />"eyes\_mouth" |
| `face_marker_radius_m` | 얼굴 점 반지름. 0 = 자동 = marker\_radius\_m의 0.3배. (기본값: 0.0)                                                                                                 | FLOAT   | 예  | 0.0-0.05                                  |

#### SCAIL 입력

`mesh_style`이 "scail"일 때 나타납니다.

| 매개변수                   | 설명                                                                                                                                    | 데이터 타입  | 필수 | 범위                                        |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------- | -- | ----------------------------------------- |
| `stick_radius_m`       | 원통 반지름(m). 본은 일정한 반지름의 열린 원통이며, 관절 구(자동 크기 조정됨)가 열린 끝을 막습니다. SCAIL 기준 = 0.0215 m. (기본값: 0.022)                                        | FLOAT   | 예  | 0.002-0.1                                 |
| `marker_radius_m`      | 관절 구 반지름. 0 = 자동 = stick\_radius\_m(플러시 캡). (기본값: 0.0)                                                                                | FLOAT   | 예  | 0.0-0.1                                   |
| `material_roughness`   | PBR 거칠기. SCAIL 기준 = 0.3. 1 = 무광, 0 = 크롬. (기본값: 0.3)                                                                                   | FLOAT   | 예  | 0.0-1.0                                   |
| `include_hands`        | 트랙별 21+21 손 키포인트와 캡슐 스틱을 추가합니다. (기본값: False)                                                                                          | BOOLEAN | 예  | True / False                              |
| `hand_marker_radius_m` | 손 구 반지름(m). (기본값: 0.005)                                                                                                              | FLOAT   | 예  | 0.001-0.05                                |
| `hand_stick_radius_m`  | 손 원통 반지름(m). (기본값: 0.003)                                                                                                             | FLOAT   | 예  | 0.001-0.05                                |
| `face_style`           | pred\_vertices에서 샘플링한 얼굴 윤곽 랜드마크(pose\_data에 canonical\_colors 필요). 'full' = 전체 약 30개 점, 'eyes\_mouth' = 눈 + 바깥쪽 입술만. (기본값: disabled) | COMBO   | 예  | "disabled"<br />"full"<br />"eyes\_mouth" |

### BVH 입력

`format`이 "bvh"로 설정된 경우 나타납니다.

| 매개변수    | 설명                                                  | 데이터 타입 | 필수 | 범위            |
| ------- | --------------------------------------------------- | ------ | -- | ------------- |
| `units` | BVH OFFSET/position 단위. 'cm'은 모션캡처 표준입니다. (기본값: cm) | COMBO  | 예  | "cm"<br />"m" |

**참고 사항:**

* `bvh` 형식과 `body_mesh`, `bones_only` 메시 스타일은 `sam3d_body_model` 입력이 필요합니다. 단, `pose_data` 자체에 스켈레톤 오버라이드(예: KimodoSample 노드의 `_skeleton_override` 딕셔너리)가 포함된 경우는 예외입니다. 둘 다 없으면 노드가 오류를 발생시킵니다. `openpose`와 `scail` 스타일은 리그 독립적이며 바디 모델 없이 키포인트에서 직접 작동합니다.
* `bvh` 형식에서 출력에는 단일 스켈레톤이 포함됩니다. `track_index`가 -1(모든 트랙)이면 첫 번째 트랙이 사용됩니다.
* `face_style`의 `full` 및 `eyes_mouth` 옵션은 포즈 데이터에 `canonical_colors`가 필요하며, 이는 포즈 데이터가 바디 모델과 함께 MHR 파이프라인에서 제공될 때 존재합니다.
* `bone_smooth_window`는 0에서 51 사이에서 2단계로 증가합니다.

## 출력

| 출력 이름      | 설명                                                                                  | 데이터 타입   |
| ---------- | ----------------------------------------------------------------------------------- | -------- |
| `model_3d` | 생성된 애니메이션 파일: 애니메이션 GLB 또는 BVH 모션캡처 클립이며, Save 3D Model과 같은 노드로 디스크에 저장할 준비가 되었습니다. | 3D\_FILE |

> 이 문서는 AI에 의해 생성되었습니다. 오류를 발견하거나 개선 제안이 있으시면 기여해 주세요! [GitHub에서 편집](https://github.com/Comfy-Org/embedded-docs/blob/main/comfyui_embedded_docs/docs/BuildPoseFile/ko.md)

***

**Source fingerprint (SHA-256):** `f3672f0749c4f9affcc92da98198c5b142f6fcd9f5e317ab43dd7e53533c0fa3`