kintex/.claude/skills/nanobanana-visualize/SKILL.md

name	description
nanobanana-visualize	부스/인테리어/배선/조명 설계 데이터를 나노바나나(Gemini 이미지 생성)로 '시공 후 결과 사진'으로 렌더링할 때 사용. 시공 시안 이미지, before/after 비교, 조명 야간 연출, 배선 오버레이 생성 요청 시 트리거.

나노바나나 시공 결과 시각화 스킬

ReRoomAI 실증 패턴(docs/analysis/reroomai-source.md)을 표준화한 파이프라인. "부스 골격 보존 + 표면(집기·조명·배선) 교체" image-to-image 편집.

호출 표준

• 모델: gemini-3.1-flash-image-preview (나노바나나 2). 환경변수 NANOBANANA_MODEL 로 오버라이드 가능.
• 호출: tools/nanobanana/client.py의 NanoBananaClient만 사용(직접 API 호출 금지). google-genai(google.genai) SDK로 generate_content(model, contents=[Part.from_bytes(...), text]). 참조 이미지는 inlineData(mimeType+base64), 지시문은 text — parts 배열로 전달. mimeType 자동 감지.
• 보안: API 키는 환경변수 GEMINI_API_KEY 에서만 로드. 코드/로그/커밋/응답에 절대 기록 금지. ★ 실제 Gemini 호출은 소유자 승인 대기(reroomai-source.md §8) — 승인 전 실호출 강제 금지.

프롬프트 빌더 (구조화 사전 조립 + 보존/교체 분리)

build_booth_prompt(scene, shot_preset, layers) 가 PLANNING §6-2 스키마를 4단으로 조립:

1. 대상+스타일 — BOOTH_TYPES(독립/조립/코너/아일랜드) × BOOTH_STYLES(럭셔리/테크/친환경/미니멀/표준) + 치수·브랜드컬러.
2. 보존 잠금 — 부스 외곽 치수·기둥·바닥 트렌치 그리드·천장 트러스·통로 방향·카메라 앵글 유지.
3. 교체 지정 — FIXTURE_LAYERS(집기/조명/전기/네트워크) 레이어별 조각 + 간판 문구(한글)·자재·존·색온도.
4. 사진 품질 — photorealistic tradeshow, natural lighting, high detail, no people/real logos.

입력은 §6-2 scene(hall/booth/design/lighting/wiring + shot/render_hints). 중첩/평면 모두 관대 파싱.

절차

1. 입력 확인: scene dict(§6-2)가 구조화됐는지 확인. 없으면 설계 데이터/사용자에서 추출.
2. GEMINI_API_KEY 확인. 없으면 발급 안내 후 중단. (승인 전이면 실호출 보류)
3. NanoBananaClient().render_shot(scene, shot_preset="S1", reference_image=빈부스사진, seed=고정값).
4. 표준 샷 세트 S1~S7 순서로 생성:
   • S1 정면 주간 → S2 정면 야간 → S3 통로 → S4 내부 (모두 render_shot)
   • S5 Before/After: S1 결과 + reference_image(빈 부스 실측) 쌍
   • S7 홀 조감: render_shot(shot_preset="S7")
   • S6 배선 오버레이: 생성형 아님 → render_wiring_overlay_raster(wiring, hall_dims_m, kinds, base_image) (도면 위 전기 적/네트워크 청/급배수 녹 경로를 좌표 정합 래스터 합성. 시공 검증용 1차 산출물). 발표/설명용 보조 이미지가 필요할 때만 generate_wiring_overlay(생성형, 검증 사용 금지).
5. 빈 부스 실측 사진은 reference_image로 전달 → 실제 홀 구조 보존 합성(S5 before/after 쌍).
6. 워터마크: 모든 산출 이미지에 "AI 생성 예상 이미지 — 실제 시공 결과와 다를 수 있음" 합성(Pillow) 후 output/visualizations/에 저장. GeneratedImage.save()가 사이드카 .meta.json(생성일·스키마 해시· 모델 버전·seed·워터마크 고지)을 결정적으로 기록하고 PNG는 tEXt 청크에도 임베드.
7. 일관성: 같은 부스의 추가 샷은 동일 seed 전달(B-12). seed 미지원 SDK/모델이면 자동으로 참조체인 기반 일관성으로 폴백(첫 생성 이미지를 다음 샷 reference_image로 재사용).

표준 샷 세트 S1~S7

샷	호출	용도
S1 정면 주간	render_shot(scene,"S1")	기본 컨펌 컷
S2 정면 야간	render_shot(scene,"S2")	조명 연출 평가
S3 통로 뷰	render_shot(scene,"S3")	관람객 동선
S4 내부 뷰	render_shot(scene,"S4")	집기 배치
S5 Before/After	S1 + reference_image 쌍	시공 전/후 비교
S6 배선 오버레이	render_wiring_overlay_raster(...) ★래스터 합성	시공 검증(좌표 정합)
S7 홀 조감	render_shot(scene,"S7")	배치안 비교

프로덕션 방어 (ReRoomAI route.ts 패턴)

• 입력 크기 가드: 참조 이미지 8MB 상한 + 긴 쪽 1024px 다운스케일/JPEG 0.85(downscale_for_upload).
• SAFETY 처리: finish_reason == SAFETY → NanoBananaSafetyError.
• 에러 분기: 키 무효→NanoBananaAuthError, 쿼터/429→NanoBananaQuotaError, SAFETY→NanoBananaSafetyError.
• 쿼터 차감: usage_recorder 훅은 성공 시에만 호출(실패는 카운트 소모 안 함).

품질 체크

• 부스 크기 비율이 스펙과 맞는가 (3x3 부스가 대형처럼 보이면 재생성).
• 텍스트 사이니지가 한국어로 정확한가 (실패 시 간판 영역 후처리 합성 — PLANNING §6-4).
• 실존 브랜드 로고/사람 얼굴이 없는가.
• 계약·심사 서류에는 생성 이미지 사용 금지(도면만 유효 — PLANNING §6-5).