基于MediaPipe与Two.js的手势交互项目Clawspace开发实践

1. 项目概述与核心价值

最近在GitHub上看到一个挺有意思的项目，叫nickytonline/clawspace。乍一看这个名字，可能会有点摸不着头脑，“Claw Space”直译是“爪子空间”，听起来像是个游戏或者某种创意工具。点进去深入研究后，我发现这是一个将物理世界的手势交互与数字创作空间结合起来的开源项目，简单说，它让你能用摄像头捕捉手部动作，然后实时控制屏幕上的虚拟“爪子”进行绘图、操控物体，甚至进行一些基础的3D建模操作。

这个项目的核心价值在于它极大地降低了动作捕捉和创意编程的门槛。传统的动作捕捉需要昂贵的硬件（如Leap Motion、深度摄像头）和复杂的SDK集成，而Clawspace巧妙地利用了成熟的计算机视觉库（如MediaPipe），仅通过普通的网络摄像头就能实现相当精准的手部21个关键点识别。开发者将识别到的手部骨骼数据，映射为一个可自定义的、带有“爪子”的虚拟控制器，从而在浏览器中开辟出一个低延迟、高互动性的创作沙盒。

它非常适合几类人：创意编程爱好者、交互装置艺术家、前端开发者想给自己的项目增加酷炫的交互，以及教育工作者想向学生展示人机交互的趣味性。你不需要是计算机视觉专家，只要对JavaScript和基本的向量数学有了解，就能基于这个项目快速搭建出自己的手势交互应用。接下来，我会深入拆解它的技术架构、实现细节，并分享如何从零开始复现和扩展这样一个项目。

2. 技术架构与核心依赖解析

Clawspace的技术栈选择体现了现代前端项目“轻量、高效、模块化”的特点。其核心是运行在浏览器环境中的，这保证了跨平台性和易用性。

2.1 前端框架与构建工具

项目基于React和TypeScript构建。React的组件化思想非常适合此类UI状态频繁更新的交互应用。虚拟“爪子”的状态（位置、开合、旋转）、画布上的笔迹或物体，都可以被建模为React组件的状态或属性。TypeScript的静态类型检查则为处理复杂的手部关键点数据（一个包含21个点、每个点有x, y, z坐标的对象）提供了安全保障，能有效避免在计算向量、角度时出现属性访问错误。

构建工具通常使用Vite。相比于传统的Webpack，Vite在开发阶段的冷启动和热更新速度有巨大优势，这对于需要频繁调整参数、实时预览交互效果的开发流程至关重要。vite.config.ts中会配置好对GLSL着色器文件（如果涉及WebGL渲染）、静态资源等的处理。

2.2 计算机视觉核心：MediaPipe Hands

这是项目的基石。MediaPipe是Google开源的一个跨平台多媒体机器学习模型应用框架。其中的MediaPipe Hands解决方案提供了端到端的手部关键点检测模型。它的优势在于：

1. 纯浏览器端运行：模型通过TensorFlow.js或MediaPipe的JavaScript API运行，无需后端服务器处理视频流，保证了低延迟和隐私性。
2. 高精度与性能：提供21个3D手部地标点（从手腕到指尖各个关节），即使在复杂背景下也有不错的鲁棒性。它支持两种模型：lite（速度快，精度稍低）和full（精度高，速度稍慢），开发者可以根据实际设备性能进行权衡。
3. 易于集成：官方提供了清晰的JavaScript API，几行代码就能初始化检测器并开始从<video>元素中获取关键点数据。

在Clawspace中，会初始化一个Hands检测器，并设置回调函数。每一帧视频处理完成后，回调函数会收到一个results对象，里面包含了检测到的每只手的关键点数组、手势分类（如“张开的手”、“握拳”、“食指指向”）以及手的偏手性（左手/右手）。

2.3 图形渲染层：Two.js vs. Three.js

如何将抽象的关键点数据转化为屏幕上可见的、可交互的图形，这里有两种主流选择，也体现了项目的不同侧重点：

• Two.js：一个轻量级的二维绘图API封装库。如果你的Clawspace主要专注于2D绘图（用手势控制画笔、移动2D图形），那么Two.js是绝佳选择。它语法简洁，易于上手，能很好地与SVG、Canvas、WebGL渲染上下文协同工作。在Clawspace的2D模式中，可能会用Two.js来绘制“爪子”的图形、画笔轨迹以及画布上的其他元素。
• Three.js：强大的3D图形库。如果项目目标是实现3D空间中的抓取、旋转物体，或者想让“爪子”和场景拥有更逼真的光影效果，Three.js是必然之选。它需要处理3D坐标系、摄像机、光照、材质等复杂概念。MediaPipe Hands提供的本就是3D关键点（z值表示深度），可以经过一个简单的透视投影转换，直接映射到Three.js的3D场景中，实现更沉浸的交互。

在复现时，你需要根据项目目标做选择。一个进阶架构是抽象一个“渲染器层”，底层对接Two.js或Three.js，上层业务逻辑只关心“爪子”的状态数据，从而实现2D/3D渲染后端的可切换。

2.4 状态管理与物理模拟

• 状态管理：即使使用React，对于复杂的交互状态（多个可抓取物体、画布历史记录、不同工具模式），仅用React Context可能显得力不从心。像Zustand或Jotai这类轻量级状态库非常适合此场景。它们能让你在组件外管理“爪子”和场景的状态，逻辑更清晰。
• 物理引擎（可选）：如果想让虚拟物体的交互更真实（例如抓取后抛出，物体具有重量和碰撞），可以集成一个轻量级的物理引擎，如Cannon-es(Three.js常用) 或Matter.js(2D)。但这会显著增加复杂度，需要处理物理世界与渲染世界的同步。

注意：MediaPipe模型对光照和手部与摄像头的相对角度比较敏感。在光线不足或手部过度旋转（如手心完全朝向摄像头）时，检测可能会失败或抖动。这是所有基于视觉的手势识别共有的挑战，在应用设计中需要加入容错机制，比如状态平滑滤波。

3. 从零实现核心交互逻辑

理解了架构，我们动手实现一个最核心的功能：用手控制一个虚拟“爪子”在2D画布上移动和开合。这里我们选择Two.js作为渲染引擎。

3.1 项目初始化与环境搭建

首先，创建一个标准的Vite + React + TypeScript项目：

npm create vite@latest clawspace-demo -- --template react-ts cd clawspace-demo npm install

然后安装核心依赖：

npm install @mediapipe/hands two.js npm install @types/two.js --save-dev # 用于TypeScript类型提示

3.2 初始化MediaPipe Hands与视频流

创建一个组件HandTracker.tsx：

import { useEffect, useRef } from 'react'; import { Hands, Results } from '@mediapipe/hands'; import { Camera } from '@mediapipe/camera_utils'; const HandTracker = ({ onResults }: { onResults: (results: Results) => void }) => { const videoRef = useRef<HTMLVideoElement>(null); const canvasRef = useRef<HTMLCanvasElement>(null); useEffect(() => { const hands = new Hands({ locateFile: (file) => `https://cdn.jsdelivr.net/npm/@mediapipe/hands/${file}`, }); hands.setOptions({ maxNumHands: 1, // 先只追踪一只手 modelComplexity: 1, // 使用‘full’模型，精度更高 minDetectionConfidence: 0.5, minTrackingConfidence: 0.5, }); hands.onResults(onResults); if (videoRef.current) { const camera = new Camera(videoRef.current, { onFrame: async () => { if (videoRef.current) { await hands.send({ image: videoRef.current }); } }, width: 640, height: 480, }); camera.start(); } return () => { hands.close(); }; }, [onResults]); return ( <div style={{ position: 'absolute', top: 0, left: 0 }}> <video ref={videoRef} style={{ display: 'none' }} /> <canvas ref={canvasRef} width="640" height="480" /> </div> ); }; export default HandTracker;

这段代码初始化了Hands检测器，并启动摄像头。视频流在隐藏的<video>元素中，结果会绘制到<canvas>上（MediaPipe内部完成）。onResults回调函数将关键点数据传递给父组件。

3.3 构建虚拟“爪子”控制器

这是项目的灵魂。我们需要将手部21个关键点，映射为一个可控制的“爪子”状态。一个简单的“爪子”可以由两个或三个“手指”组成，每个手指有开合角度。

// types.ts export interface Landmark { x: number; // 归一化坐标 [0, 1] y: number; z: number; // 相对深度 } export interface ClawState { position: { x: number; y: number }; // 爪子中心在画布上的坐标 rotation: number; // 整体旋转角度（弧度） fingers: { isPinching: boolean; // 是否处于捏合状态（用于抓取/绘画） pinchStrength: number; // 捏合力度 [0, 1] spread: number; // 手指张开角度 [0, 1] }; } // utils/clawMapper.ts export const mapHandToClaw = (landmarks: Landmark[]): ClawState | null => { if (!landmarks || landmarks.length < 21) return null; // 1. 计算爪子中心：通常取手掌根部（手腕点，索引0）或所有指尖的平均值 const wrist = landmarks[0]; const indexTip = landmarks[8]; const thumbTip = landmarks[4]; // 将归一化坐标转换为画布坐标（假设画布640x480） const canvasX = wrist.x * 640; const canvasY = wrist.y * 480; // 2. 计算捏合状态：检查拇指尖和食指尖的距离 const pinchDistance = Math.sqrt( Math.pow((thumbTip.x - indexTip.x) * 640, 2) + Math.pow((thumbTip.y - indexTip.y) * 480, 2) ); const isPinching = pinchDistance < 30; // 像素距离阈值，可调 const pinchStrength = Math.max(0, 1 - pinchDistance / 100); // 距离越小，力度越大 // 3. 计算手指张开角度：例如，通过食指、中指、无名指的指尖与手掌中心的向量夹角来估算 const middleTip = landmarks[12]; const ringTip = landmarks[16]; // ... 向量计算省略，可用余弦定理 const spread = 0.5; // 简化计算，实际需要更复杂的几何 return { position: { x: canvasX, y: canvasY }, rotation: 0, // 可通过手腕和食指根部的向量计算方向 fingers: { isPinching, pinchStrength, spread, }, }; };

3.4 使用Two.js渲染与响应交互

现在，我们在主组件中将状态和渲染连接起来：

// App.tsx import { useEffect, useRef, useState } from 'react'; import Two from 'two.js'; import HandTracker from './HandTracker'; import { mapHandToClaw } from './utils/clawMapper'; import { Results } from '@mediapipe/hands'; import './App.css'; function App() { const [clawState, setClawState] = useState<ClawState | null>(null); const twoContainerRef = useRef<HTMLDivElement>(null); const twoInstanceRef = useRef<Two | null>(null); const clawGroupRef = useRef<Two.Group | null>(null); // 初始化Two.js场景 useEffect(() => { if (!twoContainerRef.current || twoInstanceRef.current) return; const two = new Two({ width: 640, height: 480, domElement: twoContainerRef.current, }); twoInstanceRef.current = two; // 创建爪子图形：一个圆（手掌）和三条线（手指） const palm = two.makeCircle(0, 0, 15); palm.fill = '#FF6B6B'; palm.stroke = '#FF5252'; const finger1 = two.makeLine(-10, -10, -30, -40); const finger2 = two.makeLine(0, -15, 0, -45); const finger3 = two.makeLine(10, -10, 30, -40); [finger1, finger2, finger3].forEach(f => { f.stroke = '#4ECDC4'; f.linewidth = 5; f.cap = 'round'; }); const group = two.makeGroup(palm, finger1, finger2, finger3); clawGroupRef.current = group; two.bind('update', () => { // 动画循环，根据clawState更新图形 if (clawState && clawGroupRef.current) { const { position, fingers } = clawState; clawGroupRef.current.translation.set(position.x, position.y); // 根据fingers.spread更新手指线条的终点，模拟开合 const spreadOffset = fingers.spread * 20; finger1.vertices[1].set(-30 - spreadOffset, -40); finger3.vertices[1].set(30 + spreadOffset, -40); // 根据pinchStrength改变颜色或粗细 const lineWidth = 3 + fingers.pinchStrength * 4; finger2.linewidth = lineWidth; } }).play(); // 启动动画循环 return () => { two.unbind('update'); two.pause(); }; }, []); // 处理手部检测结果 const handleHandResults = (results: Results) => { if (results.multiHandLandmarks && results.multiHandLandmarks.length > 0) { const landmarks = results.multiHandLandmarks[0]; const state = mapHandToClaw(landmarks); setClawState(state); // 如果处于捏合状态，触发“绘画”或“抓取”动作 if (state?.fingers.isPinching) { drawAtPosition(state.position); } } else { setClawState(null); } }; const drawAtPosition = (pos: { x: number; y: number }) => { if (!twoInstanceRef.current) return; const two = twoInstanceRef.current; const dot = two.makeCircle(pos.x, pos.y, 3); dot.fill = '#556270'; dot.noStroke(); two.update(); // 立即更新渲染 }; return ( <div className="app"> <HandTracker onResults={handleHandResults} /> <div ref={twoContainerRef} style={{ position: 'absolute', top: 0, left: 0 }} /> <div className="status"> {clawState ? `爪子在 (${clawState.position.x.toFixed(0)}, ${clawState.position.y.toFixed(0)})` : '未检测到手部'} </div> </div> ); } export default App;

至此，一个最基础的、用手势控制屏幕虚拟爪子移动和进行点状绘制的Clawspace就实现了。摄像头捕捉你的手，手腕移动控制爪子中心移动，拇指和食指捏合会在画布上留下痕迹。

4. 高级功能扩展与性能优化

基础版本跑通后，我们可以考虑添加更多功能，让它更像一个完整的“创作空间”。

4.1 实现物体抓取与操控

在2D场景中抓取一个物体，需要引入“可交互对象”的概念。

1. 定义可抓取对象：每个对象应有位置、大小、是否被抓住的状态。

   interface GrabbableObject { id: string; position: { x: number; y: number }; radius: number; isGrabbed: boolean; element: Two.Circle; // 关联的图形对象 }

2. 碰撞检测：在每一帧动画循环中，检查“爪子”的捏合点（例如食指尖）是否与任何对象的边界相交（圆形或矩形碰撞）。

   function checkGrab(clawPos: Vector, objects: GrabbableObject[]): GrabbableObject | null { for (const obj of objects) { const distance = Math.sqrt( Math.pow(clawPos.x - obj.position.x, 2) + Math.pow(clawPos.y - obj.position.y, 2) ); if (distance < obj.radius) { return obj; } } return null; }

3. 状态绑定：当检测到捏合且发生碰撞时，将对象的状态isGrabbed设为true，并记录爪子与对象的初始偏移量。在后续帧中，如果爪子仍在捏合状态，则更新对象的位置为爪子位置 + 初始偏移量。松开捏合时，将isGrabbed设为false。

4.2 引入工具模式与UI

一个完整的创作空间应有不同的模式，如“绘图模式”、“擦除模式”、“物体模式”。

• 状态管理：使用状态管理库（如Zustand）来管理当前激活的工具。

  import { create } from 'zustand'; interface ToolStore { activeTool: 'draw' | 'erase' | 'grab'; brushSize: number; brushColor: string; setTool: (tool: ToolStore['activeTool']) => void; // ...其他actions }

• UI界面：在画布上方或侧边添加一个简单的工具栏，点击按钮调用setTool来切换模式。在不同的onResults处理逻辑中，根据activeTool执行不同的操作（画点、清除区域、尝试抓取）。

4.3 关键性能优化点

当画布元素增多或逻辑变复杂时，性能问题会显现。

1. 节流与防抖：onResults回调频率很高（通常与摄像头帧率一致，30fps）。对于不需要每帧都响应的操作（如切换工具、更改画笔颜色），应使用防抖函数。对于连续绘制，可以适当节流，比如每2帧画一次点，在流畅度和性能间取得平衡。
2. 对象池：在绘图模式下，频繁创建和销毁图形对象（点、线）会产生垃圾回收压力。可以预先创建一定数量的图形对象放入“池”中，需要时激活并设置位置，不需要时隐藏并放回池中。
3. 分层渲染：使用Two.js或Canvas的离屏渲染（OffscreenCanvas）技术。将静态背景、动态的爪子和物体、临时笔迹分别绘制在不同的图层上。这样只需要重绘变化的图层，能大幅提升性能。
4. 检测器参数调优：根据实际场景调整MediaPipe Hands的modelComplexity和置信度阈值。在保证识别率的前提下，使用lite模型能提升性能。如果只追踪一只手，务必设置maxNumHands: 1。

4.4 手势识别优化与平滑处理

原始的关键点数据会有抖动，直接使用会导致爪子抖动。

1. 卡尔曼滤波或低通滤波：对关键点的位置（x, y）应用滤波算法。一个简单有效的低通滤波器可以这样实现：

   let smoothedX = 0; let smoothedY = 0; const smoothingFactor = 0.3; // 平滑因子，0~1，越大越平滑但延迟越高 function smoothPosition(newX, newY) { smoothedX = smoothedX * (1 - smoothingFactor) + newX * smoothingFactor; smoothedY = smoothedY * (1 - smoothingFactor) + newY * smoothingFactor; return { x: smoothedX, y: smoothedY }; }

2. 手势状态机：对于“捏合”这种手势，不要只基于单帧的距离阈值判断。可以引入一个简单的状态机（如“空闲”->“准备捏合”->“捏合中”->“释放”），只有连续多帧满足条件才切换状态，能有效避免误触发。

5. 部署、调试与常见问题排查

5.1 本地开发与调试技巧

1. 摄像头权限问题：现代浏览器要求HTTPS环境或localhost才能访问摄像头。确保你在http://localhost:5173下开发。如果遇到权限被拒绝，检查浏览器设置，并确保没有其他应用独占摄像头。
2. MediaPipe模型加载：locateFile函数配置了CDN地址。如果网络环境不佳导致模型加载慢或失败，可以考虑将@mediapipe/hands的模型文件（.bin, .tflite）下载到项目的public目录，然后修改locateFile指向本地路径。
3. 使用屏幕坐标模拟：在开发手势逻辑时，可以暂时屏蔽摄像头，用鼠标事件来模拟手部移动和捏合（鼠标按下视为捏合），这能极大提高调试UI和交互逻辑的效率。

   // 调试用：用鼠标模拟爪子 useEffect(() => { const handleMouseMove = (e: MouseEvent) => { setClawState({ position: { x: e.clientX, y: e.clientY }, fingers: { isPinching: false, pinchStrength: 0, spread: 0.5 } }); }; const handleMouseDown = () => {/* 模拟捏合 */}; window.addEventListener('mousemove', handleMouseMove); // ... }, []);

5.2 构建与部署

使用Vite构建生产版本非常简单：

npm run build

生成的dist目录包含了所有静态资源。你可以将其部署到任何静态网站托管服务，如Vercel,Netlify,GitHub Pages或你自己的服务器。

重要提示：由于项目使用了摄像头，部署到生产环境后必须使用HTTPS。大多数现代浏览器在非HTTPS页面上会完全禁止访问getUserMediaAPI（调用摄像头）。Vercel和Netlify等平台默认提供HTTPS。

5.3 常见问题与解决方案速查表

5.4 进阶方向探索

当你完成了基础版本后，可以尝试以下方向让项目更具吸引力：

• 3D化：将渲染引擎切换到Three.js。将MediaPipe的3D关键点（注意其z轴是相对深度，不是真实世界尺度）通过一定比例映射到Three.js场景中。实现用“爪子”抓取、旋转、缩放3D模型。
• 多手势识别：利用MediaPipe返回的gestures信息，识别“张开手”、“握拳”、“胜利手势”等，并绑定不同的操作（握拳擦除、张开手选择等）。
• 协作空间：使用WebSocket（如Socket.io）搭建一个简单的服务器，让多个用户的“爪子”同时出现在同一个画布空间中，实现远程协同创作。
• 导出与保存：实现将画布内容导出为PNG图片或SVG矢量图的功能。利用Two.js的two.renderer.domElement.toDataURL()可以轻松实现截图。

这个项目的魅力在于，它用一个相对简单的技术组合，打开了一扇通往趣味人机交互的大门。从技术上看，它串联起了计算机视觉、前端图形学、交互设计和实时通信等多个领域。从创作上看，它把身体动作变成了创作工具的一部分，这种直接的映射关系带来了非常直观和有趣的体验。我自己的体会是，调试手势识别的参数（如阈值、平滑系数）是一个需要耐心和反复实验的过程，因为每个人的手大小、移动习惯都不同，找到一组普适性较好的参数能让用户体验提升一个档次。另外，在性能优化上，离屏渲染和对象池带来的帧率提升是立竿见影的，尤其是在低端设备上，这部分投入非常值得。