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. 재개 시 권장 첫 명령

현재 상태 확인:

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'

빌드/테스트:

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

실행 파일:

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 통과.