# Persona Live2D Part Generation Guide

이 폴더는 서연(P1) PSD v2 파츠 구조를 기준으로 P4~P7 등 다른 페르소나용 Live2D식 래스터 파츠를 만드는 작업장이다.

## 핵심 규칙

1. **시트 금지**
   - 여러 파츠를 한 이미지에 모으지 않는다.
   - `brow-left.png`, `iris-right.png`처럼 파츠 하나당 파일 하나만 생성한다.

2. **imagegen 입력은 파츠 crop**
   - 앱 렌더러는 900×1125 캔버스를 쓰지만, imagegen 참조 이미지로 전체 캔버스를 주면 작은 파츠 위치가 흔들린다.
   - 그래서 원본 파츠의 `alphaBox`를 기준으로 tight crop을 만들고, 그 crop을 `-i` 참조로 준다.
   - crop 산출물은 `docs/avatar-art/personas/source-part-crops/`에 둔다.

3. **최종 산출물은 900×1125 투명 PNG**
   - gpt-image-2 생성 크기는 16px 배수 제약이 있으므로 생성 draft는 `1024x1280`을 쓸 수 있다.
   - 최종 앱 자산은 반드시 900×1125 RGBA PNG여야 한다.
   - 생성 결과에서 실제 파츠 bbox를 잡고, 원본 `alphaBox` 크기로 resize한 뒤 같은 좌표에 paste한다.

4. **bbox 검증이 통과해야 한다**
   - 원본 `alphaBox`와 최종 파츠 bbox의 drift는 각 변 기준 2px 이내여야 한다.
   - 검증 결과는 `boxValidation`에 남긴다.
   - bbox 검증 없이 `docs/dev_dashboard.html`이나 backlog에 DONE을 쓰지 않는다.

5. **긴 머리 슬롯 주의**
   - P5/P7 같은 남성 짧은 머리 페르소나는 서연의 긴 머리 슬롯(`hair-back-*`, `hair-side-*`)을 그대로 채우면 어색할 수 있다.
   - 그래도 렌더러 좌표 계약은 유지해야 하므로, 빈 공간이 많은 파츠라도 같은 `alphaBox`에 맞춰 저장하고 미리보기에서 판단한다.

## 기본 명령

프롬프트와 큐만 갱신:

```powershell
$ErrorActionPreference = 'Stop'
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$env:PYTHONUTF8='1'
python -X utf8 docs\avatar-art\personas\run_part_imagegen.py --tier all --dry-run
```

단일 파츠 smoke:

```powershell
$env:PYTHONUTF8='1'
python -X utf8 docs\avatar-art\personas\run_part_imagegen.py --personas P4 --parts brow-sad-left --quality low --concurrency 1 --overwrite
```

핵심 얼굴 파츠 생성:

```powershell
$env:PYTHONUTF8='1'
python -X utf8 docs\avatar-art\personas\run_part_imagegen.py --personas P4 P5 P6 P7 --tier core --quality low --concurrency 4
```

전체 파츠 생성:

```powershell
$env:PYTHONUTF8='1'
python -X utf8 docs\avatar-art\personas\run_part_imagegen.py --personas P4 P5 P6 P7 --tier all --quality low --concurrency 4
```

## 산출 위치

- 프롬프트: `docs/avatar-art/personas/<P-code>/prompts/*.txt`
- 생성 raw: `docs/avatar-art/personas/<P-code>/generated-raw/*.png`
- 앱 파츠: `apps/web/public/avatar/<p-code>-live2d-generated/parts/*.png`
- 결과 요약: `docs/avatar-art/personas/generation-results.json`

## 앱 연결 전 체크

- 각 페르소나별 `parts/*.png`가 필요한 파일을 모두 갖고 있어야 한다.
- `generation-results.json`의 failed 항목이 없어야 한다.
- bbox drift가 2px를 넘는 파츠는 재생성하거나 수동 보정한다.
- `RasterBust.tsx`에 새 art set을 등록하기 전에 neutral/sad/warm/anxious preview를 만든다.

## 시각 QA 필수

좌표 검증만으로 DONE 처리하지 않는다. 사람처럼 보이는지 직접 합성 프리뷰를 보고 판정한다.

```powershell
$env:PYTHONUTF8='1'
python -X utf8 docs\avatar-art\personas\visual_qa.py --personas P4 P5 P6 P7
```

산출물:

- `docs/avatar-art/personas/visual-qa/p*-neutral-app-composite.png`
- `docs/avatar-art/personas/visual-qa/p*-sad-app-composite.png`
- `docs/avatar-art/personas/visual-qa/p*-parts-contact-sheet.png`

반드시 볼 것:

- 눈동자 좌우 위치, 홍채/동공/하이라이트가 서로 어긋나지 않는지
- 얼굴이 외계인처럼 비대칭이거나 이마/턱이 과장되지 않는지
- chroma-key 초록 헤이즈, 엣지 블리딩, 검은/녹색 찌꺼기가 남지 않았는지
- 표정 파츠가 감정과 맞는지. sad는 눈물/울상 눈썹/입이 모두 보여야 한다.
- P5/P7 남성 페르소나는 긴 머리 실루엣과 여성 리본을 금지한다.

남성 페르소나 보정:

```powershell
$env:PYTHONUTF8='1'
python -X utf8 docs\avatar-art\personas\apply_visual_overrides.py
python -X utf8 docs\avatar-art\personas\visual_qa.py --personas P4 P5 P6 P7
```

`apply_visual_overrides.py`는 P5/P7의 긴 뒷머리·긴 사이드 슬롯을 빈 투명 파츠로 만들고, P5의 리본형 outfit을 남성 교복형 outfit으로 교체한다. 또한 저알파 chroma-key 초록 엣지 픽셀을 정리한다. 이 보정 없이 P5/P7을 앱에 연결하지 않는다.