基于 MediaPipe + Three.js 的实时姿态可视化前端

这是一套前端实时姿态捕获与 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')
• 扩展拦截 fetch
  • 使用无痕窗口或禁用拦截扩展
  • DevTools Network 查看失败 URL

体验与易用性

• 打开即用（默认自动启动相机）；也支持手动控制
• 视觉现代化：玻璃面板、渐变、光效与动效
• 移动端自适应：容器尺寸与文本字号优化

可继续演进的方向

• 角度计算实现（肩/肘/膝等）并在面板展示历史曲线
• 录制模式：保存姿态数据或渲染视频
• 更多皮肤主题（暗/亮主题切换）
• 多模型支持（如 Holistic / Hands / Face）可开关切换
• 性能自适应（根据设备性能自动降低几何细分与像素比）