ComfyUI-GNM

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

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

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

설치

1. 이 폴더(ComfyUI-GNM)를 ComfyUI/custom_nodes/에 복사합니다.

2. 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를 참고하세요.