Dansori_EQ/docs/HANDOFF.md

# DansoriEQ Live2D Character HANDOFF

> ⚠️ **상태 알림 (2026-07-04 저장소 정리)**: 이 문서 상당 부분은 이전 **LeeSoriV2** 하이브리드 퍼펫 기준의 히스토리다. **현재 라이브 설정(`characters.json`)은 `LeeSoriDance`(Solo Dance 3 전신 리그)를 사용**하며, `LeeSoriV2`·`LeeSoriExtended`·`LeeSoriUpper` 및 옛 QA 자산은 정리로 **삭제**되었다. 경로 루트도 옛 `D:\Work_AI\Dansori` → 현재 `D:\Project\Dansori_EQ`로 이동. **§2 = 현재 상태, §3 이하 = 히스토리.**

작성일: 2026-07-04
작업 루트: `D:\Project`
앱 프로젝트: `D:\Project\Dansori_EQ`
캐릭터 자료 루트: `D:\Project\Dansori_Characters`

이 문서는 세션이 바뀌어도 Live2D/캐릭터 통합 작업을 바로 이어가기 위한 인수인계 문서다. 더 상세한 변경 로그는 `docs/LIVE2D_CHARACTER_INTEGRATION_PLAN.md`에 누적되어 있다.

## 1. 현재 목표

DansoriEQ는 Equalizer APO와 AI 프롬프트를 이용한 Auto AI EQ WPF 앱이다. 최종 목표는 앱 오른쪽 영역에 단순 PNG가 아니라 Live2D에 가까운 동적 캐릭터를 탑재하는 것이다.

현재는 실제 Cubism `.model3.json`이 아니라 WebView2 기반 HTML/CSS/JS 호스트에서 PNG 파츠를 겹쳐 움직이는 하이브리드 퍼펫 방식으로 구현 중이다. 이 방식은 빠르게 WPF 안에서 구도, 캐릭터성, 파츠 움직임을 검증하기 위한 중간 단계다.

## 2. 현재 적용 상태 (2026-07-04 갱신)

현재 앱은 이소리 **`LeeSoriDance`** 퍼펫(Solo Dance 3 기반 전신 리그)을 사용한다. `characters.json`이 이소리를 `LeeSoriDance`로 가리킨다.

- 설정: `src\DansoriEQ.App\Assets\Live2DHost\characters.json`
- rig: `../Characters/Puppets/LeeSoriDance/rig.json`
- imageBase: `../Characters/Puppets/LeeSoriDance/Images/`
- poseBase: `../Characters/Puppets/LeeSoriDance/Gestures/dance/solo3/`

`LeeSoriDance/rig.json`이 로드하는 bone(전신): `base, pelvis, chest, upperarm_l/r, forearm_l/r, hand_l/r, thigh_l/r, shin_l/r, foot_l/r, head`.

신 버전 이소리 기준 시트(참고): `D:\Project\Dansori_Characters\LeeSori_Live2D\03_Assets\Reference\sori_sheet.png`.

> ⚠️ 이 아래(§3~§14)는 이전 **`LeeSoriV2`** 하이브리드 퍼펫 작업 기록(히스토리)이다. `LeeSoriV2`·`LeeSoriExtended`·`LeeSoriUpper` 및 관련 QA 이미지는 2026-07-04 저장소 정리 때 **삭제**되어 해당 경로는 더 이상 존재하지 않는다. 프레이밍 등 실제 현재 값은 `style.css`를 기준으로 확인한다(옛 `right:6.5%/bottom:-65%/width:87%`는 V2 값).

현재 프레이밍은 사용자 확인으로 “비율과 위치가 정확”하다고 승인됨.

- 파일: `D:\Project\Dansori_EQ\src\DansoriEQ.App\Assets\Live2DHost\style.css`
- 값:
  - `right: 6.5%`
  - `bottom: -65%`
  - `width: 87%`
- 의도: 무릎 위와 왼손 끝 중간쯤부터 머리 위 끝까지 보이는 knee-up 프레이밍.

## 3. 현재 LeeSoriV2 Rig 상태

현재 `rig.json`에서 로드되는 bone은 다음만 남아 있다.

- `base`
- `chest`
- `upperarm_r`
- `hand_r`
- `head`

제거된 animated bone:

- `legs`
- `upperarm_l`
- `hand_l`

제거 이유:

- `legs`: 바지 양쪽 녹색 라인이 base 이미지와 animated legs 레이어에서 중복 표시되어 한 줄/두 줄로 보이는 현상이 있었다.
- `upperarm_l`, `hand_l`: 왼손은 주머니에 들어간 정적 포즈라 따로 움직이면 어색했다. 현재는 base 이미지에만 남겨 정적으로 보이게 했다.

주의:

- `Images` 폴더 안에는 이전에 생성된 `leesori_v2_legs.png`, `leesori_v2_arm_l.png`, `leesori_v2_hand_l.png` 파일이 남아 있을 수 있다.
- 하지만 `rig.json`에서 참조하지 않으면 WebView는 해당 이미지를 생성/표시하지 않는다.
- 다음 작업자는 파일 존재만 보고 활성 파츠라고 판단하지 말고 반드시 `rig.json` 기준으로 확인해야 한다.

## 4. 최근 사용자 피드백

최신 사용자 피드백:

- “비율과 위치는 정확합니다.”
- “바지라인 외곽의 녹색이 한줄/두줄 되는건 여전히 동일하게 남아있고, 자세히 보면 왼손도 약간 어색합니다.”

이에 대해 마지막으로 수행한 조치:

- accepted 프레이밍은 유지했다.
- `legs`, `upperarm_l`, `hand_l` animated bone을 제거했다.
- 움직임은 `chest`, `upperarm_r`, `hand_r`, `head` 중심으로 제한했다.
- 빌드 출력 rig에서도 제거가 반영되었음을 확인했다.

다음 세션 첫 작업은 사용자가 실행 확인 후 녹색 라인 문제가 실제로 사라졌는지 듣는 것이다. 만약 여전히 보이면, 원인은 rig 중복이 아니라 원본 이미지 자체의 바지 녹색 라인/보라색 가장자리 또는 chest/right-arm 파츠 마스크가 하체 라인 일부를 포함하는 문제일 가능성이 높다.

## 5. 검증된 빌드 상태

마지막 검증 결과:

- `dotnet build .\DansoriEQ.sln`: 성공, 경고 0, 오류 0
- `dotnet test .\DansoriEQ.sln --no-build`: 성공, 15/15 통과
- 빌드 출력 CSS에 accepted 프레이밍 값 반영 확인
- 빌드 출력 `LeeSoriV2/rig.json`에서 `legs`, `upperarm_l`, `hand_l`이 더 이상 참조되지 않음

실행 파일:

- `D:\Project\Dansori_EQ\src\DansoriEQ.App\bin\Debug\net8.0-windows\DansoriEQ.App.exe`

## 6. 주요 구현 파일

WPF 통합:

- `D:\Project\Dansori_EQ\src\DansoriEQ.App\MainWindow.xaml`
- `D:\Project\Dansori_EQ\src\DansoriEQ.App\MainWindow.xaml.cs`
- `D:\Project\Dansori_EQ\src\DansoriEQ.App\Controls\Live2DCharacterView.xaml`
- `D:\Project\Dansori_EQ\src\DansoriEQ.App\Controls\Live2DCharacterView.xaml.cs`

WebView 호스트:

- `D:\Project\Dansori_EQ\src\DansoriEQ.App\Assets\Live2DHost\index.html`
- `D:\Project\Dansori_EQ\src\DansoriEQ.App\Assets\Live2DHost\style.css`
- `D:\Project\Dansori_EQ\src\DansoriEQ.App\Assets\Live2DHost\characterHost.js`
- `D:\Project\Dansori_EQ\src\DansoriEQ.App\Assets\Live2DHost\characters.json`

캐릭터 퍼펫:

- `D:\Project\Dansori_EQ\src\DansoriEQ.App\Assets\Characters\Puppets\LeeSoriV2\rig.json`
- `D:\Project\Dansori_EQ\src\DansoriEQ.App\Assets\Characters\Puppets\LeeSoriV2\Images\`
- `D:\Project\Dansori_EQ\src\DansoriEQ.App\Assets\Characters\Live2DPreview\leesori.png`

작업 스크립트:

- `D:\Project\Dansori_Characters\tools\build_leesori_v2_puppet.py`
- `D:\Project\Dansori_Characters\tools\update_leesori_v2_framing.py`
- `D:\Project\Dansori_Characters\tools\fix_leesori_v2_outline_and_left_hand.py`

QA 이미지:

- `D:\Project\Dansori_EQ\src\DansoriEQ.App\Assets\Characters\Puppets\LeeSoriV2\qa_source_black.png`
- `D:\Project\Dansori_EQ\src\DansoriEQ.App\Assets\Characters\Puppets\LeeSoriV2\qa_view_390x600_knee_upper.png`
- `D:\Project\Dansori_EQ\src\DansoriEQ.App\Assets\Characters\Puppets\LeeSoriV2\qa_view_390x600_v3_clean_outline.png`

## 7. 앱 동작 관련 이미 완료된 변경

- WebView2 Live2D placeholder host를 WPF 앱 우측 캐릭터 영역에 통합했다.
- `Live2DCharacterView`는 virtual host mapping을 사용해 로컬 assets를 로드한다.
- `characterHost.js`는 `characters.json`을 읽고 `rig.json`의 bones를 DOM 이미지 레이어로 생성한다.
- CSS keyframes로 idle/thinking/success/error 상태 애니메이션을 적용한다.
- 캐릭터 상태는 `MainWindow.xaml.cs`에서 AI 작업 흐름에 맞춰 `idle`, `thinking`, `success`, `error`로 전환된다.
- 앱 시작 시 EQ는 비활성 상태로 시작되도록 변경했다.
  - `ActiveToggle IsChecked="False"`
  - `_bypassed = true`

## 8. 이전 시도와 폐기/보존 상태

기존 퍼펫 폴더:

- `LeeSori`: 초기 Canvas/FK 참고용
- `LeeSoriUpper`: 구 버전 상반신 기반. 비율은 좋았으나 손목/하체가 원본에서 잘림.
- `LeeSoriExtended`: AI로 구 버전 전신 확장. 클리핑은 해결했으나 신 버전 이소리가 아니어서 현재 사용하지 않음.
- `LeeSoriV2`: 현재 적용 중. 신 버전 sheet 기반.

중요 판단:

- 신 버전 이소리는 AI 재생성보다 `sori_sheet.png`에서 직접 정면 전신 포즈를 크롭해 쓰는 방식이 캐릭터 일관성이 가장 좋았다.
- 사용자가 승인한 비율/위치는 `LeeSoriV2 + knee-up CSS`다.

## 9. 남은 작업 우선순위

1. 사용자 실행 확인 받기

- 현재 빌드 실행 후 바지 녹색 라인 한 줄/두 줄 문제가 사라졌는지 확인해야 한다.
- 왼손이 더 자연스러워졌는지 확인해야 한다.
- 비율/위치는 이미 승인됐으므로 임의로 건드리지 말 것.

2. 녹색 외곽선 문제가 남아 있을 경우

가능 원인:

- 원본 `sori_sheet.png`의 바지 라인 주변에 이미 보라/녹색 가장자리 픽셀이 존재한다.
- `chest` 또는 `upperarm_r` 파츠 마스크가 바지 라인까지 일부 포함한다.
- base 이미지 자체 가장자리 알파 정리가 부족하다.

권장 조치:

- 먼저 `rig.json`에서 `chest`, `upperarm_r`, `hand_r`, `head`를 하나씩 임시 제거해 원인 파츠를 분리 확인한다.
- 원인 파츠가 있으면 해당 파츠 마스크를 더 좁힌다.
- 그래도 남으면 `leesori_v2_base.png`에서 바지 외곽 라인의 색상/알파를 직접 정리한다.
- 최후 수단으로 하체 라인 영역은 아예 정적 base만 쓰고 상체 레이어도 허리 위까지만 제한한다.

3. 애니메이션 품질 개선

현재는 단순 CSS transform 기반이다. 다음 개선은 다음 순서가 좋다.

- idle: 머리와 오른손만 아주 미세하게 움직이기
- thinking: 머리 기울임 + 오른손/상체 약간 움직임
- success: 과한 점프보다 고개/어깨/오른손 반응
- error: 흔들림은 작게, 얼굴/상체 위주

주의:

- 왼손과 하체는 현재 정적 유지가 자연스럽다.
- 상체 scaleY가 너무 크면 바지/허리 라인에서 이중선이 다시 생길 수 있다.

4. Haruka/Isabel/Noeul 생성

최초 목표에는 `LeeSori_Live2D`를 참고해 `Haruka_Live2D`, `Isabel_Live2D`, `Noeul_Live2D` 생성이 포함되어 있다. 아직 본격 진행하지 않았다.

권장 프로세스:

- 먼저 각 캐릭터의 authoritative sheet/reference가 있는지 확인한다.
- 없으면 ChatGPT/imagegen으로 sheet부터 만든다.
- LeeSoriV2처럼 sheet의 정면 포즈를 직접 크롭해 identity drift를 줄인다.
- 각 캐릭터별 `Puppets/<Name>V1/rig.json`과 `Images/`를 만든다.
- `characters.json`에 puppet 정보를 추가한다.
- selector에서 캐릭터 전환 시 rig가 정상 로드되는지 확인한다.

5. 진짜 Live2D Cubism 전환

현재 방식은 “Live2D-like HTML puppet”이다. 최종 목표가 실제 Live2D라면 다음이 필요하다.

- Cubism Editor 또는 대체 rigging pipeline 결정
- PSD 수준 파츠 분리 필요
- `.model3.json`, `.moc3`, texture atlas, physics 설정 필요
- WPF에서 Cubism SDK를 직접 붙일지, WebView에서 Cubism Web SDK를 로드할지 결정

현실적인 다음 단계:

- 지금은 하이브리드 퍼펫으로 캐릭터 룩/위치/상태 애니메이션을 먼저 확정한다.
- 이후 승인된 아트와 파츠 정의를 Cubism용 PSD/파츠 명세로 정리한다.

## 10. 재개 시 권장 첫 명령

현재 상태 확인:

```powershell
Get-Content -LiteralPath 'D:\Project\Dansori_EQ\src\DansoriEQ.App\Assets\Characters\Puppets\LeeSoriV2\rig.json'
Select-String -LiteralPath 'D:\Project\Dansori_EQ\src\DansoriEQ.App\Assets\Live2DHost\style.css' -Pattern 'right: 6.5|bottom: -65|width: 87'
```

빌드/테스트:

```powershell
cd D:\Project\Dansori_EQ
dotnet build .\DansoriEQ.sln
dotnet test .\DansoriEQ.sln --no-build
```

실행 파일:

```powershell
D:\Project\Dansori_EQ\src\DansoriEQ.App\bin\Debug\net8.0-windows\DansoriEQ.App.exe
```

## 11. 작업 시 주의사항

- 사용자가 승인한 `LeeSoriV2` 프레이밍은 바꾸지 말 것. 바꿔야 한다면 반드시 이유와 QA 이미지를 먼저 제시한다.
- `LeeSoriExtended`로 되돌리지 말 것. 구 버전 이소리다.
- `sori_sheet.png`가 신 버전 authoritative source다.
- 이미지 생성 AI를 쓸 때는 identity drift가 쉽게 생기므로 원본 sheet 직접 크롭/마스크 편집을 우선한다.
- 앱 Assets 변경 후 반드시 `dotnet build`를 해서 `bin\Debug\net8.0-windows\Assets` 출력까지 갱신해야 한다.
- 사용자는 FHD 모니터 기준에서 앱을 확인하므로 창 크기와 캐릭터 영역 변경은 신중히 해야 한다.

## 12. 2026-07-04 추가 조치: V3 파일명과 WebView 캐시 차단

세션 한도가 남아 추가로 진행한 내용:

- 활성 LeeSoriV2 파츠 파일명을 `leesori_v2_v3_*`로 변경했다.
- `rig.json`은 이제 `leesori_v2_v3_base.png`, `leesori_v2_v3_chest.png`, `leesori_v2_v3_arm_r.png`, `leesori_v2_v3_hand_r.png`, `leesori_v2_v3_head.png`만 참조한다.
- `characterHost.js`에서 puppet 이미지 URL에 `?v=`를 붙여 WebView2 이미지 캐시가 이전 파츠를 보여주는 상황을 막았다.
- 승인된 프레이밍 값은 유지했다: `right: 6.5%`, `bottom: -65%`, `width: 87%`.
- 검증: `node --check` 통과, `dotnet build` 성공, `dotnet test` 15/15 통과.

다음 세션 첫 확인:

- 사용자가 새 빌드를 실행한 뒤 바지 녹색 라인의 한 줄/두 줄 반복이 사라졌는지 확인한다.
- 여전히 남으면 캐시/rig 문제가 아니라 원본 이미지의 색상 가장자리 또는 현재 움직이는 `chest`/`upperarm_r`/`hand_r` 마스크 경계 문제로 보고, 해당 파츠를 하나씩 임시 제거해 원인을 분리한다.


## 13. 2026-07-04 추가 조치: 호흡 애니메이션 축소

- 바지/허리 경계의 미세한 이중선 가능성을 줄이기 위해 `chestBreath`와 `chestThinking`에서 `scaleY`를 제거했다.
- 상체 호흡은 `translateY(-1px)`만 사용한다.
- 오른팔 idle 회전량도 `-0.6deg` / `0.4deg`로 줄였다.
- 승인된 프레이밍 값은 그대로 유지했다.
- 검증: `dotnet build` 성공, `dotnet test` 15/15 통과.


## 14. 2026-07-04 추가 조치: LeeSoriV2 허리 자연화

- 사용자 요청으로 과도하게 잘록한 허리 실루엣만 자연스럽게 수정했다.
- 이전 소스는 `LeeSoriV2/leesori_v2_source_pre_waist_fix.png`로 보존했다.
- AI 편집 후보는 전체 교체하지 않고 복부/허리밴드 주변 패치 소스로만 사용했다. 얼굴, 머리, 손, 전체 포즈는 원본을 유지했다.
- 수정된 기준 소스: `LeeSoriV2/leesori_v2_source.png`.
- 재생성된 활성 파츠: `leesori_v2_v3_*`.
- QA: `qa_source_waist_patch_black.png`, `qa_view_390x600_v3_clean_outline.png`.
- 검증: `dotnet build` 성공, `dotnet test` 15/15 통과.