手势控制3D粒子圣诞树：MediaPipe与Three.js完整源码实现

简介：这是一份面向前端开发者与3D交互爱好者的可运行源码包，聚焦手势识别与粒子渲染的结合，解决如何在网页端快速搭建可交互3D场景的问题。项目以Three.js完成粒子圣诞树的3D渲染，并借助MediaPipe实现握拳、张掌、旋转手掌、捏合指尖等手势识别，支持合拢态、散开态与照片放大态切换，还可上传照片融入场景，视觉上采用哑光绿、金属金与圣诞红营造节日高级感。压缩包共3个文件，约10KB，以html主页面为核心，辅以inscode配置与gitignore忽略规则，结构轻量，便于直接运行与二次改造。目前已有1970人学习下载。读者可从中获取完整可运行代码、手势与3D场景联动的实现思路，以及粒子形态切换与照片融合的具体写法，适合作为课程设计、节日互动页面或Three.js与MediaPipe入门练手的参考素材。

1. 手势控制3D粒子圣诞树：从摄像头到粒子系统的完整落地路径

去年年底想做一个展厅互动装置，需求很明确：观众站在屏幕前，不用碰任何设备，只靠手势就能让一棵由几万个发光粒子组成的圣诞树旋转、缩放、爆散再重组。听起来像是要动用深度相机或者雷达，实际上普通 RGB 摄像头加一个轻量手势识别模型就够了。这个标题拆开看是三层技术栈的叠加：手势识别负责把画面里的手部关键点提取出来，3D 粒子系统负责把几万个点渲染成树形并做动画，可运行源码则意味着这套东西要能在一台普通笔记本上跑起来，而不是停留在论文里的 demo。

适合谁看？前端想转互动开发的、做展厅装置的技术美术、以及手里有摄像头想玩点视觉项目的独立开发者。核心难点不在粒子数量，而在手势信号的稳定性和粒子动画的状态管理——手一抖，树就跟着抽搐，这是最常见的翻车点。下面按「先跑通最小闭环，再调参数，最后处理边界」的顺序展开，每一步都给出可复现的代码和参数含义。

2. 手势识别选型与最小可运行闭环

2.1 为什么用 MediaPipe Hands 而不是自己训模型

手势识别这条路有三条常见走法：一是用 OpenCV 的肤色分割加轮廓检测，优点是零依赖，缺点是光照一变就废，展厅顶灯稍微偏暖就识别不到；二是自己拿少量数据训一个 CNN 分类器，能识别固定几种手势，但泛化差，换个人换只手就要重新采数据；三是用现成的关键点检测模型，直接拿到 21 个手部关节坐标，再基于坐标做几何判断。

我一般会选第三条路。MediaPipe Hands 在普通 CPU 上单帧推理能压到 10ms 以内，输出 21 个关键点的归一化坐标，这意味着你不需要关心「这是石头还是布」，只需要关心「食指指尖和拇指指尖的距离是多少」「手腕到中指根部的向量朝向哪边」。几何判断比分类判断稳定得多，因为关键点坐标是连续量，可以做平滑滤波，而分类结果是离散的，一旦跳变就是硬切。

选型理由归结为三点：推理速度够快、关键点精度够用、不依赖特定手势库。代价是它对手部遮挡比较敏感，手背对镜头时关键点会飘，这个后面避坑章节会讲怎么处理。

2.2 最小闭环：摄像头到粒子旋转的完整代码

先跑通一个最小版本：用食指指尖的横向位置控制粒子树的 Y 轴旋转，用拇指和食指的捏合距离控制缩放。这段代码不依赖任何 3D 引擎，用 Canvas 2D 做粒子投影就够了，方便你先把信号链路调通。

# gesture_particle_min.py # 最小闭环：手势 -> 粒子树旋转/缩放 import cv2 import mediapipe as mp import numpy as np import math mp_hands = mp.solutions.hands hands = mp_hands.Hands( static_image_mode=False, max_num_hands=1, # 只跟踪一只手，减少误检 min_detection_confidence=0.6, min_tracking_confidence=0.5 ) # 生成树形粒子：圆锥螺旋分布 def build_tree_particles(n=3000, height=400, radius=160): pts = [] for i in range(n): t = i / n y = -height * t + height * 0.5 # 从底部到顶部 r = radius * (1 - t) # 越往上半径越小 angle = t * math.pi * 14 # 螺旋圈数 # 加一点随机抖动，避免粒子排列过于规整 jitter = np.random.normal(0, 3, 3) x = r * math.cos(angle) + jitter[0] z = r * math.sin(angle) + jitter[2] pts.append([x, y + jitter[1], z]) return np.array(pts) particles = build_tree_particles() rot_y = 0.0 scale = 1.0 cap = cv2.VideoCapture(0) cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640) cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 480) while True: ok, frame = cap.read() if not ok: break frame = cv2.flip(frame, 1) # 镜像，符合直觉 rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) result = hands.process(rgb) if result.multi_hand_landmarks: lm = result.multi_hand_landmarks[0].landmark # 关键点 8 = 食指指尖，4 = 拇指指尖 idx_tip = lm[8] thumb_tip = lm[4] # 横向位置映射到旋转角，范围 -1 到 1 rot_y = (idx_tip.x - 0.5) * 2 * math.pi # 捏合距离映射到缩放，距离范围经验值 0.02~0.25 dist = math.hypot(idx_tip.x - thumb_tip.x, idx_tip.y - thumb_tip.y) scale = np.clip(dist / 0.15, 0.4, 2.0) # 简单透视投影到 2D canvas = np.zeros((480, 640, 3), dtype=np.uint8) cos_a, sin_a = math.cos(rot_y), math.sin(rot_y) for p in particles: x = p[0] * cos_a - p[2] * sin_a z = p[0] * sin_a + p[2] * cos_a y = p[1] f = 500 / (500 + z) # 透视因子 sx = int(320 + x * f * scale) sy = int(240 + y * f * scale) if 0 <= sx < 640 and 0 <= sy < 480: cv2.circle(canvas, (sx, sy), 1, (0, 200, 120), -1) cv2.imshow('gesture_tree', canvas) if cv2.waitKey(1) & 0xFF == 27: break cap.release() cv2.destroyAllWindows()

逻辑说明：build_tree_particles用参数方程生成圆锥螺旋，t从 0 到 1 控制粒子从底部到顶部的分布，radius * (1 - t)让半径线性收缩形成树形，angle = t * math.pi * 14控制螺旋圈数，圈数越多树看起来越密。jitter是高斯抖动，不加的话粒子会排成一条完美的螺旋线，看起来像弹簧不像树。

参数说明：max_num_hands=1是关键，多手跟踪会让画面里出现两只手时粒子乱跳。min_detection_confidence=0.6和min_tracking_confidence=0.5是平衡灵敏度和稳定性的起点，光线暗的环境可以降到 0.5/0.4，但误检会变多。dist / 0.15里的 0.15 是归一化坐标下的经验距离，手离镜头远近不同这个值会变，所以后面要做动态归一化。

2.3 从 2D 投影升级到 Three.js 粒子系统

上面的 Canvas 版本能跑，但粒子超过 5000 就会掉帧，而且没有发光效果。实际交付时我会换成 Three.js 的Points，用自定义 Shader 做粒子大小随距离衰减和颜色渐变。

// three_tree.js // Three.js 粒子树核心：BufferGeometry + ShaderMaterial import * as THREE from 'three'; const COUNT = 20000; const positions = new Float32Array(COUNT * 3); const colors = new Float32Array(COUNT * 3); for (let i = 0; i < COUNT; i++) { const t = i / COUNT; const y = -400 * t + 200; const r = 160 * (1 - t); const angle = t * Math.PI * 14; positions[i * 3] = r * Math.cos(angle) + (Math.random() - 0.5) * 6; positions[i * 3 + 1] = y + (Math.random() - 0.5) * 6; positions[i * 3 + 2] = r * Math.sin(angle) + (Math.random() - 0.5) * 6; // 颜色从底部深绿渐变到顶部亮青 colors[i * 3] = 0.1 + t * 0.2; colors[i * 3 + 1] = 0.6 + t * 0.4; colors[i * 3 + 2] = 0.3 + t * 0.5; } const geometry = new THREE.BufferGeometry(); geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3)); geometry.setAttribute('color', new THREE.BufferAttribute(colors, 3)); const material = new THREE.ShaderMaterial({ vertexColors: true, transparent: true, depthWrite: false, blending: THREE.AdditiveBlending, vertexShader: ` attribute vec3 color; varying vec3 vColor; uniform float uScale; void main() { vColor = color; vec4 mv = modelViewMatrix * vec4(position * uScale, 1.0); gl_PointSize = 300.0 / -mv.z; // 距离越远点越小 gl_Position = projectionMatrix * mv; } `, fragmentShader: ` varying vec3 vColor; void main() { vec2 c = gl_PointCoord - vec2(0.5); float d = length(c); if (d > 0.5) discard; // 裁成圆形 float alpha = smoothstep(0.5, 0.0, d); gl_FragColor = vec4(vColor, alpha); } ` }); const tree = new THREE.Points(geometry, material); tree.material.uniforms = { uScale: { value: 1.0 } };

逻辑说明：AdditiveBlending是粒子发光的关键，它让重叠的粒子颜色相加而不是覆盖，密集区域自然变亮。gl_PointSize = 300.0 / -mv.z是透视衰减，mv.z是视图空间深度，取负是因为相机朝向 -Z。片元着色器里discard掉圆形外的像素，否则粒子是方块。

参数说明：COUNT = 20000是普通笔记本核显能稳 60 帧的上限，再往上要改用 InstancedMesh 或者降低粒子尺寸。uScale就是手势缩放要驱动的 uniform，每帧更新一次即可，不要重建 geometry。

3. 手势信号到粒子动画的映射与平滑

3.1 关键点坐标怎么变成稳定的控制量

原始关键点坐标抖动很大，直接映射到旋转角会让树疯狂抽搐。我一般做三级处理：先做指数移动平均（EMA）滤波，再做死区判断，最后做范围归一化。

# 信号平滑：EMA + 死区 class SmoothSignal: def __init__(self, alpha=0.3, dead_zone=0.01): self.alpha = alpha # 平滑系数，越小越稳但越滞后 self.dead_zone = dead_zone # 死区，变化小于此值不更新 self.value = None def update(self, raw): if self.value is None: self.value = raw return self.value delta = raw - self.value if abs(delta) < self.dead_zone: return self.value # 死区内保持不动 self.value = self.alpha * raw + (1 - self.alpha) * self.value return self.value

逻辑说明：alpha=0.3意味着新值占 30% 权重，旧值占 70%，手快速移动时会有约 3 帧滞后，但静止时几乎不抖。dead_zone=0.01是归一化坐标下的阈值，对应约 6 个像素，手静止时的微小抖动会被完全吃掉。

参数说明：alpha的取值要看帧率，30fps 下 0.3 合适，60fps 下可以降到 0.15 因为更新更频繁。dead_zone不要设太大，超过 0.03 会出现「手动了但树没反应」的粘滞感。

3.2 三种手势到三种动画状态的映射表

实际项目里不会只做一个旋转，通常要支持多个动作。下面是我常用的映射方案，用关键点之间的几何关系做判断，不依赖任何分类模型。

判断握拳和张开时，用「指尖到手腕的平均距离」比用单点更稳，因为单点容易被遮挡。手掌宽度用关键点 5（食指根部）到 17（小指根部）的距离做归一化，这样手离镜头远近不影响判断。

3.3 爆散与重组的状态机实现

爆散动画不能每帧重新计算，要用状态机管理。我一般定义三个状态：TREE（树形）、EXPLODE（爆散中）、REFORM（重组中），每个粒子记录自己的目标位置和当前速度。

// 粒子状态机：爆散与重组 const state = { mode: 'TREE', progress: 0 }; const explodeTargets = new Float32Array(COUNT * 3); function triggerExplode() { if (state.mode !== 'TREE') return; state.mode = 'EXPLODE'; state.progress = 0; for (let i = 0; i < COUNT; i++) { // 爆散目标：球面上随机点 const theta = Math.random() * Math.PI * 2; const phi = Math.acos(Math.random() * 2 - 1); const r = 300 + Math.random() * 200; explodeTargets[i * 3] = r * Math.sin(phi) * Math.cos(theta); explodeTargets[i * 3 + 1] = r * Math.cos(phi); explodeTargets[i * 3 + 2] = r * Math.sin(phi) * Math.sin(theta); } } function updateParticles(dt) { const pos = geometry.attributes.position.array; if (state.mode === 'EXPLODE') { state.progress = Math.min(1, state.progress + dt * 1.5); const e = 1 - Math.pow(1 - state.progress, 3); // easeOutCubic for (let i = 0; i < COUNT * 3; i++) { pos[i] += (explodeTargets[i] - pos[i]) * e * 0.1; } if (state.progress >= 1) state.mode = 'REFORM'; } else if (state.mode === 'REFORM') { // 向原始树形位置插值，逻辑同上，方向相反 } geometry.attributes.position.needsUpdate = true; }

逻辑说明：easeOutCubic让爆散先快后慢，视觉上更有冲击力。pos[i] += (target - pos[i]) * e * 0.1是线性插值，0.1是每帧逼近比例，太大会瞬移，太小会拖沓。

参数说明：dt * 1.5控制爆散总时长约 0.67 秒，展厅场景可以放慢到 1.0 秒让观众看清。r = 300 + Math.random() * 200是爆散半径，要大于树的原始半径 160，否则粒子飞不出去。

4. 性能调优与常见翻车排查

4.1 粒子数量与帧率的平衡

20000 个粒子在核显上跑 60 帧是上限，但如果你用的是集成显卡的老笔记本，可能要降到 8000。判断标准很简单：打开 Chrome 的 Performance 面板录 10 秒，看requestAnimationFrame的间隔是否稳定在 16.7ms。如果频繁跳到 33ms，就是粒子太多或者 Shader 太复杂。

优化手段按性价比排序：第一，把gl_PointSize的计算从片元着色器移到顶点着色器（上面代码已经是这样）；第二，关闭depthWrite和depthTest，粒子之间不需要深度排序；第三，如果还卡，把粒子颜色从逐顶点改成统一色加渐变纹理。

4.2 避坑：手势识别的五个血泪教训

现象：手一进画面树就疯狂旋转。原因：min_detection_confidence设太低，背景里的类手物体被误检。解决：提高到 0.7，同时加max_num_hands=1，并且只在关键点置信度大于 0.8 时才更新控制量。

现象：手静止时树缓慢漂移。原因：EMA 滤波的alpha太大，或者没有死区。解决：加dead_zone=0.015，并且对旋转角做模 2π 的环绕处理，避免从 π 跳到 -π 时产生突变。

现象：捏合缩放时大时小。原因：用绝对距离而不是归一化距离，手离镜头近时距离大，远时距离小。解决：除以手掌宽度做归一化，手掌宽度用关键点 5 到 17 的距离。

现象：爆散后粒子回不到树形。原因：重组时目标位置被爆散过程覆盖了。解决：在build_tree_particles时把原始位置存一份到originalPositions，重组时向这份数据插值，不要向positions的当前值插值。

现象：换个人来玩就识别不到。原因：不同人的手部比例差异大，固定阈值不通用。解决：在检测到手掌后先做一次标定，记录该用户手掌宽度和手指长度的比例，后续判断用相对值。

4.3 摄像头参数与光照的隐性影响

摄像头自动曝光是手势项目里最容易被忽略的坑。展厅灯光变化时，摄像头会自动调整曝光，导致画面亮度突变，MediaPipe 的关键点会跟着跳。我一般会锁定曝光和白平衡，OpenCV 里用cap.set(cv2.CAP_PROP_AUTO_EXPOSURE, 0.25)关闭自动曝光，然后手动设一个中间值。如果摄像头不支持，就在画面进入识别前做一次直方图均衡化，减少光照波动的影响。

另外，摄像头帧率要和渲染帧率解耦。手势识别不需要 60fps，15fps 足够，可以用一个独立线程做识别，主线程只读最新结果。这样即使识别偶尔卡顿，粒子动画也不会掉帧。

5. 从可运行源码到可交付装置的最后一公里

源码能跑和装置能用之间，差的是「无人值守」这四个字。展厅里没有人会帮你按 F5，所以要做三件事：自动重连摄像头、异常状态自恢复、以及一个隐藏的调试入口。

自动重连的逻辑是监听cap.read()的返回值，连续 10 帧失败就释放摄像头重新VideoCapture(0)，中间加 2 秒延迟避免频繁重试。异常自恢复是指当连续 3 秒检测不到手时，粒子自动回到树形并缓慢自转，避免画面死寂。调试入口我一般做成「五指张开保持 3 秒」触发，弹出参数面板可以实时调alpha、dead_zone和粒子数量，调完再收起来。

验证方法上，我会用一个简单的脚本记录每帧的识别耗时和渲染耗时，跑 10 分钟看 P99 延迟。如果 P99 超过 50ms，说明有偶发的卡顿，通常是垃圾回收或者摄像头缓冲区堆积，需要把识别结果用环形缓冲区存，只取最新一帧。

最后说一个我自己的习惯：每次交付前，我会让完全没接触过这个项目的人站在摄像头前玩 5 分钟，不说话，只看他们的手部动作。如果他们不自觉地做出「捏合」「挥手」这些动作，说明映射符合直觉；如果他们愣在那里不知道手该放哪，说明需要加一个引导动画。技术参数可以调，但直觉这东西调不出来，只能靠观察。希望帮到你。

本文还有配套的精品资源，点击获取