跳到主要内容
AI教程

使用 WonderSnap 构建和控制 GPU 粒子模型

本教程将向你介绍如何安装 WonderSnap、在本地启动、通过手势或键盘输入控制交互式粒子模型、调整性能设置、探索高级教育功能，以及运行 Playwright 测试套件。

AI我搜编辑部阅读约 10 分钟
使用 WonderSnap 构建和控制 GPU 粒子模型

什么是 WonderSnap？

WonderSnap 是一款基于浏览器的 3D 体验，可将程序化模型转化为由 GPU 驱动、最多包含 250,000 个粒子的发光云团。你可以打响手指召唤粒子，将它们组成地标或解剖结构，用手旋转模型，并将组件展开为带标签的爆炸视图。

该应用结合了设备端手部追踪、自定义手势识别、程序化模型以及手写的 WebGL2 渲染器。它不使用 Three.js、游戏引擎或前端框架。摄像头视频会保留在你的设备上，不会发送到服务器。

摄像头为可选设备。所有必要的交互也都可以通过屏幕控件、键盘和鼠标完成。

主要功能

  • GPU 粒子渲染：粒子物理通过 WebGL2 transform feedback 运行，支持最多 250,000 个粒子。
  • 设备端手部追踪：MediaPipe Hand Landmarker 最多可追踪两只手，每只手包含 21 个关键点。
  • 手势识别：自定义分类器可识别打响手指、握拳、张开手掌、指向、捏合、V 字手势、手部旋转和双手缩放。
  • 33 个程序化模型：模型集合涵盖地标、解剖结构、生物学、发动机、车辆和机械设备。
  • 交互式部件：命名组件可以发光、分离为爆炸视图、显示标签，并可拉出以便近距离查看。
  • 动画解剖结构：心脏以每分钟 72 次的速度跳动，肺部则以 4.5 秒为一个周期呼吸。
  • 教育工具：测验模式会要求你识别部件，同时提供描述和语音功能进行讲解。
  • 语音控制：Chrome 和 Edge 可以处理 show me the heart、zoom in 和 quiz 等指令。
  • 剖切与录制：你可以显示发光的剖面，并将场景保存为 WebM 视频。

运行要求

安装 WonderSnap 前，请确认你具备以下条件：

  • Node.js 18 或更高版本。
  • Chrome 或 Edge，以获得文档所述的浏览器体验。
  • 如果需要使用手势控制，则需要摄像头。
  • 支持 WebGL2 的浏览器和设备。

摄像头必须通过 localhost 或 HTTPS 地址访问。不要通过双击 index.html 启动应用，而应使用随附的本地服务器。

安装并启动 WonderSnap

1. 克隆代码仓库

git clone https://github.com/AkbarSheikh-debug/wondersnap.git
cd wondersnap

2. 安装依赖

npm install

此步骤还会让手部追踪运行时可从 node_modules 中使用。如果 MediaPipe 始终无法加载，请确认安装已成功完成。

3. 启动本地服务器

npm start

在 Chrome 或 Edge 中打开 http://localhost:5173。选择 Start with camera 以启用手部追踪，或选择 Continue without camera，使用鼠标、键盘和屏幕控件。

4. 必要时使用其他端口

如果端口 5173 已被占用，请在启动命令中传入其他端口：

npm start -- 8080

然后你可以打开 http://localhost:8080。

基本手势操作流程

授予摄像头访问权限后，将手放在摄像头能够清晰看到的位置。典型的交互流程如下：

  1. 打响手指以召唤粒子。再次打响手指会溶解当前模型。
  2. 握拳以形成选中的奇观、器官、车辆、发动机或机械设备。
  3. 抬起、扭转或倾斜手部以旋转和倾斜已形成的模型。
  4. 张开手掌将奇观切换到下一个模型。对于器官、发动机和车辆，张开手掌可以控制部件向外爆炸的程度；合拢手掌则会使它们重新组合。
  5. 指向某个部件并将手指停留在其上方以选中它。该部件会发光，信息卡会介绍其作用。
  6. 捏合以将选中的部件拉向自己。再次捏合可将其放回原处。
  7. 使用双手并改变两手之间的距离，以放大或缩小视图。
  8. 做出 V 字手势以跳转到下一个模型。

使用键盘和鼠标

如果没有摄像头，或希望进行更精确的控制，可以使用键盘和鼠标。点击部件即可选中它，拖动场景即可旋转视图。

  • 空格：模拟打响指。
  • F、O 和 V：触发握拳、张开手掌和胜利手势动作。
  • 左箭头 和 右箭头：选择上一个或下一个模型。
  • E、上箭头、下箭头 或鼠标滚轮：调整爆炸视图。
  • +、- 和 0：改变或重置缩放。也可以按住 Control 并使用鼠标滚轮。
  • C：打开或关闭摄像头。
  • L：切换部件标签。
  • R：切换自动旋转。
  • G：启用或禁用基于手势的旋转。
  • X：启用剖切横截面。使用 , 和 . 微调切割平面。
  • Q：开始测验模式。
  • M：使用语音命令和朗读功能。
  • K：录制视频。
  • D：播放内置演示。
  • I：描述所选部件。
  • Esc：取消选择当前部件。
  • H：显示帮助。

探索模型集合

WonderSnap 包含 33 个根据真实测量数据生成的程序化模型，分为六组：

  • 奇观：十一处地标，包括埃菲尔铁塔、吉萨大金字塔、泰姬陵、大本钟和悉尼歌剧院。
  • 人体解剖：十个模型，包括大脑、跳动的心脏、呼吸中的肺、骨骼和分层人体。
  • 生物学：一条可以解链的 DNA 双螺旋和一个动物细胞。
  • 发动机：直列四缸发动机、机械增压 HEMI V8、涡扇喷气发动机和九缸星型发动机。
  • 交通工具：跑车、摩托车、客机和可分级分离的土星 V 号。
  • 机械：机械腕表，以及包含电芯、汇流排、冷却系统和电池管理系统的电动汽车电池组。

使用教育功能

检查带标签的部件

将指针移到组件上或点击组件即可选择它。选中的部件会发光，其卡片会解释其功能。按 L 启用标签，显示连接名称与各个部件的引导线。

开始测验

按 Q 进入测验模式。WonderSnap 会显示类似 查找：海马体 的提示。将指针移到或点击所要求的组件。每次测验包含五道题，并会生成分数。

通过语音控制场景

按 M 使用语音命令和朗读功能。支持的示例包括 show me the heart、open it up、where is the right atrium、zoom in 和 quiz。语音合成功能已针对 Chrome 和 Edge 编写说明。

创建剖切视图

按 X 启用剖切视图。切割平面可以跟随手部移动，并显示发光的横截面。没有手势输入时，使用 , 和 . 逐步移动平面。

录制结果

按 K 录制场景，并将其保存为 WebM 视频。

使用 URL 选项配置 WonderSnap

查询字符串选项可以改变启动行为并调整渲染设置，无需编辑源文件。

  • ?n=250000：设置粒子数量。
  • ?model=12：从指定的模型编号开始。
  • ?autostart=camera：跳过开始界面并请求摄像头模式。
  • ?autostart=nocamera：跳过开始界面并在不使用摄像头的情况下运行。
  • ?trails=0：禁用粒子轨迹。
  • ?dpr=1：将设备像素比强制设为 1，可帮助较慢的 GPU 提升性能。

选项可以组合使用。例如，以下地址会在不使用摄像头的情况下启动，使用 100,000 个粒子，将设备像素比设为 1，并禁用轨迹：

http://localhost:5173/?autostart=nocamera&n=100000&dpr=1&trails=0

高级提示

提升较慢硬件上的性能

粒子数量和设备像素比会直接影响渲染负载。首先使用 README 推荐的低帧率配置：

http://localhost:5173/?n=100000&dpr=1

如有需要，还可以添加 trails=0 来关闭粒子轨迹。

使用确定性的启动链接

如需演示或进行可重复测试，请将 model 与 autostart 模式结合使用。这样每次都无需手动浏览开始界面和模型列表。

了解应用架构

主渲染循环、拾取、缩放、爆炸视图、标签、测验、剖切和演示行为都位于 src/app.js 中。摄像头和 MediaPipe 集成位于 src/hands.js 中，而语音控制、朗读支持和录制功能则实现在 src/features.js 中。

src/gl/ 目录包含 WebGL2 着色器和变换反馈渲染器。手势逻辑、状态机、控制器以及粒子物理的 CPU 等效实现位于 src/logic/ 中。程序化几何工具位于 src/lib/ 下，模型定义则归类在 src/models/ 中。

运行测试套件

WonderSnap 包含使用 Playwright 构建的 36 个端到端测试和单元测试。这些测试使用模拟手部和确定性时钟驱动真实应用。

首次使用时安装 Playwright 的 Chromium 浏览器：

npx playwright install chromium

然后运行测试：

npm test

该套件涵盖完整的手势流程、每个模型、爆炸视图、键盘和鼠标滚轮控制、响应式布局、心跳和呼吸动画、双手缩放、部件选择、捏合交互、测验、语音命令、剖切模式、录制、摄像头回退行为、姿态分类器、状态转换、程序化模型有效性以及 GPU 物理效果。GPU 着色器还会与其 CPU 对应实现进行比较，在每种模式下的误差约为 1e-7。

故障排除

  • 摄像头无法启动：请通过 http://localhost:5173 打开应用，而不要直接打开 index.html，并在提示时授予摄像头权限。
  • 手部追踪无法加载：运行 npm install。追踪运行时从 node_modules 提供。
  • 帧率较低：尝试访问 http://localhost:5173/?n=100000&dpr=1。
  • 端口 5173 已被占用：运行 npm start -- 8080，然后打开 http://localhost:8080。

结论

WonderSnap 展示了设备端手部追踪、自定义手势分类器、程序化建模和 GPU 粒子物理如何完全在浏览器中打造交互式教育体验。先完成标准本地设置，熟悉打响指、握拳、张开手掌、指向和捏合交互，然后探索 URL 调节、语音控制、测验、剖面、录制以及自动化测试套件。