Museum Constructor (프로토타입)
사진·영상·3D 작품을 올려 웹에서 관람할 수 있는 3D 전시관을 만드는 도구입니다. 서버 없이 브라우저 안에서 동작합니다.
- 편집 모드: 건축 프로그램처럼 층마다 공간을 그리고 벽에 액자·벽 글을, 바닥에 조각 좌대를 배치한 뒤 작품을 올려요.
- 관람 모드: 공개된 전시 목록에서 하나를 고르면 초대장이 뜨고, 3D 전시관에 입장해 층을 오가며 작품을 감상해요. 자동 투어·음성 해설·VR 관람을 지원해요.
실행
npm install
npm run dev # http://127.0.0.1:5173 (PORT 환경변수가 있으면 그 포트)
npm test # 도면·충돌·자동배치·감상 순서·스키마·EXIF·텍스처 LOD·오디오·VR 단위 테스트
npm run build # 타입체크 + 프로덕션 빌드 (dist/)
첫 실행 시 2층짜리 샘플 전시가 자동으로 만들어집니다 (작품 이미지는 개발용 임시 이미지, 입구에 서문 벽 글).
배포 (GitHub Pages)
main 에 push 하면 GitHub Actions(.github/workflows/deploy.yml)가 테스트·빌드 후 https://ring-experimental.github.io/museum-constructor/ 에 배포합니다. 빌드는 상대 경로(base: './')라 어느 하위 경로에 올려도 동작하고, public/ 파일은 publicUrl()(src/publicUrl.ts)로 불러옵니다. 서버가 없으므로 배포된 사이트에서도 전시 데이터는 각 방문자의 브라우저에만 저장됩니다.
편집 모드 사용법
| 도구 (단축키) | 하는 일 |
|---|
| 선택 (1, V) | 항목 선택·드래그 이동. 빈 곳 드래그 = 화면 이동. Shift+클릭 = 여러 개 선택, Shift+드래그 = 범위 선택, Ctrl+A = 층 전체 |
| 공간 (2) | 격자를 드래그해 바닥(방)을 칠함. 벽은 공간 둘레에 자동 생성. 우클릭 드래그 = 지우기 |
| 칸막이 벽 (3) | 격자선을 클릭/드래그해 내부 벽을 세우거나 없앰 |
| 액자 (4) | 벽 가까이 클릭 → 액자 걸기. 보관함에서 작품을 고르면 클릭할 때마다 다음 작품이 순서대로 걸림 |
| 벽 글 (5) | 벽에 전시 서문·섹션 제목·안내문을 붙임. 글자 크기·정렬·색(벽 색에 맞춰 자동)·폭·높이 조절 |
| 엘리베이터 (6) | 벽에 엘리베이터 설치 (층마다 1개, 층 이동 지점) |
| 소품 (7) | 벤치·화분·조각 좌대 배치, R 로 회전. 조각 좌대에는 3D 작품(GLB)을 올릴 수 있음 |
| 시작 위치 (8) | 관람객이 처음 서는 곳. 클릭 후 드래그로 방향 지정 |
| 지우개 (9) | 액자·벽 글·소품·칸막이 벽 삭제 |
- 가장 빠른 방법: 템플릿 선택 → 사진 업로드(여러 장, 창에 끌어다 놓기 가능) → ‘빈 벽에 자동 배치’.
- 보관함에는 **사진(JPG/PNG/WebP), 영상(MP4/WebM, 200MB·15분 이하), 3D 모델(.glb, 50MB 이하)**을 올릴 수 있어요. 사진은 EXIF/Windows 속성의 제목·작가·촬영 연도를 자동으로 채워요.
- 보관함의 작품을 도면의 벽/액자 위로 끌어다 놓아도 걸립니다. 3D 작품은 좌대 위로 끌면 올라가고, 빈 바닥에 끌면 좌대와 함께 놓여요.
- 정보 일괄 편집(보관함 버튼): 표에서 제목·작가·연도·설명을 한꺼번에 입력 (Enter 로 아래 칸), 작가·연도 일괄 적용, 보관함 순서 변경.
- 감상 순서(층 설정 탭): 자동 순서(시작 위치에서 벽을 따라 시계방향)를 드래그나 ↑↓ 로 바꿀 수 있고, 도면에 번호로 표시돼요.
- 여러 개 선택 시 인스펙터에서 액자 중심 높이(눈높이 1.45m 등)·크기·액자 스타일·매트·명제표·조명을 한 번에 맞추고, 함께 삭제·회전·이동(방향키)할 수 있어요.
- 액자마다 조명을 기본 / 스포트라이트 / 끄기 로 고를 수 있어요 (스포트라이트 = 실제 조명 + 빛줄기, 층마다 실제 조명 6개까지).
- 작품마다 음성 해설 녹음을, 전시에 배경 음악을 올릴 수 있어요 (녹음이 없으면 설명을 음성 합성으로 읽어 줌 — 전시 정보 탭에서 끌 수 있음).
- 화면 구성: 도면 / 분할(도면 + 실시간 3D) / 3D. 3D 미리보기에서 액자·좌대 작품을 클릭하면 선택(Shift+클릭 = 추가)됩니다.
- 실행취소 Ctrl+Z, 다시실행 Ctrl+Shift+Z (입력칸 하나를 고친 것은 한 단계로 묶임). 변경은 자동 저장됩니다.
- ‘걸어보기’로 바로 1인칭 관람, ‘공개하기’로 관람 목록에 노출.
- 전시를
.museum.json 파일로 내보내기/가져오기 (업로드한 사진·영상·3D 모델·오디오 포함) — 서버 없이 백업·공유.
관람 모드 조작
드래그 둘러보기 · WASD/방향키 이동(Shift 빠르게) · 바닥 클릭 이동 · 휠 앞뒤 이동 · 작품/벽 글 클릭 감상(←/→ 이전·다음, ‘크게 보기’, 3D 작품은 ‘돌려 보기’) · 미니맵(M, 클릭 이동) · 엘리베이터 또는 우측 상단 층 버튼으로 층 이동. 모바일 터치도 같은 방식(드래그/탭)으로 동작합니다.
- 작품 순서대로 감상: 큐레이터가 정한 순서로 자동 투어. 작품마다 설명 길이에 맞춰 머물다 넘어가고(스페이스 = 일시정지), 층 끝에서는 다음 층으로 이어서 감상해요.
- 음성 해설(헤드폰 버튼): 작품 앞에 서면 녹음 또는 브라우저 기본 음성 합성(Web Speech API)으로 설명을 들려주고, 자동 투어는 해설이 끝난 뒤 넘어가요. 배경 음악(음표 버튼)은 해설 중 작게 줄어요.
- 영상 작품은 가까이 가면 소리 없이 재생되고, 감상 패널의 ‘영상 소리 켜기’로 소리를 들을 수 있어요.
- 작품 링크: 감상 패널의 ‘이 작품 링크 복사’ 또는 주소창의
#/visit/<전시>?art=<작품> 으로 그 작품 앞에서 바로 시작해요.
- VR 관람: WebXR 을 지원하는 브라우저·헤드셋에서 VR 버튼이 보여요. 컨트롤러로 가리키고 트리거 = 그곳으로 이동/작품 앞으로/엘리베이터로 다음 층, 왼쪽 스틱 = 이동, 오른쪽 스틱 = 30° 회전.
구조
src/
core/ 데이터 모델(types), 스키마 버전·검증(schema), 도면 계산(grid), 충돌(collision),
템플릿·자동배치(factory), 감상 순서(tour), 업로드 파일 참조(blobs)
storage/ IndexedDB 저장소(exhibitionRepo, imageRepo), 업로드 리사이즈, EXIF, 영상 포스터,
내보내기/가져오기, 샘플 시드
three/ Stage(렌더러·조명·카메라 받침대), buildFloor(층 → 3D 씬), 액자 몰딩, 벽 글 텍스처,
작품 텍스처 캐시 + 거리별 해상도(artworkSlot), 3D 작품(GLB) 로더, 스포트라이트, 소품 GLB
viewer/ 1인칭 컨트롤러, 미니맵, 오디오 가이드(TTS·녹음·배경 음악), WebXR
editor/ zustand 스토어(실행취소·다중 선택), 2D 도면(SVG), 3D 미리보기, 인스펙터, 작품 보관함,
일괄 편집 표, 감상 순서 목록, 오디오 첨부
pages/ 관람 목록 · 관람 · 스튜디오 목록 · 편집기
tools/blender/ 소품 3D 모델 생성 스크립트 (→ public/assets/models/*.glb)
docs/EXTERNAL_ASSETS.md 외부 제작이 필요한 2D 에셋 목록과 규격
도면 모델
- 층 =
cols × rows 격자, 한 칸 = 2m. 칸을 칠하면 바닥, 칠한 칸과 빈 칸의 경계에 벽이 자동으로 생깁니다. 칸막이 벽은 격자선(모서리) 단위.
- 액자·벽 글·엘리베이터는
벽 모서리 + 바라보는 방향(side) + 좌우 오프셋으로 저장되어, 벽 위치만 알면 3D 좌표가 결정됩니다.
- 공간/벽을 지워 걸 곳이 사라진 액자·소품은 자동 정리되고(토스트 안내), Ctrl+Z 로 복구됩니다.
- 3D 텍스처는 처음엔 작은 썸네일(최대 512px)로 걸고, 관람객 7m 안의 가까운 작품 10점만 고해상도(데스크톱 2048px / 모바일 1280px)로 바꿨다가 11m 밖으로 멀어지면 다시 내립니다. 영상도 가까울 때만 재생돼요.
문서 버전과 검증
Exhibition JSON 에는 schemaVersion 이 있고(현재 v2 — 벽 글, 감상 순서, 작품 종류(media), 좌대 작품, 오디오, 작품 조명), 저장소에서 읽거나 파일을 가져올 때 모두 migrateExhibition(src/core/schema.ts)을 거칩니다.
- 옛 버전 문서는 현재 구조로 변환되고, 타입이 틀리거나 범위를 벗어난 값은 안전한 값으로 고쳐지며, 쓸 수 없는 항목(격자 밖 벽, 모르는 종류,
javascript: 같은 주소)은 버려집니다.
- 앱보다 새 버전의 문서는 안내 메시지와 함께 거부합니다. 가져오기 파일의 첨부 데이터는
data: URL 만 받습니다.
- 구조를 바꿀 때는
SCHEMA_VERSION 을 올리고 migrateExhibition 에 변환을 추가하세요.
서버 확장 포인트
ExhibitionRepository(src/storage/exhibitionRepo.ts) 인터페이스와 Exhibition JSON(src/core/types.ts)은 그대로 API 페이로드로 쓸 수 있게 설계했습니다. 게시판 서버를 붙일 때는 REST 구현으로 저장소를 교체하고(읽은 문서는 migrateExhibition 으로 검증 — 서버 쪽 요청 검증에도 같은 함수 사용 가능), 업로드 파일은 collectBlobIds/remapBlobIds(src/core/blobs.ts)로 찾아 오브젝트 스토리지로 옮기면 됩니다. status: draft | published 가 공개 여부를, ?art= 작품 링크가 공유 주소를 담당합니다.
3D 모델 (Blender)
로컬 Blender 5.2 로 스크립트 생성한 GLB 를 씁니다. 다시 만들려면 (PowerShell, 프로젝트 루트):
& "C:\Program Files\Blender Foundation\Blender 5.2\blender.exe" -b --factory-startup --python tools/blender/build_props.py -- --out public/assets/models
& "C:\Program Files\Blender Foundation\Blender 5.2\blender.exe" -b --factory-startup --python tools/blender/render_previews.py
두 번째 명령은 GLB 검증(크기·원점·방향 출력)과 미리보기 렌더(tools/blender/previews/)를 합니다. GLB 가 없으면 앱은 단순 도형으로 대체합니다. 조각 좌대 모델의 Sculpture 노드는 사용자 3D 작품을 올리면 자동으로 빠집니다.
알려진 제약 (프로토타입)
- 데이터는 이 브라우저의 IndexedDB에만 저장됩니다. 다른 기기와 공유하려면 내보내기 파일을 쓰세요 (작품 링크도 같은 브라우저 안에서만 열립니다).
- 외부 URL 이미지는 원본 서버가 CORS 를 허용해야 3D 텍스처로 쓸 수 있습니다 (안 되면 다운로드 후 업로드). 서버가 생기면 프록시로 해결 가능합니다. 영상·3D 모델·오디오는 업로드 파일만 지원합니다.
- 업로드 사진은 긴 변 2560px 로 줄여 저장합니다. 영상·3D 모델은 원본 그대로 저장하므로 내보내기 파일이 커질 수 있어요.
- 음성 해설은 브라우저 기본 음성 합성(Web Speech API)을 씁니다. API 가 없거나 음성이 하나도 없는 환경에서는 헤드폰 버튼이 나타나지 않고, 읽다가 엔진 오류가 나면 그 자리에서 기능이 꺼집니다. 음성은 브라우저가
ko-KR 기준으로 고르므로, 한국어 음성이 없는 OS 에서는 다른 언어 음성이 어색하게 읽을 수 있어요.
- VR 관람은 WebXR
immersive-vr 를 지원하는 환경에서만 버튼이 보이며, 실제 헤드셋에서의 조작감은 기기별 확인이 필요합니다.
- 층 이동은 엘리베이터(페이드 전환) 방식이며 계단으로 이어진 연속 공간은 아닙니다.
