Initial Dansori EQ workspace

docs/HANDOFF.md

@@ -0,0 +1,289 @@
+# DansoriEQ Live2D Character HANDOFF
+
+작성일: 2026-07-04
+작업 루트: `D:\Work_AI\Dansori`
+앱 프로젝트: `D:\Work_AI\Dansori\DansoriEQ`
+캐릭터/빌드 문서 루트: `D:\Work_AI\Dansori\Characters_Build_Docs`
+
+이 문서는 세션이 바뀌어도 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. 현재 적용 상태
+
+현재 앱은 신 버전 이소리 시트를 기준으로 만든 `LeeSoriV2` 퍼펫을 사용한다.
+
+신 버전 기준 원본:
+
+- `D:\Work_AI\Dansori\Characters_Build_Docs\LeeSori_Profile\03_Assets\Reference\sori_sheet.png`
+
+앱에 연결된 퍼펫:
+
+- `D:\Work_AI\Dansori\DansoriEQ\src\DansoriEQ.App\Assets\Characters\Puppets\LeeSoriV2\rig.json`
+- `D:\Work_AI\Dansori\DansoriEQ\src\DansoriEQ.App\Assets\Characters\Puppets\LeeSoriV2\Images\`
+
+현재 `characters.json`은 이소리를 `LeeSoriV2`로 가리킨다.
+
+- `D:\Work_AI\Dansori\DansoriEQ\src\DansoriEQ.App\Assets\Live2DHost\characters.json`
+- LeeSori rig: `../Characters/Puppets/LeeSoriV2/rig.json`
+- LeeSori imageBase: `../Characters/Puppets/LeeSoriV2/Images/`
+
+현재 프레이밍은 사용자 확인으로 “비율과 위치가 정확”하다고 승인됨.
+
+- 파일: `D:\Work_AI\Dansori\DansoriEQ\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:\Work_AI\Dansori\DansoriEQ\src\DansoriEQ.App\bin\Debug\net8.0-windows\DansoriEQ.App.exe`
+
+## 6. 주요 구현 파일
+
+WPF 통합:
+
+- `D:\Work_AI\Dansori\DansoriEQ\src\DansoriEQ.App\MainWindow.xaml`
+- `D:\Work_AI\Dansori\DansoriEQ\src\DansoriEQ.App\MainWindow.xaml.cs`
+- `D:\Work_AI\Dansori\DansoriEQ\src\DansoriEQ.App\Controls\Live2DCharacterView.xaml`
+- `D:\Work_AI\Dansori\DansoriEQ\src\DansoriEQ.App\Controls\Live2DCharacterView.xaml.cs`
+
+WebView 호스트:
+
+- `D:\Work_AI\Dansori\DansoriEQ\src\DansoriEQ.App\Assets\Live2DHost\index.html`
+- `D:\Work_AI\Dansori\DansoriEQ\src\DansoriEQ.App\Assets\Live2DHost\style.css`
+- `D:\Work_AI\Dansori\DansoriEQ\src\DansoriEQ.App\Assets\Live2DHost\characterHost.js`
+- `D:\Work_AI\Dansori\DansoriEQ\src\DansoriEQ.App\Assets\Live2DHost\characters.json`
+
+캐릭터 퍼펫:
+
+- `D:\Work_AI\Dansori\DansoriEQ\src\DansoriEQ.App\Assets\Characters\Puppets\LeeSoriV2\rig.json`
+- `D:\Work_AI\Dansori\DansoriEQ\src\DansoriEQ.App\Assets\Characters\Puppets\LeeSoriV2\Images\`
+- `D:\Work_AI\Dansori\DansoriEQ\src\DansoriEQ.App\Assets\Characters\Live2DPreview\leesori.png`
+
+작업 스크립트:
+
+- `D:\Work_AI\Dansori\Characters_Build_Docs\tools\build_leesori_v2_puppet.py`
+- `D:\Work_AI\Dansori\Characters_Build_Docs\tools\update_leesori_v2_framing.py`
+- `D:\Work_AI\Dansori\Characters_Build_Docs\tools\fix_leesori_v2_outline_and_left_hand.py`
+
+QA 이미지:
+
+- `D:\Work_AI\Dansori\DansoriEQ\src\DansoriEQ.App\Assets\Characters\Puppets\LeeSoriV2\qa_source_black.png`
+- `D:\Work_AI\Dansori\DansoriEQ\src\DansoriEQ.App\Assets\Characters\Puppets\LeeSoriV2\qa_view_390x600_knee_upper.png`
+- `D:\Work_AI\Dansori\DansoriEQ\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:\Work_AI\Dansori\DansoriEQ\src\DansoriEQ.App\Assets\Characters\Puppets\LeeSoriV2\rig.json'
+Select-String -LiteralPath 'D:\Work_AI\Dansori\DansoriEQ\src\DansoriEQ.App\Assets\Live2DHost\style.css' -Pattern 'right: 6.5|bottom: -65|width: 87'
+```
+
+빌드/테스트:
+
+```powershell
+cd D:\Work_AI\Dansori\DansoriEQ
+dotnet build .\DansoriEQ.sln
+dotnet test .\DansoriEQ.sln --no-build
+```
+
+실행 파일:
+
+```powershell
+D:\Work_AI\Dansori\DansoriEQ\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 통과.
+