diff --git a/features/construction-pmis/bim-viewer.md b/features/construction-pmis/bim-viewer.md index e2b0341..01056ea 100644 --- a/features/construction-pmis/bim-viewer.md +++ b/features/construction-pmis/bim-viewer.md @@ -1,7 +1,7 @@ # BIM 뷰어 — Three.js + web-ifc 기반 웹 3D BIM 뷰어 > **작성일**: 2026-03-12 -> **상태**: Phase 2 완료 (IFC 업로드 + 다운로드) +> **상태**: Phase 3 완료 (SAM Show Effects 20종) > **소스**: `mng/resources/views/juil/bim-viewer.blade.php` --- @@ -23,6 +23,7 @@ | **IFC 파일 업로드** | `.ifc` 파일 업로드 → 실제 BIM 모델 렌더링 | **Phase 2** | | **IFC 파일 다운로드** | 현재 모델을 IFC 파일로 내보내기 | **Phase 2** | | **드래그 앤 드롭** | IFC 파일을 뷰포트에 드래그하여 로드 | **Phase 2** | +| **SAM Show Effects** | SAM/샘 텍스트 3D 애니메이션 20종 선택/재생 | **Phase 3** | ### 1.3 핵심 기술 스택 @@ -367,20 +368,177 @@ Three.js → React: bim.onSelect = setSelected (요소 선택 콜백) | 파일 | 위치 | 설명 | |------|------|------| -| `bim-viewer.blade.php` | `mng/resources/views/juil/` | BIM 뷰어 전체 (~900줄, Three.js + web-ifc + React) | +| `bim-viewer.blade.php` | `mng/resources/views/juil/` | BIM 뷰어 전체 (~1300줄, Three.js + web-ifc + React + Show Effects) | | `PlanningController.php` | `mng/app/Http/Controllers/Juil/` | `bimViewer()` 메서드 | | `web.php` | `mng/routes/` | `GET /juil/construction-pmis/bim-viewer` | --- -## 9. 향후 계획 (Phase 3+) +## 9. SAM Show Effects (Phase 3) -| Phase | 기능 | 기술 | -|-------|------|------| -| ~~Phase 1~~ | ~~데모 건물 + 3D 뷰어~~ | ~~Three.js r128~~ (완료) | -| ~~Phase 2~~ | ~~IFC 업로드/다운로드 + 실제 BIM 렌더링~~ | ~~web-ifc 0.0.66~~ (완료) | -| **Phase 3** | 요소 속성 패널 고도화, 2D 평면도 모드 | Three.js Orthographic Camera | -| **Phase 4** | 모델 파일 관리, 버전 이력, 협력업체 조회 | Laravel API + DB | +### 9.1 개요 + +BIM 뷰어에 SAM 브랜드 3D 애니메이션 효과 20종을 추가했다. 툴바 드롭다운에서 효과를 선택하고 재생 버튼을 누르면 3D 뷰포트 위에 "SAM"(3D TextGeometry)과 "샘"(Canvas Sprite) 텍스트가 다양한 패턴으로 애니메이션된다. + +### 9.2 아키텍처 + +``` +사용자 → 드롭다운(sam1~sam20) 선택 → ▶ 재생 버튼 + ↓ +playShow(id) + ↓ FontLoader로 3D 폰트 로드 (최초 1회) +_initEffect(id) + ↓ switch(id): 20개 케이스 + ↓ 각 케이스: items[] 생성 + update(s, elapsed) 클로저 정의 + ↓ +this._show = { type, items, extras, startTime, duration, update } + ↓ +animate() 루프에서 _updateShow() 호출 + ↓ s.update(s, elapsed) — 클로저가 애니메이션 계산 + ↓ elapsed >= duration → _cleanupShow() + ↓ +_cleanupShow() + ↓ items[].geometry.dispose() + material.dispose() + ↓ extras[].geometry.dispose() + material.dispose() + ↓ scene.remove(item/extra) +``` + +**핵심 설계 원칙**: 각 효과는 클로저 기반 `update` 함수로 자기 완결적이다. `_updateShow()`는 단순 디스패처로, `s.update(s, elapsed)`만 호출하고 시간 초과 시 `_cleanupShow()`를 호출한다. + +### 9.3 헬퍼 메서드 + +| 메서드 | 역할 | +|--------|------| +| `_makeTextSprite(text, color, size)` | Canvas 2D로 한글 텍스트("샘") 스프라이트 생성 | +| `_mkItem(text, color, size, pos)` | "SAM" → 3D TextGeometry, "샘" → Canvas Sprite 통합 생성 | +| `_mkFlash(pos)` | 흰색 반투명 SphereGeometry (폭발/번쩍 효과용) | +| `_setOp(item, value)` | 아이템 투명도 설정 (0~1 클램핑) | +| `mkMix(n, sMin, sMax)` | SAM/샘 혼합 아이템 N개 일괄 생성 (효과 내부 헬퍼) | + +### 9.4 아이템 생성 패턴 + +```javascript +// 3D TextGeometry (영문 "SAM") +const geo = new THREE.TextGeometry('SAM', { font, size, height:size*0.2 }); +const mat = new THREE.MeshPhongMaterial({ color, transparent:true, opacity:1 }); +const mesh = new THREE.Mesh(geo, mat); + +// Canvas Sprite (한글 "샘") +const canvas = document.createElement('canvas'); +ctx.fillText('샘', ...); // 한글 렌더링 +const sprite = new THREE.Sprite(new THREE.SpriteMaterial({ map:texture })); +``` + +각 아이템에 `size`, `color`, `idx`, `targetPos`, `burstSpeed` 등 애니메이션용 커스텀 속성을 부착한다. + +### 9.5 효과 목록 (20종) + +| ID | 이름 | 설명 | 패턴 | +|----|------|------|------| +| 1 | Star Gathering | 사방에서 별처럼 모여 폭발 | gather → burst | +| 2 | Spiral Galaxy | 은하 소용돌이 | 나선 회전 → 수축 | +| 3 | Fireworks | 불꽃놀이 | 상승 → 방사 폭발 | +| 4 | Matrix Rain | 매트릭스 문자비 | 상단에서 하강 | +| 5 | DNA Helix | DNA 이중나선 | 쌍 나선 회전 | +| 6 | Wormhole | 웜홀 통과 | 원형 터널 돌진 | +| 7 | Constellation | 별자리 연결 | 점 배치 → 선 연결 | +| 8 | Heartbeat | 심장 박동 | 하트 형태 펄스 | +| 9 | Tornado | 토네이도 | 원뿔형 회전 상승 | +| 10 | Domino Wave | 도미노 파동 | 순차 기울어짐 | +| 11 | Gravity Well | 중력 우물 | 공전 → 흡입 | +| 12 | Northern Lights | 오로라 커튼 | 수평 웨이브 컬러 변화 | +| 13 | Clock Mechanism | 시계 톱니바퀴 | 동심원 역방향 회전 | +| 14 | Particle Storm | 입자 폭풍 | 격렬한 랜덤 이동 | +| 15 | Bloom Garden | 꽃 피어남 | 중심에서 방사 성장 | +| 16 | Ocean Waves | 해양 파도 | 사인파 물결 | +| 17 | Lightning Storm | 번개 | 번쩍 + 분산 | +| 18 | Pendulum | 진자 시계 | 좌우 스윙 | +| 19 | Flock of Birds | 새 떼 비행 | Boids 군집 이동 | +| 20 | Grand Finale | 그랜드 피날레 | 나선 → 모임 → 대폭발 | + +### 9.6 애니메이션 시간 관리 + +```javascript +// 정규화된 시간 t (0.0 ~ 1.0) +const t = elapsed / s.duration; + +// 페이즈 분할 예시 (Star Gathering) +if (t < 0.6) { + // GATHER 페이즈: 사방에서 중심으로 모임 + const p = t / 0.6; // 0~1 정규화 +} else if (t < 0.7) { + // FLASH 페이즈: 흰색 번쩍 +} else { + // BURST 페이즈: 폭발 분산 + const bp = (t - 0.7) / 0.3; +} +``` + +- `performance.now()` 기준 절대 시간 사용 +- 각 효과의 `duration`은 3~6초 범위 +- 프레임 독립적 (delta time 기반) + +### 9.7 UI 구성 + +``` +┌─────────────────────────────────────────────┐ +│ BimToolbar │ +│ ┌──────────────────┐ ┌──┐ │ +│ │ sam1 Star Gather ▼│ │▶│ ... 기존 버튼 │ +│ └──────────────────┘ └──┘ │ +│ (드롭다운 select) (재생) │ +└─────────────────────────────────────────────┘ +``` + +| UI 요소 | React 상태 | 설명 | +|---------|-----------|------| +| 효과 드롭다운 | `effectId` | `SHOW_EFFECTS` 배열(20개) 중 선택 | +| 재생 버튼 | — | `sceneRef.current.playShow(effectId)` 호출 | + +`SHOW_EFFECTS` 상수: + +```javascript +const SHOW_EFFECTS = [ + { id:1, name:'sam1 Star Gathering' }, + { id:2, name:'sam2 Spiral Galaxy' }, + // ... 20개 +]; +``` + +### 9.8 메모리 관리 + +`_cleanupShow()`가 모든 효과의 리소스를 통일적으로 정리한다: + +```javascript +_cleanupShow() { + if (!this._show) return; + const { items, extras } = this._show; + // items: TextGeometry 또는 Sprite + [items, extras].forEach(arr => arr.forEach(it => { + if (it.geometry) it.geometry.dispose(); + if (it.material) { + if (it.material.map) it.material.map.dispose(); + it.material.dispose(); + } + this.scene.remove(it); + })); + this._show = null; +} +``` + +`dispose()` (BimScene 전체 정리) 시에도 `_cleanupShow()`를 호출하여 누수를 방지한다. + +--- + +## 10. 향후 계획 (Phase 4+) + +| Phase | 기능 | 기술 | 상태 | +|-------|------|------|------| +| ~~Phase 1~~ | ~~데모 건물 + 3D 뷰어~~ | ~~Three.js r128~~ | 완료 | +| ~~Phase 2~~ | ~~IFC 업로드/다운로드 + 실제 BIM 렌더링~~ | ~~web-ifc 0.0.66~~ | 완료 | +| ~~Phase 3~~ | ~~SAM Show Effects 20종~~ | ~~Three.js TextGeometry + Sprite~~ | 완료 | +| **Phase 4** | 요소 속성 패널 고도화, 2D 평면도 모드 | Three.js Orthographic Camera | | +| **Phase 5** | 모델 파일 관리, 버전 이력, 협력업체 조회 | Laravel API + DB | | --- @@ -391,4 +549,4 @@ Three.js → React: bim.onSelect = setSelected (요소 선택 콜백) --- -**최종 업데이트**: 2026-03-12 +**최종 업데이트**: 2026-03-13