kintex/tools/nanobanana

tools/nanobanana — Gemini 이미지 생성(나노바나나) 연동 모듈

부스/인테리어/배선/조명 설계 데이터를 "시공 후 결과 사진"으로 렌더링한다. 설계 기준: ReRoomAI 실증 패턴(docs/analysis/reroomai-source.md) + PLANNING §6.

준비

pip install google-genai Pillow
export GEMINI_API_KEY=발급받은_키   # https://aistudio.google.com

• 모델 기본값: gemini-3.1-flash-image-preview(나노바나나 2). NANOBANANA_MODEL로 오버라이드.
• ★ 실제 Gemini 호출은 소유자 승인 대기(reroomai-source.md §8). 키/네트워크 없이도 import·구조는 성립.

빠른 시작 (§6-2 scene 스키마)

from tools.nanobanana.client import NanoBananaClient

scene = {
    "hall": {"id": "제1전시장 7홀", "dims_m": [126, 90], "ceiling_m": 12},
    "booth": {"id": "A-102", "size_m": [6, 3], "type": "independent"},
    "design": {
        "signage": {"text": "주식회사 가디아"},
        "brand_color": "#0052A5",
        "zones": [{"type": "demo"}, {"type": "consult"}],
        "materials": [{"part": "wall", "finish": "matte_white"}],
    },
    "lighting": {"mode": "night", "color_temp_k": 4000},
    "wiring": {"power": [{"from_trench": [1, 1], "to": [5, 2], "kw": 3}]},
    "render_hints": {"style": "tech"},
}

c = NanoBananaClient()
img = c.render_shot(scene, shot_preset="S2",
                    reference_image="empty_booth.jpg",  # 빈 부스 실측 → 구조 보존
                    seed=12345)                         # 컷 간 일관성(B-12)
img.save("output/visualizations/booth_S2.png")          # 사이드카 .meta.json 동시 기록

표준 샷 세트 S1~S7 (PLANNING §6-3)

샷	호출	용도
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(wiring, hall_dims_m, kinds) ★래스터 합성	시공 검증(좌표 정합)
S7 홀 전경 조감	render_shot(scene,"S7")	배치안 비교(SCR-04)

S6 — 생성형 아님 (B-02)

시공 검증용 S6는 좌표 정합이 보장되는 백엔드 래스터 합성이다(로컬 PIL):

from tools.nanobanana.client import render_wiring_overlay_raster
ov = render_wiring_overlay_raster(scene["wiring"], hall_dims_m=(6, 3),
                                  kinds=["power", "network", "plumbing"],
                                  base_image="floorplan.png")  # 선택
ov.save("output/visualizations/booth_S6_wiring.png")

generate_wiring_overlay(layout, kind)(생성형)는 발표/설명용 보조 이미지 전용 — 시공 검증 사용 금지.

하위호환

평면 booth_spec dict를 쓰던 기존 코드는 generate_booth_photo(booth_spec, view, time_of_day)가 내부적으로 §6-2 scene 으로 변환 후 render_shot에 위임한다(그대로 동작).

방어·정책

• 입력 이미지 8MB 상한 + 긴 쪽 1024px 다운스케일/JPEG 0.85(downscale_for_upload).
• 에러 분기: NanoBananaAuthError(키 무효) / NanoBananaQuotaError(429·쿼터) / NanoBananaSafetyError(SAFETY).
• 쿼터/카운트는 성공 시에만 차감(usage_recorder 훅).
• 모든 산출 이미지에 "AI 생성 예상 이미지 — 실제 시공 결과와 다를 수 있음" 워터마크(계약 서류 사용 금지).
• 메타데이터(생성일·스키마 해시·모델 버전·seed)는 사이드카 .meta.json + PNG tEXt 청크로 임베드(B-03).
• API 키는 환경변수 GEMINI_API_KEY에서만 로드 — 코드/로그/커밋에 절대 기록 금지.