# 🦖 우리 반에 공룡이 나타났다! (Dino AR Camera)

초등학교 1학년 통합교과 **'우리 반에 공룡이 나타난다면'** 수업을 위해 개발된 웹 기반 무료 3D AR 공룡 카메라입니다.  
별도의 앱 설치, 회원가입, 광고 없이 웹 브라우저만으로 교실 카메라 화면 위에 움직이는 3D 공룡을 소환하고 친구들과 함께 사진을 찍어 저장할 수 있습니다.

---

## 1. 주요 구현 기능 (1차 버전)

### 📷 카메라 및 교실 연습 배경
- **자동 카메라 연결**: 브라우저에서 `MediaDevices.getUserMedia()`를 통해 카메라 권한을 요청합니다.
  - 태블릿/스마트폰: **후면 카메라(`environment`)** 우선 사용
  - PC / 노트북: **웹캠** 자동 연결
- **전·후면 카메라 전환**: 상단 `🔄 카메라` 버튼으로 전면(셀카, 자동 좌우 미러링)과 후면 카메라를 전환할 수 있습니다.
- **교실 배경 폴백 모드**: 카메라가 없는 데스크톱 PC이거나 카메라 권한이 거부된 경우에도 수업을 진행할 수 있도록 **1학년 교실 일러스트 배경 모드(`🏫 교실배경`)**를 기본 제공합니다.

### 🦖 3D 공룡 및 애니메이션·울음소리
- **기본 공룡**: **티라노사우루스(T-Rex)**가 첫 화면에 등장합니다.
- **추가 공룡 포함 (총 5종)**:
  1. 🦖 **티라노사우루스** (`public/models/trex.glb`)
  2. 🦕 **트리케라톱스** (`public/models/triceratops.glb`)
  3. 🦕 **브라키오사우루스** (`public/models/brachiosaurus.glb`)
  4. 🐉 **스테고사우루스** (`public/models/stegosaurus.glb`)
  5. 🦖 **벨로시랩터** (`public/models/velociraptor.glb`)
- **자연스러운 조명과 바닥 그림자**: `HemisphereLight`, `DirectionalLight`(Soft Shadow Map), 그리고 실제 교실 바닥 영상 위에 그림자만 투명하게 드리우는 `ShadowMaterial` 바닥 평면(Shadow Catcher)을 적용했습니다.
- **애니메이션 재생**: 내장 키프레임 애니메이션(`Idle` 숨쉬기, `Walk` 걷기, `Roar` 입 벌려 포효하기) 및 보조 관절 모션이 작동합니다.
- **울음소리 및 음소거**: 공룡별 고유 울음소리(`public/sounds/*.wav` + Web Audio API 합성 폴백) 재생 및 상단 `🔊 소리 켜짐 / 🔇 소리 꺼짐` 토글을 지원합니다.

### 👆 초등학교 1학년 맞춤형 조작 (PC & 태블릿)
- **PC 조작**:
  - **마우스 왼쪽 드래그**: 공룡 위치 이동
  - **마우스 휠**: 공룡 크기 확대·축소 (`0.35배 ~ 2.8배` 안전 범위 자동 제한)
  - **회전 버튼 (`↩️ 왼쪽 돌리기` / `↪️ 오른쪽 돌리기`)** 또는 **우클릭/Shift 드래그**: 공룡 방향 회전
- **태블릿 / 모바일 조작**:
  - **한 손가락 드래그**: 공룡 위치 이동
  - **두 손가락 핀치 줌(벌리기/오므리기)**: 공룡 크기 확대·축소
  - **두 손가락 회전 또는 회전 버튼**: 공룡 방향 회전
- **원래대로 버튼 (`🎯 원래대로`)**: 공룡이 너무 작아지거나 구석으로 이동했을 때 한 번의 터치로 처음 위치·크기·방향으로 되돌립니다.

### 📸 사진 촬영 및 기기 저장 (서버 업로드 없음)
- 화면 하단 중앙의 큰 **`📸 찰칵!`** 버튼을 누르면 카메라 영상(또는 교실 배경)과 3D 공룡(+바닥 그림자)을 고해상도 캔버스에 합성합니다.
- **UI 버튼 및 초록색 바닥 배치 가이드 링은 사진에 절대 포함되지 않습니다.**
- `object-fit: cover` 비율 계산(`computeCoverCrop`)과 전면 카메라 좌우 반전 보정을 통해 화면에서 보던 비율·위치 그대로 왜곡 없이 저장됩니다.
- 촬영 직후 **사진 미리보기 창**에서 **`💾 사진 저장하기`**(PNG 다운로드), 모바일 **`📤 공유하기`**(Web Share API 지원 기기), **`🔄 다시 찍기`**를 사용할 수 있습니다.
- 모든 영상과 사진 데이터는 **사용자 기기(브라우저 메모리)에서만 처리**되며 외부 서버로 전송되지 않습니다.

---

## 2. 개발 및 실행 방법

### 사전 준비
- Node.js 18 이상 (권장: Node.js 20+)

### 패키지 설치 및 실행
```bash
# 1. 의존성 패키지 설치
npm install

# 2. (선택) 자체 제작 CC0 공룡 GLB 5종 및 WAV 울음소리 5종 재생성
npm run generate:assets

# 3. 개발 서버 실행 (로컬 및 동일 네트워크 접속 허용)
npm run dev
```
- 실행 후 브라우저에서 `http://localhost:5188` 으로 접속합니다.

### 빌드 및 테스트 명령어
```bash
# TypeScript 타입 검사
npm run typecheck

# 단위 테스트 실행 (Vitest)
npm test

# 프로덕션 정적 웹사이트 빌드 (dist/ 폴더 생성)
npm run build

# 빌드 결과물 로컬 미리보기
npm run preview
```

---

## 3. 공룡 GLB 모델 및 사운드 교체 방법

이 프로젝트는 외부 디자이너가 제작했거나 무료 에셋 사이트에서 다운로드한 `.glb` 파일로 즉시 교체할 수 있도록 설계되어 있습니다.

### 방법 A: `public/models/` 파일 교체 (영구 적용)
1. 새로운 3D 공룡 모델 파일(`.glb`)을 `public/models/trex.glb` (또는 `triceratops.glb` 등) 경로에 덮어씁니다.
2. `DinoManager`가 모델을 불러올 때 **자동으로 바운딩 박스를 계산하여 크기를 정규화하고 발바닥을 바닥 그림자(`y = 0`)에 맞추므로**, 모델 원점이나 스케일이 달라도 별도 코드 수정 없이 바로 표시됩니다.
3. 모델 내부에 `Idle`, `Walk`, `Roar` 등의 glTF 애니메이션 클립이 있으면 자동으로 매칭하여 재생하며, 애니메이션이 없는 정적 모델이라도 기본 호흡·걸음 모션이 적용됩니다.
4. 새로운 공룡 종류를 추가하려면 `src/config/dinosaurs.ts`의 `DINOSAUR_CATALOG` 배열에 항목을 추가합니다.

### 방법 B: 브라우저 화면에서 즉시 불러오기 (테스트용)
1. 앱 상단 왼쪽의 **`🦖 티라노사우루스 ▾`** 버튼을 누릅니다.
2. 팝업 하단의 **`📂 내 공룡 3D 파일(.glb) 불러오기`** 버튼을 눌러 내 기기에 있는 `.glb` 또는 `.gltf` 파일을 선택하면 즉시 화면의 공룡이 교체됩니다.

### 모델 및 사운드 라이선스 / 출처
- **티라노사우루스 (`public/models/trex.glb`)**:
  - 작품/저작자: **"T. rex" by Bake3D** (<https://bake3d.ai/free-3d-models>)
  - 라이선스: **CC BY 4.0** (<https://creativecommons.org/licenses/by/4.0/>) — 메시·텍스처 최적화 및 포효 모션 적용
- **트리케라톱스, 브라키오사우루스, 스테고사우루스, 벨로시랩터 (`public/models/*.glb`)**:
  - 원본: **Quaternius, "Animated Dinosaur Pack"** (<https://quaternius.com/packs/animateddinosaurs.html>)
  - 라이선스: **CC0 1.0 (퍼블릭 도메인)** — 곡면 세분화(Subdivision) 및 파충류 비늘 셰이더 적용
- **공룡 울음소리 (`public/sounds/trex.wav`, `*.mp3`)**:
  - `trex.wav`: **CC0 Deep Monster Roar by trazzz123** (OpenGameArt, **CC0 1.0**)
  - `*.mp3`: Freesound **CC0 1.0** 동물/공룡 효과음 가공본 (`JarredGibb`, `D.jones`, `Breviceps`)

---

## 4. 기기별 테스트 방법

### 💻 PC 웹캠 테스트 방법
1. `npm run dev` 실행 후 Chrome 또는 Edge에서 `http://localhost:5173`에 접속합니다.
2. 브라우저 상단 카메라 권한 팝업에서 **[허용]**을 클릭합니다.
3. 웹캠이 없는 데스크톱 PC라면 자동으로 **교실 배경 모드**가 켜지며, 언제든 상단 `🏫 교실배경 / 📷 카메라켜기` 버튼으로 전환할 수 있습니다.
4. 마우스 드래그(이동), 마우스 휠(크기 조절), 하단 버튼(회전·울음소리·걷기·찰칵)을 테스트합니다.

### 📱 Android 태블릿 테스트 방법 (Chrome 권장)
- Android Chrome에서 카메라(`getUserMedia`)를 사용하려면 반드시 **`localhost`** 또는 **`HTTPS` 보안 연결**로 접속해야 합니다.
- 아래 **5번(HTTPS를 이용한 모바일 테스트 환경 구성)** 방법으로 접속한 뒤:
  1. 후면 카메라로 교실 바닥이나 책상을 비춥니다.
  2. 한 손가락으로 공룡을 끌어서 원하는 위치에 놓고, 두 손가락을 벌려 크기를 조절합니다.
  3. `📸 찰칵!` 버튼을 눌러 사진을 찍고 `💾 사진 저장하기` 또는 `📤 공유하기`로 갤러리에 저장되는지 확인합니다.

### 🍎 iPad Safari 테스트 방법 (iPadOS 15+ 권장)
1. iPad Safari에서 HTTPS 주소로 접속한 뒤 카메라 권한 요청 시 **[허용]**을 탭합니다.
2. 비디오가 전체 화면에 자동 재생(`playsinline`, `muted`)되는지 확인합니다.
3. 사진을 찍은 후 미리보기 창에서 **`📤 공유하기` -> `이미지 저장`**(사진 앱에 바로 저장) 또는 **`💾 사진 저장하기`**(파일 앱 다운로드)가 정상 동작하는지 확인합니다.

### 💻 Chromebook 테스트 방법
1. Chromebook 내장 Chrome 브라우저에서 배포된 HTTPS 주소(또는 로컬 실행 시 `http://localhost:5173`)로 접속합니다.
2. 터치스크린이 있는 크롬북은 태블릿과 동일하게 손가락 핀치 줌·드래그를 사용할 수 있으며, 트랙패드/마우스로도 동일하게 조작할 수 있습니다.
3. 키보드 방향키/전환 시 화면 비율이 바뀔 때 공룡과 카메라 화면이 자연스럽게 리사이즈되는지 확인합니다.

---

## 5. HTTPS를 이용한 모바일(태블릿) 테스트 환경 구성

교실의 Android 태블릿이나 iPad에서 개발 PC의 서버에 접속해 카메라를 켜려면 **HTTPS 보안 컨텍스트**가 필요합니다 (`http://192.168.x.x:5173` 형태는 브라우저 보안 정책상 카메라가 차단됨).

### 방법 1: Cloudflare Tunnel 또는 ngrok 사용 (가장 간편, 인증서 경고 없음)
```bash
# 개발 서버 실행 (포트 5173)
npm run dev

# 새 터미널에서 Cloudflare 무료 임시 HTTPS 터널 실행
npx cloudflared tunnel --url http://localhost:5173
```
- 출력되는 `https://xxxx.trycloudflare.com` 주소를 태블릿 브라우저나 QR 코드로 열면 즉시 후면 카메라가 작동합니다.

### 방법 2: 정적 호스팅 무료 배포 (수업 현장에서 가장 추천)
백엔드가 없는 순수 정적 웹사이트이므로 `npm run build` 후 생성된 `dist/` 폴더를 아래 무료 HTTPS 호스팅에 올리면 교실 모든 태블릿에서 바로 접속할 수 있습니다:
- **GitHub Pages**, **Cloudflare Pages**, **Vercel**, **Netlify**

### 방법 3: USB 케이블 포트 포워딩 (Android 태블릿 전용)
- Android 태블릿을 PC에 USB로 연결하고 Chrome 주소창에 `chrome://inspect/#devices`를 열어 **`Port forwarding` (`5173 -> localhost:5173`)**을 활성화하면, 태블릿에서도 `http://localhost:5173`으로 카메라 권한을 사용할 수 있습니다.

---

## 6. 현재 구현된 기능과 알려진 제약

### 구현 완료 항목
- [x] Vite + TypeScript + Three.js 프로젝트 구조 설계 및 구현
- [x] PC 웹캠 및 태블릿 후면 카메라 우선 연결 + 전/후면 카메라 전환
- [x] 카메라 미연결/권한 거부 시 한국어 안내 및 **1학년 교실 일러스트 배경 모드** 제공
- [x] 티라노사우루스(기본) 포함 5종의 애니메이션 내장 GLB 모델 및 로컬 `.glb` 파일 즉시 불러오기 기능
- [x] 자연스러운 조명과 바닥 그림자(Shadow Catcher)
- [x] 마우스 드래그/휠 및 터치 한 손가락 이동/두 손가락 핀치 줌·회전 조작
- [x] 공룡 울음소리 재생 및 음소거 토글
- [x] UI를 제외한 고해상도 카메라+3D 공룡 사진 합성, 미리보기, 다시 찍기, PNG 저장 및 모바일 공유

### 알려진 제약
- 1차 버전은 모든 기기(PC, iPad, Chromebook, 보급형 Android 태블릿)에서 100% 작동하는 **카메라 화면 + 3D 레이어 실시간 합성 방식**을 사용합니다. 따라서 태블릿을 들고 걸어 다닐 때 실제 물리적 바닥 좌표에 공룡이 고정(World-Tracking)되지는 않으며, 화면 드래그와 핀치 줌으로 바닥 위치에 맞춰 배치합니다.
- 모바일 브라우저에서 `http://`(비보안 연결)로 로컬 IP에 접속하면 브라우저 정책에 의해 카메라 접근이 차단되므로, 이때는 자동으로 안내 배너와 함께 **교실 배경 모드**가 활성화됩니다.

---

## 7. 향후 WebXR 공간 인식 AR 개발 계획 (2차 확장 로드맵)

프로젝트 내 `src/ar/WebXRManager.ts`에 WebXR 지원 감지 인터페이스가 분리되어 있으며, 향후 다음 순서로 확장할 수 있습니다:

1. **WebXR `immersive-ar` + `hit-test` 연동**:
   - Android Chrome(ARCore 지원 기기)에서 `navigator.xr.requestSession('immersive-ar', { requiredFeatures: ['hit-test'] })` 세션을 시작합니다.
   - 교실 실제 바닥 평면을 인식해 레티클(바닥 조준점)을 표시하고, 화면을 탭하면 해당 3D 월드 좌표에 공룡을 고정 배치합니다.
2. **기기별 자동 폴백 아키텍처 유지**:
   - iPad Safari나 Chromebook, PC처럼 WebXR `immersive-ar`를 지원하지 않는 기기에서는 현재 구현된 **기본 카메라 합성 모드**로 자동 작동하도록 이원화 구조를 유지합니다.
3. **다중 공룡 배치 및 PWA 오프라인 캐싱**:
   - 한 화면에 친구들과 여러 마리의 공룡을 동시에 배치하는 기능 및 Service Worker를 통한 오프라인 수업 지원을 추가합니다.