koriweb
a3f63e56e2
- 10_Wiki/Comfyui/: ComfyUI docs generated via /wikify - 00_Raw/_youtube/: /youtube extraction outputs - Move some 00_Raw originals into 10_Wiki/Topics_meeting; remove empty canvases and stray files Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
91 lines
5.2 KiB
Markdown
91 lines
5.2 KiB
Markdown
---
|
|
id: images-latents-and-masks---comfyui
|
|
title: "Images, Latents, and Masks - ComtyUI"
|
|
category: "10_Wiki/Topics"
|
|
status: "draft"
|
|
verification_status: "conceptual"
|
|
canonical_id: ""
|
|
aliases: []
|
|
duplicate_of: ""
|
|
source_trust_level: "B"
|
|
confidence_score: 0.8
|
|
created_at: 2026-05-20
|
|
updated_at: 2026-05-20
|
|
review_reason: ""
|
|
merge_history: []
|
|
tags: ["web", "wikify"]
|
|
raw_sources: ["https://docs.comfy.org/custom-nodes/backend/images_and_masks"]
|
|
applied_in: []
|
|
github_commit: ""
|
|
---
|
|
|
|
# [[Images, Latents, and Masks - ComfyUI]]
|
|
|
|
## 🎯 한 줄 통찰 (One-line insight)
|
|
ComfyUI 백엔드 개발을 위한 핵심 데이터 타입인 [[IMAGE]], [[MASK]], [[LATENT]]의 구조적 차이와 [[torch.Tensor]] 조작법에 대한 기술 명세.
|
|
|
|
## 🧠 핵심 개념 (Core concepts)
|
|
- **[[IMAGE]] 구조**: $[B, H, W, C]$ 형태를 가지며 $C=3$인 채널 마지막(channel last) 방식의 [[torch.Tensor]] 데이터 타입.
|
|
- **[[MASK]] 구조**: $[B, H, W]$ 형태를 가지며, 0 또는 1의 값을 통해 특정 연산 범위를 지정하는 데이터 타입.
|
|
- **[[LATENT]] 구조**: `samples` 키에 $[B, C, H, W]$ ($C=4$) 형태의 데이터를 담고 있는 [[dict]] 타입.
|
|
- **데이터 변환**: [[PIL.Image]]와 [[torch.Tensor]] 간의 포맷 전환 및 채널 순서(channel first vs last) 관리의 중요성.
|
|
|
|
## 🧩 추출된 패턴 (Extracted patterns)
|
|
- **차원 확장 전략**: [[MASK]] 사용 시 $[B, H, W, C]$ 형태를 맞추기 위해 `unsqueeze(-1)`(C 차원) 및 `unsqueeze(0)`(B 차원)을 사용하는 패턴.
|
|
- **데이터 정규화**: [[LoadImage]] 노드에서 알파 채널을 활용하여 [[MASK]]를 생성할 때 $[0, 1]$ 범위로 정규화하고 반전시키는 프로세스.
|
|
- **채널 우선순위의 상이성**: [[LATENT]]는 channel first($[B, C, H, W]$) 형식을 따르지만, [[IMAGE]]는 channel last($[B, H, W, C]$) 형식을 따름.
|
|
|
|
## 📖 세부 내용 (Details)
|
|
|
|
### 🖼️ Images
|
|
- **데이터 구조**: `torch.Tensor` 형태이며, shape은 $[B, H, W, C]$ ($C=3$)입니다.
|
|
- **주의 사항**: 연산 효율을 위해 일부 PyTorch 연산은 $[B, C, H, W]$ (channel first) 형식을 기대할 수 있으므로 주의가 필요합니다.
|
|
- **포맷 변환**: 이미지를 저장하거나 불러올 때 [[PIL.Image]] 포맷으로의 변환이 필요합니다.
|
|
|
|
### 🖼️ Working with PIL.Image
|
|
- 이미지 로드 및 저장을 위해 `from PIL import Image, ImageOps`를 사용합니다.
|
|
|
|
### 🎭 Masks
|
|
- **데이터 구조**: `torch.Tensor` 형태이며, shape은 $[B, H, W]$입니다.
|
|
- **값의 의미**:
|
|
- 이진 값(0 또는 1): 특정 픽셀이 연산 대상인지 지정.
|
|
- 0과 1 사이의 값: 투명도 조절, 필터 조정, 레이어 합성 등을 위한 마스킹 범위(extent)를 나타냄.
|
|
|
|
#### [[Masks from the Load Image Node]]
|
|
- **생성 원리**: `LoadImage` 노드는 이미지의 알파 채널(RGBA의 'A')을 사용하여 [[MASK]]를 생성합니다.
|
|
- **정규화 과정**: 알파 채널 값을 $[0, 1]$ 범위(`torch.float32`)로 정규화한 후 반전시킵니다.
|
|
- **예외 케이스**: JPEG와 같이 알파 채널이 없는 경우, `LoadImage`는 $[1, 64, 64]$ 크기의 기본 마스크를 생성합니다.
|
|
|
|
#### [[Understanding Mask Shapes]]
|
|
- **차원 특성**: [[numpy]]나 [[PIL]]과 달리, 마스크는 채널 차원이 생략된 2D 배열($[H, W]$)로 표현되는 경우가 많습니다. 따라서 배치 단위의 마스크는 $[B, H, W]$의 3차원을 가집니다.
|
|
- **Shape 매칭 기법**:
|
|
- $C$ 차원 확장: `unsqueeze(-1)`를 사용하여 $[B, H, W, 1]$ 생성.
|
|
- $B$ 차원 확장: `unsqueeze(0)`를 사용하여 배치 차원 추가.
|
|
- **권장 사항**: 노드가 마스크를 입력받을 때 `len(mask.shape)`를 확인하는 것이 좋습니다.
|
|
|
|
### 🧬 Latents
|
|
- **데이터 구조**: `dict` 형태이며, `samples` 키에 데이터가 저장됩니다.
|
|
- **형태**: $[B, C, H, W]$ (여기서 $C=4$)의 shape을 가집니다.
|
|
- **특징**: [[LATENT]]는 channel first 형식을 따릅니다.
|
|
|
|
## ⚖️ 모동 및 업데이트 (Contradictions & updates)
|
|
- **상충 정보**: [[IMAGE]]는 channel last($[B, H, W, C]$)이고, [[LATENT]]는 channel first($[B, C, H, W]$)임이 명시되어 있어 두 타입 간의 구조적 차이를 주의해야 합니다.
|
|
|
|
## 🛠️ 적용 사례 (Applied in summary)
|
|
- **노드 출력 구현**: 노드의 출력이 단일 텐서인 경우, 반드시 `(image,)` 형태로 반환해야 함을 명시함.
|
|
- **데이터 처리**: [[LoadImage]] 노드를 통한 알파 채널 기반 마스크 생성 및 정규화 프로세스.
|
|
|
|
## ✅ 검증 상태 및 신뢰도
|
|
- **상태:** draft
|
|
- **검증 단계:** conceptual
|
|
- **출처 신뢰도:** B (Primary Source — 웹사이트 본문 직접 추출)
|
|
- **중복 검사 결과:** 신규 생성 (New discovery)
|
|
|
|
## 🔗 관련 문서 링크 (Related document links)
|
|
- [[torch.Tensor]] : 모든 데이터 타입의 기초가 되는 클래스.
|
|
- [[PIL.Image]] : 이미지 로드 및 저장에 사용되는 라이mer리.
|
|
- [[LoadImage]] : 알파 채널을 통해 마스크를 생성하는 소스 노드.
|
|
- [[RGBA]] : 마스크 생성의 근거가 되는 알파 채널 포함 색상 모델.
|
|
|
|
## 📝 변경 이력 (Change history)
|
|
- 2026-05-20: Astra /wikify 로 https://docs.comfy.org/custom-nodes/backend/images_and_masks 본문에서 초안 생성. |