這是一套前端實時姿態捕獲與 3D 可視化的 DEMO，特點是啟動快、UI 現代、渲染穩定，同時對設備性能與網絡情況做了多處優化。
預覽地址
技術棧與核心依賴
- 框架與工程：Vite + React + TypeScript
- 實時姿態識別：MediaPipe Tasks Vision（PoseLandmarker）
- 三維渲染：Three.js（OrbitControls 動態導入）
- UI/樣式：現代玻璃擬態風格 + 自定義 Loading
功能總覽
- 實時相機捕獲與姿態識別（身體骨架）
- 三維骨架可視化（顏色分區、發光、光照增強）
- 角度信息面板（可自動隱藏，僅在有數據時顯示）
- 全局加載遮罩（等待 MediaPipe + Three.js 完成）
- 手動啟動/停止相機控制（支持自動啟動模式）
關鍵模塊與結構
src/components/CameraCapture/CameraCapture.tsx- 負責相機權限、視頻流、MediaPipe 推理、數據結構轉換
- 提供
onPoseDetection,onReady,onStarted,onStopped - 支持按鈕控制“啟動相機/停止相機”
src/components/PoseVisualizer/PoseVisualizer.tsx- Three.js 場景、光照與骨架渲染
- 動態導入
OrbitControls，限制旋轉角度，不卡交互 angle-display面板：僅在有數據時顯示，避免遮擋
src/App.tsx- 負責兩個模塊組合 + 全局加載遮罩
MediaPipe 接入要點
- 預加載
- 啟動時預創建 PoseLandmarker，后續組件共享，減少首次推理延遲
- 推理節流
- 使用
requestAnimationFrame，同時用 33ms 限制至 ~30FPS，減輕負載
- 使用
- 結果轉換
- 將
results.landmarks轉為統一PoseData，包含landmarks與connections
- 將
示例（推理節流核心邏輯片段）：
const now = performance.now();
const elapsed = now - lastDetectTimeRef.current;
if (elapsed >= 33) {lastDetectTimeRef.current = now;const poseResults = poseLandmarkerRef.current.detectForVideo(videoEl, now);// 轉換數據后 onPoseDetection(poseData)
}
Three.js 可視化策略
- 場景與光照
AmbientLight + DirectionalLight + PointLight增強立體感- 關閉陰影、降低
pixelRatio，保性能穩定
- 骨架渲染
- 關節點使用不同尺寸與顏色分區，提升可視效果
- 線條色彩柔和（透明度 0.8），避免視覺噪聲
- 交互限制
OrbitControls限制旋轉范圍，支持小幅觀察，不允許拖拽離場景
UI/交互設計
- 全局 Loading 遮罩
- 等 MediaPipe + Three.js 均完成后自動消失
- 手動相機控制
- 頂部按鈕：啟動/停止
- 卸載時清理流與動畫幀，避免內存泄漏
- 角度信息條 angle-display
- 僅在有角度數據時展示；否則隱藏，不遮擋畫面
- 背景為淺色玻璃風格，支持移動端可讀性
性能優化清單
- MediaPipe
- 預加載模型，避免首幀等待
- 推理節流至 ~30FPS
- Three.js
- 關閉陰影、降低抗鋸齒與像素密度上限
- 節省幾何細分（SphereGeometry 16/16）
- 網絡與構建
- Vite 插件移除第三方 sourcemap 注釋，避免控制臺噪音
- 手動切換為本地模型與本地 wasm（可選，弱網/內網環境）
常見問題與排查
- 模型/wasm 拉取失敗
- 檢查 CDN 可訪問性，或改為本地：將模型放到
public/models/pose_landmarker_lite.task - wasm 路徑：默認 CDN。如需離線，將
@mediapipe/tasks-vision/wasm同名文件復制至public/mediapipe/wasm/，并修改FilesetResolver.forVisionTasks('/mediapipe/wasm')
- 檢查 CDN 可訪問性，或改為本地：將模型放到
- 擴展攔截 fetch
- 使用無痕窗口或禁用攔截擴展
- DevTools Network 查看失敗 URL
體驗與易用性
- 打開即用（默認自動啟動相機）；也支持手動控制
- 視覺現代化：玻璃面板、漸變、光效與動效
- 移動端自適應：容器尺寸與文本字號優化
可繼續演進的方向
- 角度計算實現（肩/肘/膝等）并在面板展示歷史曲線
- 錄制模式：保存姿態數據或渲染視頻
- 更多皮膚主題（暗/亮主題切換）
- 多模型支持（如 Holistic / Hands / Face）可開關切換
- 性能自適應（根據設備性能自動降低幾何細分與像素比）
)
