66 lines
3.4 KiB
Markdown
66 lines
3.4 KiB
Markdown
# 交互式 3D 粒子系统 (Interactive 3D Particle System)
|
||
|
||
这是一个基于 Web 的交互式 3D 粒子特效展示项目。它利用 Three.js 进行 3D 渲染，并通过 MediaPipe Hands 实现手势交互，允许用户通过手势控制粒子的运动。
|
||
|
||
## ✨ 特性 (Features)
|
||
|
||
* **多种粒子模型**：内置多种粒子形态，包括：
|
||
* ❤️ **爱心 (Heart)**：浪漫的 3D 爱心形状。
|
||
* 🌸 **花朵 (Flower)**：基于玫瑰线的 3D 花朵。
|
||
* 🪐 **土星 (Saturn)**：带有光环的行星模型。
|
||
* 🎆 **烟花 (Fireworks)**：绚丽的球形爆炸效果。
|
||
* ⛰️ **山水 (Mountain)**：动态波浪地形。
|
||
* 🔢 **数字倒数 (Countdown)**：粒子组成的倒计时动画。
|
||
* **手势交互 (Hand Interaction)**：
|
||
* 集成 MediaPipe Hands，通过摄像头实时捕捉手部动作。
|
||
* 根据手掌的开合程度 (Openness) 动态影响粒子的散布和运动。
|
||
* **实时控制面板 (Control Panel)**：
|
||
* 使用 `lil-gui` 提供浮动控制面板。
|
||
* 支持切换模型、调整粒子颜色、大小、混合模式及手势影响强度。
|
||
* **响应式设计**：支持全屏显示，并自适应窗口大小。
|
||
|
||
## 🛠️ 技术栈 (Tech Stack)
|
||
|
||
* **[Three.js](https://threejs.org/)**: 核心 3D 渲染引擎。
|
||
* **[MediaPipe Hands](https://google.github.io/mediapipe/solutions/hands)**: 谷歌开源的机器学习手部追踪库。
|
||
* **[Tween.js](https://github.com/tweenjs/tween.js/)**: 平滑动画过渡库。
|
||
* **[lil-gui](https://lil-gui.georgealways.com/)**: 轻量级 Web 界面控制器。
|
||
|
||
## 🚀 快速开始 (Getting Started)
|
||
|
||
### 前置要求
|
||
* 现代浏览器（推荐 Chrome, Edge, Firefox）。
|
||
* 摄像头（用于手势交互功能）。
|
||
|
||
### 运行项目
|
||
1. **克隆或下载**本项目到本地。
|
||
2. **启动服务**：由于浏览器的安全策略（CORS）以及摄像头权限限制，直接双击 `index.html` 可能无法正常加载模型或调用摄像头。建议使用本地服务器运行：
|
||
* **VS Code Live Server**: 在 VS Code 中安装 "Live Server" 插件，右键 `index.html` 选择 "Open with Live Server"。
|
||
* **Python**: 在项目根目录下运行 `python -m http.server`，然后访问 `http://localhost:8000`。
|
||
* **Node.js**: 使用 `http-server` 或 `vite` 等工具。
|
||
|
||
3. **授权摄像头**：浏览器弹出摄像头请求时，请点击“允许”。
|
||
|
||
## 📂 文件结构 (File Structure)
|
||
|
||
```
|
||
├── index.html # 项目入口文件，包含 HTML 结构和库引用
|
||
├── main.js # 核心逻辑：Three.js 场景、粒子系统、手势识别
|
||
├── style.css # 全局样式：全屏布局、UI 样式
|
||
├── create_repo.py # (工具脚本) 用于自动创建远程仓库
|
||
└── README.md # 项目说明文档
|
||
```
|
||
|
||
## 🎮 操作指南 (Controls)
|
||
|
||
* **模型选择**：在右上角面板的 "模型选择" 下拉框中切换不同效果。
|
||
* **参数调整**：
|
||
* **粒子颜色**：自定义粒子基础颜色。
|
||
* **粒子大小**：调整单个粒子的大小。
|
||
* **手势强度**：控制手势对粒子干扰的范围和力度。
|
||
* **全屏模式**：点击左上角的 "全屏显示" 按钮进入沉浸式体验。
|
||
|
||
## 📝 注意事项
|
||
* 请确保在光线充足的环境下使用摄像头，以获得最佳的手势识别效果。
|
||
* 初次加载 MediaPipe 模型可能需要几秒钟，请耐心等待。
|