ComfyUI Extension

ComfyUI-GNM

Generate parametric 3D heads by adjusting gender, race, expression, and head angle with sliders, output as color images, normal maps, depth maps, and masks for ControlNet conditioning. (Description by CC)

By soylab-edu·Created about a month ago·Updated about a month ago· 9

soylab-edu/ComfyUI-GNM

Nodes8

On cloudLocal install

CategoryGNM

Stars9

Updatedabout a month ago

Nodes (8)

GNM Expression Sampler

GNM Head Viewport (Advanced)

GNM

GNM Head Viewport (Pro Node)

Readme

ComfyUI-GNM

GNM Head Viewport outputs: image, normal map, depth map, mask

성별·인종·표정·머리 각도를 슬라이더로 조절해 3D 두상을 만들고, 컬러 이미지

노멀맵 + 뎁스맵 + 마스크로 출력합니다 (노멀/뎁스는 ControlNet 컨디셔닝에 바로 사용 가능). GNM Head Viewport 노드의 내장 미리보기는 최종 출력과 동일한 렌더러를 사용하므로 보이는 그대로 출력됩니다.

Google GNM (Generative aNthropometric Model) — 파라메트릭 3D 두상 모델을 ComfyUI 노드로 사용합니다. GNM Head v3 코어(numpy 백엔드)와 모델 데이터(51MB npz)가 vendor/에 동봉되어 있어 별도 다운로드가 필요 없습니다. (GNM은 Apache-2.0 라이선스)

설치

이 폴더(ComfyUI-GNM)를 ComfyUI/custom_nodes/에 복사합니다.
ComfyUI의 파이썬 환경에서:
```
pip install -r requirements.txt
```

TensorFlow는 필요 없습니다 — 시맨틱 샘플러(성별/인종/표정)의 Keras 디코더는 h5py로 가중치를 읽어 numpy로 직접 실행합니다 (tf.keras와 출력 동일 검증됨).

노드

| 노드 | 설명 | |---|---| | GNM Model Loader | GNM Head v3 모델 로드 (1회 로드 후 캐시) → GNM_MODEL | | GNM Random Params | 표준정규분포에서 identity/expression 벡터 샘플링 | | GNM Identity Sampler | 성별(2종) × 인종(4종) 조건으로 identity 샘플링 | | GNM Expression Sampler | 20종 표정 클래스(happy, surprise, wink 등)에서 expression 샘플링 | | GNM Head Render | 파라미터로 두상을 포즈하고 렌더링 → IMAGE(컬러) + 노멀맵 + 뎁스맵 + 마스크 | | GNM Head Viewport | 위 기능이 전부 들어간 올인원 노드 + 실시간 미리보기. 슬라이더를 움직이면 Queue 없이 즉시 갱신되고, 미리보기를 마우스로 드래그(궤도 회전)/휠(줌)하면 카메라 위젯에 반영됩니다. Queue 실행 시 미리보기와 같은 구도로 최종 이미지 출력 | | GNM Head Viewport (Advanced) | GNM 공식 데모(GIF)와 동일한 개별 컴포넌트 슬라이더(identity: head 10 + eyes 3, expression: 눈 3+3·하관 7·혀 4·동공 1)를 노드 내 패널로 제공. neck/head 분리 회전, 시선(gaze) + 버전스, XYZ 이동 슬라이더 포함. 샘플링 강도를 0으로 두면 데모처럼 템플릿에서 조형 시작 | | GNM Head Viewport (Pro Node) | Advanced와 동일하되 모든 컴포넌트 노출 — identity 253개(head 170/eyes 3/teeth 80) + expression 383개(영역별 접이식 그룹, 스크롤 패널) |

GNM Head Render 파라미터

head_yaw/pitch/roll: 목 관절 회전 (도 단위)
eyes_yaw/pitch: 안구 회전
camera_azimuth/elevation: 카메라 궤도 각도 (0/0 = 정면)
zoom, fov: 화면 채움 비율과 원근감
surface: plain(단색 머티리얼) 또는 edgeflow_texture(GNM 기본 텍스처)
mesh_parts: face_default(눈 외피 제외, GNM 기본) 또는 all

노멀맵/뎁스맵 출력은 ControlNet 컨디셔닝(depth, normal)에 바로 연결할 수 있습니다 — 원하는 얼굴형·표정·각도의 헤드를 만들어 이미지 생성 제어에 사용하세요.

뷰포트 노드 3종 비교 — 어떤 노드를 쓸까?

세 노드 모두 실시간 미리보기(드래그 궤도 회전·휠 줌), 동일한 4종 출력 (image / normal_map / depth_map / mask), Queue 시 풀 해상도 렌더를 지원합니다. 차이는 얼굴을 만드는 방식입니다.

| | GNM Head Viewport | (Advanced) | (Pro Node) | |---|---|---|---| | 얼굴 생성 방식 | 시드 샘플링 | 샘플링 + 컴포넌트 슬라이더 | 샘플링 + 전체 컴포넌트 | | identity 조절 | 성별·인종·시드·강도 | + head 10, eyes 3 슬라이더 | + head 170, eyes 3, teeth 80 (253개 전부) | | expression 조절 | 표정 20종 클래스·시드·강도 | + 눈 3+3, 하관 7, 혀 4, 동공 1 슬라이더 | + 영역별 383개 전부 | | 머리 회전 | head yaw/pitch/roll (neck+head 자동 분배) | neck(±90°)·head(±45°) 분리 | 동일 | | 시선 | eyes yaw/pitch | gaze pitch/yaw + 버전스(양안 모음) | 동일 | | 위치 이동 | 없음 (카메라로 대체) | translate XYZ (±0.2m, 프레임 고정) | 동일 | | 적합한 용도 | 빠르게 랜덤 얼굴 뽑기, 시드 탐색 | GNM 공식 데모처럼 주요 성분만 직접 조형 | 특정 성분(치아, 눈가 주름 등)까지 정밀 제어 |

사용 팁

Advanced/Pro는 identity_strength/expression_strength 기본값이 0이라 템플릿(평균) 얼굴에서 조형을 시작합니다. 시드로 뽑은 얼굴을 베이스로 미세조정하려면 강도를 올리세요 — 컴포넌트 슬라이더 값은 샘플링된 벡터 위에 오프셋으로 더해집니다.
컴포넌트 슬라이더 값은 노드의 숨은 JSON 위젯에 저장되어 워크플로 저장/로드 시 그대로 복원됩니다.
그룹별 reset 버튼으로 해당 영역만 초기화할 수 있습니다.
예시 (GIF 데모의 입 벌리기): Expression → lower face 그룹에서 e200 = -2.6, e201 = 1.0, e202 = -2.1.
미리보기는 조작 중 저해상도(256px)로 빠르게 흐르고, 손을 떼면 자동으로 선명한 화질(384px)로 정제됩니다. Queue 실행 결과는 항상 width/height 그대로의 풀 해상도입니다.

가장 간단한 사용법 (뷰포트 노드)

GNM Head Viewport 노드 하나만 놓고 image 출력을 Preview/Save Image에 연결하면 끝입니다. 성별/인종/표정/시드/회전이 모두 슬라이더 위젯으로 있고, 노드 안의 3D 뷰포트가 실시간으로 갱신됩니다. 내부 구현:

프론트엔드(three.js)가 위젯 변경을 감지해 /gnm/viewport/pose API로 파라미터를 보내고, 서버가 GNM forward pass로 계산한 버텍스(float32 바이너리)를 받아 메시를 갱신합니다 (요청당 ~210KB, 디바운스 120ms).
메시 토폴로지는 /gnm/viewport/topology에서 최초 1회만 받습니다.

기본 워크플로 예시

GNM Model Loader ─┬─────────────────────────► GNM Head Render ─► Preview Image
                  │                            ▲    ▲
GNM Random Params ┴─ identity ─────────────────┘    │
                  └─ expression ────────────────────┘

주의사항

렌더링 백엔드: GNM 자체의 pyrender 래퍼는 osmesa를 강제해 Windows에서 동작하지 않으므로, 이 패키지는 pyrender를 직접 구동합니다(Windows는 WGL). headless Linux 서버에서는 PYOPENGL_PLATFORM=egl 환경변수를 설정하세요.
pyglet<2 고정은 pyrender 호환성 때문입니다.
시맨틱 샘플러는 GNM 원본과 달리 TensorFlow 없이 동작하도록 numpy로 재구현했습니다 (numpy_sampler.py, 같은 h5 가중치 사용, 같은 seed → 같은 결과).

라이선스

이 프로젝트는 GPL-3.0 라이선스로 배포됩니다 (ComfyUI 본체가 GPL-3.0이며, 이 패키지는 ComfyUI의 내부 API에 결합되어 동작합니다).

vendor/gnm/에는 Google GNM (Apache-2.0)의 gnm/shape 패키지와 모델 데이터가 동봉되어 있습니다. 원본 라이선스와 변경 내역은 vendor/gnm/LICENSE와 vendor/gnm/VENDORED.md를 참고하세요.