From 40f085e9287e99ed0dc98efc7ad49c2fb324a551 Mon Sep 17 00:00:00 2001
From: admin <admin@aitosuv.com>
Date: Tue, 9 Dec 2025 10:20:28 +0800
Subject: [PATCH] Initial commit

---
 .gitignore |  8 +++++++
 README.md  | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 73 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 README.md

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..4e1403e
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+.trae/
+.vscode/
+.idea/
+*.log
+create_repo.py
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..fb95ce7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,65 @@
+# 交互式 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 模型可能需要几秒钟，请耐心等待。