Hadimeeee/mongle-bg-lora

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 이상 권장)

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

---

실행 방법

CLI

# 배치 — 폴더 안 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 적용됩니다.