single-image-3d-projection

name	single-image-3d-projection
description	단일 정면 원화(마스터 PNG) → fal.ai Rodin 3D 메시 생성 → Unity 캘리브레이션 투사 베이크로 마스터를 메시 앞면에 "자연스럽게" 입힌다(뒤=네이티브, 솔리드). 핵심은 BakeProjected의 per-view 캘리브레이션(캐릭터 bbox 정렬, 가로·세로 독립) — Blender 오쏘(전체이미지 프레이밍)보다 얼굴이 안 늘어남. 평면 데칼이라 정면~¾만 자연스럽고 옆모습은 납작(천장). 트리거 — "로딘", "Rodin", "단일 이미지 3D", "정면 마스터 3D에 입히기", "얼굴 투사", "projection bake", "BakeProjected", "3D 텍스처 투사", "image-to-3D 데칼", "PNG 3D 메시".

단일 이미지 → 3D 투사 데칼 (Rodin + Unity 캘리브레이션 베이크)

한 줄: 정면 마스터 1장 → Rodin 3D 메시 → Unity BakeProjected(캘리브레이션 정렬)로 앞면=마스터·뒤=네이티브 솔리드 텍스처. 자연스러운 얼굴의 열쇠는 캘리브레이션 정합(마스터 속 캐릭터 bbox를 메시에 가로·세로 독립 정렬). 프로젝트: unity-3d-texture-projection-poc/, 코어 Assets/Poc/Editor/ProjectionBaker.cs.

비협상

• 주인님이라 부른다. 시각 결과는 항상 open <png>로 띄운다([[show-results-open-png]]).
• 투사 프리뷰는 거짓말한다(아래 ★). 실렌더로 판정하기 전 "됐다" 금지([[visual-verify-real-render]]).
• 증거 GLB·베이크 PNG·렌더 삭제 금지. 배포 자산 불가침.

채택 결론 (2026-07-02)

• Rodin 작품이 최고(주인님 판정). Rodin/Hunyuan/TRELLIS 퀄리티 차이 미미. → 신규는 Rodin(fal.ai Hyper3D) 로 간다.
• 6개 모델(rodin_no_tapose·v2·hunyuan·trellis·legacy rodin·regular_hyper) 전부 이 파이프라인으로 앞면 자연 얼굴 확보.

★1. 3D 메시 = fal.ai Rodin

# scratchpad/rodin_gen.py 패턴. venv=scratchpad/falenv, 키=~/.config/vtube/fal_api_key
# fal-ai/hyper3d/rodin: quality=high, material="Shaded", use_hyper=True, TAPose=False(포즈 보존)
# addons HighPack(4K)는 아티팩트 못 고침 — 기본으로 충분. Hunyuan(fal-ai/hunyuan3d/v2)·TRELLIS도 대안.

입력은 전신 정면(흉상이면 다리 환각). 결과 GLB엔 네이티브 텍스처 임베드됨(diffuse/shaded 이미지).

★2. 자연 얼굴의 핵심 = BakeProjected 캘리브레이션 (Blender 오쏘 아님)

ProjectionBaker.BakeProjected(outFile, "front=<masterPath>", neutralFallback=false, priorityFill=false)

• CalibrationByView["front"] = (uL, uR, imgTop, imgBottom) = 마스터 이미지 안에서 캐릭터가 차지하는 bbox(yuki 마스터 = 0.317, 0.673, 0.016, 0.988). 이 캐릭터 영역만 메시 bounds에 가로·세로 독립 정렬 → 얼굴이 머리에 딱 맞음.
• 캘리브레이션은 마스터-상대(이미지 속 캐릭터 위치)라 어느 메시에도 그대로 적용됨(메시 bounds에 매핑). 단 방향(아래 ★)은 메시마다 확인.
• 앞면만: dot(worldNormal, -viewDir) > 0.15 + MeshCollider 레이캐스트 오클루전. neutralFallback=false → 나머지는 네이티브 텍스처(뒤통수 등). 솔리드 메시 → 어느 각도서 봐도 안 뚫림.
• Blender 오쏘 투사(scratchpad/blender_project_bake.py)는 열등: 마스터 전체 이미지(여백 포함) 를 메시에 맞춰 캐릭터가 크게·넓게 → 얼굴 늘어남. 단일 오쏘라 가로·세로 독립 정렬 불가. 참고용으로만 보존.

★3. 함정들 (이번 세션 실증 — 재현 방지)

1. 투사 프리뷰는 거짓말: 카메라가 향한 면에 마스터 얼굴이 찍히니, 뒤통수에 쏴도 프리뷰엔 얼굴이 보임 → "정면됨"으로 오판. → 판정은 원본(네이티브) 메시를 4방향 렌더해 조각된 얼굴이 어느 yaw인지 먼저 확인(=해부학적 앞면), 그 쪽으로 투사.
2. 평면 데칼 천장: 평면 2D를 3D 머리에 붙이면 정면·¾은 자연스럽지만 옆(프로필)은 납작(깊이 정보 없음). 모든 각도 자연 얼굴 = VRoid/VRM(실제 얼굴 지오메트리) 영역, 단일이미지 투사로는 불가.
3. 솔리드 유지(뒷면 face 삭제 금지): 삭제하면 속 빈 셸 → 궤도 돌면 안쪽 비쳐 "사라짐/등에 매핑" 착시. 풀 메시 + Cull Back.
4. 렌더 셰이더 = Unlit/Texture(Cull Back), Sprites/Default 금지(Cull Off 양면 → 뚫린 뒷면·중복 아바타).
5. 메시별 방향 제각각: 원본 GLB 프리팹은 gltf 루트 회전을 품음. 씬 배치 시 rotY를 프리팹 기본 회전 위에 곱함(덮어쓰기 금지 — v2가 틀어졌음). 스킨 메시는 Object.Instantiate 사용(PrefabUtility.InstantiatePrefab은 v2를 T-포즈 바인드로 되돌림).

unityctl 운영 함정 (이번 세션 겪음, [[unityctl-operations]] 보강)

• --json 필수: 없으면 Spectre.Console 크래시("Could not find color 'UnknownError'") — 실제 호출은 성공, 출력만 죽음.
• --args는 JSON 배열: '["NATIVE","yaw0=a.png",768]'. 문자열 그냥 주면 파싱에러.
• play stop 먼저: EditorSceneManager.OpenScene은 플레이모드서 불가("cannot be used during play mode"). 렌더 전 항상 정지.
• 컴파일 반영 레이스: C# 수정 후 asset import <script.cs> + await-ready 후에도 첫 invoke는 구 어셈블리 가능 → 재invoke로 검증(반환문자열/동작 확인).
• 락 경합: invoke 겹치면 "Project lock is still held". 직렬화(하나 끝나고 다음), 겹친 place는 완료까지 폴링.
• 캡처: screenshot capture --view game|scene --width W --height H --output p, editor focus-gameview|focus-sceneview.

코어 API (Assets/Poc/Editor/ProjectionBaker.cs)

• SetGlb(path) — 대상 메시 지정(런타임, 재컴파일 불요).
• BakeProjected(outFile, "view=texPath|...", neutralFallback, priorityFill) — 캘리브레이션 투사 베이크(→ Output/). neutralFallback=false=나머지 네이티브, true=투명. priorityFill=앞뷰 우선 갭필.
• RenderWithTexture(texPathOr"NATIVE"/"BARE", "yaw0=a.png|yaw90=b.png", res) — 검수 렌더(Unlit/Texture Cull Back). yawN=수평 회전.
• PlaceModelsForCompare("glb[;texPath]@rotY|...") — 씬에 배치·저장(BakedResultScene.unity). ;texPath=텍스처 오버라이드(BakeProjected 결과 적용), 균일 높이 정규화, 프리팹 회전 보존+rotY.

검수 플로우 (한 캐릭터)

1. Rodin으로 GLB 생성 → Assets/Poc/  (asset import)
2. RenderWithTexture(NATIVE, yaw0|90|180|270) → 조각된 얼굴 yaw 확인(=해부학 앞면)
3. SetGlb → BakeProjected("x_bp.png","front=master",false,false) → Output/x_bp.png
4. cp Output/x_bp.png Assets/Poc/  + asset import
5. RenderWithTexture("Assets/Poc/x_bp.png", yaw<앞면>) → open 으로 얼굴 자연스러움 판정
6. PlaceModelsForCompare("glb;x_bp.png@rot") → 씬 저장, 캡처

전신은 출하 가능(정면·¾ 자연). 옆모습·강회전은 별 트랙(VRoid/2.5D).

관련

메모리 [[unityctl-operations]]·[[show-results-open-png]]·[[visual-verify-real-render]]·[[vrm-3d-pipeline-research-hold]](진짜 3D 얼굴 경로). SPEC/증거 unity-3d-texture-projection-poc/TEXTURE_REGISTRATION_FINDINGS.md.