feat(examples): Meta Quest 3 egocentric recording + 3D hand pose viewer

[styu12]

Summary

새 예제 examples/meta_quest/ — MetaQuestHandStream + MetaQuestCameraStream 조합으로 Quest 3 하나에서 head pose / 양손 skeleton / 스테레오 egocentric 카메라를 동기화된 단일 세션으로 기록. Viewer 에 3-D hand pose 패널 추가해 opengraph-studio/showcase 와 동일한 스타일의 실시간 시각화 제공.

What the example does

Stream	Data	Rate	Transport
`quest_tracking`	26-joint hand skeleton × 2 + head pose (pos3+quat4)	72 Hz	UDP :14043
`quest_cam` (left/right)	720p stereo passthrough MJPEG-AVI	30 fps	HTTP :14045

모든 샘플이 `clock_domain="remote_quest3"` + `uncertainty_ns=10ms` 로 통일 → Mac-host 센서들과 standard sync 파이프라인으로 정렬.

Viewer 확장

`hand_joints` (156 floats) / `head_pose` (7 floats) 같은 vector-valued 채널을 viewer 가 이제 처리:

1. Backend (Python)

   • `StreamStatsBuffer` 에 `_latest_pose: Dict[str, List[float]]` 추가 — 최신 1개만 retain (300-sample rolling 은 메모리 폭발)
   • `StreamSnapshot` 에 `latest_pose` 필드 추가
   • SSE endpoint 가 `{channels, pose, label}` 로 전송 (pose=null 이면 기존 scalar-only 어댑터와 호환)

2. Frontend (React + Three.js)

   • `quest3-pose-panel.tsx` 신설 — R3F 로 cyan/orange hand skeleton + RGB-axis head rig 렌더링, OrbitControls 로 자유 시점
   • `use-sensor-stream.ts` 에 `pose` 스냅샷 state 추가 (버퍼링 안함 — 순간 pose 렌더링용)
   • `sensor-panel.tsx` dispatcher 가 `hand_joints` 감지 시 새 패널로 라우팅

3. Dependencies 추가: `three`, `@react-three/fiber`, `@react-three/drei`, `@types/three`. 번들 ~1MB gz 증가 (desktop viewer 라 수용 가능).

호환성

기존 scalar-only 어댑터는 `pose=null` 로 스트림 → hook/dispatcher 모두 기존 chart 경로로 폴백 → 행동 변화 0.

84개 unit 테스트 통과 (`pytest tests/unit/viewer tests/unit/adapters/test_meta_quest.py`).

스크린샷 참고

Panel 레이아웃/색상 tone:

• Cyan 왼손, 오렌지 오른손 (showcase 동일)
• 머리 RGB 좌표축 (R=X, G=Y, B=Z)
• 0.84m workspace 박스 + 그리드 바닥

Test Plan

• `yarn build` — frontend 타입체크 + 빌드 성공
• `pytest tests/unit/viewer tests/unit/adapters/test_meta_quest.py -q` — 84 passed
• 실제 Quest 3 + Unity sender 앱 실행 → example 로 end-to-end 녹화 검증

Out of scope

• 실제 Quest 3 하드웨어 검증은 별도로 사용자가 실행 필요 (`QUEST_IP` 수동 설정)
• Camera discovery 자동화 (Phase 2)
• Phase 2 H.264 인코딩 (현재 MJPEG-AVI)

🤖 Generated with Claude Code