---
name: nanobanana-visualize
description: 부스/인테리어/배선/조명 설계 데이터를 나노바나나(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).