README.md

# feed_pipeline

퀘스트 완료 메시지 + 캐릭터 누끼 이미지 → 몽글마을 픽셀아트 피드 이미지 생성 패키지.

---

## 폴더 구조

```
feed_pipeline/
├── __init__.py      ← 핵심 함수 export
├── pipeline.py      ← 핵심 로직 (캐릭터 생성 + 배경 생성 + 합성)
├── run.py           ← CLI 진입점
└── README.md        ← 이 파일
```

결과는 `outputs/feed/{name}/` 에 저장됩니다.

---

## 파이프라인 흐름

```
result_nobg.png (image_pipeline 결과물)  +  한국어 퀘스트 메시지
        │
        ▼
[STEP 0] Qwen2-VL — 퀘스트 번역
         → action: 캐릭터 포즈 설명  (예: "running with arms swinging")
         → scene:  배경 환경 설명    (예: "fluffy cloud meadow path")
        │
        ▼
[STEP 1] img2img (strength=0.75)
         result_nobg.png → 픽셀아트 캐릭터 (흰 배경)
         캐릭터 LoRA + action 프롬프트 + appearance.json 외형 정보
        │
        ▼
[STEP 2] rembg — 픽셀아트 캐릭터 누끼
        │
        ▼
[STEP 3] text2img — 퀘스트 배경 장면 생성
         배경 LoRA + scene 프롬프트 + 랜덤 시드 (이미지마다 다른 배경)
        │
        ▼
[STEP 4] 합성 — 캐릭터를 배경 위에 배치 (그림자 포함)
        │
        ▼
[STEP 5] 인페인팅 블렌딩 — 캐릭터 경계 자연스럽게 처리
        │
        ▼
     {name}_feed.png  ★ 최종 결과
```

---

## 사용 모델

**HuggingFace 자동 다운로드** (첫 실행 시 캐시에 저장):

| 모델 | 용도 | VRAM |
|------|------|------|
| `stabilityai/stable-diffusion-xl-base-1.0` | 기반 생성 모델 | ~8GB |
| `latent-consistency/lcm-lora-sdxl` | 8스텝 빠른 생성 | (LoRA) |
| `Hadimeeee/mongle-character-lora` | 몽글 픽셀아트 캐릭터 스타일 LoRA | (LoRA) |
| `Hadimeeee/mongle-bg-lora` | 몽글 픽셀아트 배경 스타일 LoRA | (LoRA) |
| `Qwen/Qwen2-VL-7B-Instruct` | 퀘스트 한→영 번역 | ~8GB (8bit) |

> 로컬에 모델 폴더가 없어도 됩니다. 모두 HuggingFace에서 자동으로 받아옵니다.

---

## 환경 요구사항

- Python 3.10+
- CUDA GPU (VRAM 12GB 이상 권장)

```bash
pip install torch diffusers transformers accelerate
pip install rembg pillow numpy
pip install bitsandbytes qwen-vl-utils
pip install huggingface_hub
```

---

## 실행 방법

### CLI

```bash
# 배치 — 폴더 안 result_nobg.png 전체 처리
python -m feed_pipeline.run --batch path/to/folder --quest "오늘 도서관에서 책 한 권을 다 읽었어요" --name run_01

# 단일 이미지
python -m feed_pipeline.run --input path/to/result_nobg.png --quest "공원에서 30분 달리기를 완료했어요"

# 영어 직접 입력 (VLM 번역 생략, 빠름)
python -m feed_pipeline.run --batch path/to/folder --quest-en "running in the park" --name run_02

# 처음 n장만 테스트
python -m feed_pipeline.run --batch path/to/folder --quest "..." --limit 3 --name test_01
```

> `python -m feed_pipeline.run` 은 **레포 루트**에서 실행합니다.

### 입력 폴더 구조

`--batch` 폴더 안에 아래처럼 `result_nobg.png` 가 있으면 됩니다.  
`appearance.json` 이 같은 폴더에 있으면 캐릭터 외형 정보로 자동 반영됩니다.

```
batch_folder/
├── 01/
│   ├── result_nobg.png   ← 필수 (image_pipeline 결과물)
│   └── appearance.json   ← 선택 (외형 자동 반영)
├── 02/
│   ├── result_nobg.png
│   └── appearance.json
└── ...
```

---

## 결과 파일

```
outputs/feed/{name}/
├── {폴더명}_char.png      ← STEP 1 픽셀아트 캐릭터 (흰 배경)
├── {폴더명}_feed.png      ← 최종 피드 이미지 ★
└── {폴더명}_compare.png   ← 원본 / 캐릭터 / 배경 / 결과 4단 비교
```

---

## 파라미터 상세

| 파라미터 | 기본값 | 설명 |
|----------|--------|------|
| `--strength` | `0.75` | 캐릭터 img2img 강도. 높을수록 원본에서 많이 변형됨 |
| `--char-scale` | `1.0` | 캐릭터 LoRA 강도 |
| `--bg-scale` | `1.0` | 배경 LoRA 강도 |
| `--inpaint-str` | `0.35` | 블렌딩 강도. 낮을수록 합성 경계만 살짝 처리 |
| `--blend-mode` | `inpaint` | `inpaint`=경계만 / `img2img`=전체 이미지 블렌딩 |
| `--steps` | `8` | 추론 스텝 수 (LCM 8스텝 기본) |
| `--seed` | `42` | 캐릭터 생성 시드 (배경은 이미지마다 자동 랜덤) |
| `--limit` | `0` | 배치 처리 최대 장수 (`0`=전체) |
| `--name` | `run_01` | 출력 폴더 이름 |

---

## 주요 파일 설명

### `pipeline.py`

핵심 생성 함수들이 정의된 파일입니다.

- `load_pipelines()` — SDXL txt2img + img2img + inpaint 파이프라인 로드 (UNet 공유로 VRAM 절약)
- `generate_character()` — img2img로 픽셀아트 캐릭터 생성
- `remove_bg()` — rembg로 캐릭터 누끼
- `generate_background()` — text2img로 배경 장면 생성
- `composite()` — 캐릭터를 배경 위에 합성 (그림자 포함, 크기 자동 조정)
- `inpaint_blend()` — 캐릭터 경계 인페인팅 블렌딩
- `img2img_blend()` — 전체 이미지 img2img 블렌딩 (대안)

### `run.py`

`python -m feed_pipeline.run` 으로 실행하는 CLI 진입점입니다.

### `__init__.py`

`pipeline.py` 의 핵심 함수들을 패키지 레벨로 export합니다.

---

## 주의사항

- `result_nobg.png` 는 `image_pipeline` 의 출력물을 사용합니다.
- 배경은 이미지마다 랜덤 시드가 적용되어 항상 다른 배경이 생성됩니다.
- 첫 실행 시 모델 다운로드로 시간이 걸립니다 (합계 약 15~20GB).
- LCM 모드에서 `guidance_scale` 은 자동으로 1.5 적용됩니다.