# 交互式 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 模型可能需要几秒钟，请耐心等待。