christmas-tree

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 9 Open GitHub ↗

Hand-tracking 3D particle Christmas tree in the browser.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🎄 3D Interactive Particle Christmas Tree

> 基于 [echoezy9527/christmas-tree-generated-by-gemini-3](https://github.com/echoezy9527/christmas-tree-generated-by-gemini-3) 项目进行改造，新增和优化相关功能

本项目是一个基于 **Three.js** 和 **MediaPipe** 构建的沉浸式 Web 3D 应用。它融合了电影级的视觉效果与前沿的计算机视觉技术，允许用户通过简单的手势，在“璀璨圣诞树”与“漫天星河”之间自由切换，并与悬浮的照片墙进行交互。

代码经过深度优化，**完美适配移动端与桌面端**，并提供了一套完整的可视化工具栏。

---

## ✨ 核心亮点 (Key Features)

* **🎨 电影级视觉 (Cinematic Visuals)**：
    * 采用 **哑光绿**、**香槟金** 与 **圣诞红** 的经典配色。
    * 集成 Unreal Bloom 辉光效果与物理材质（PBR），营造唯美、深邃的节日氛围。

* **🛠️ 实用工具栏 (Smart Toolbar)**：
    * **📷 智能截屏**：一键保存当前 3D 画面为高清图片（自动隐藏 UI，仅保留纯净画面）。
    * **◎ 沉浸模式**：支持一键隐藏手势追踪光圈，享受无干扰的纯净视觉体验。
    * **❓ 交互指引**：内置磨砂玻璃风格的帮助卡片，随时查看手势说明。

* **🎯 精准交互系统 (Precise Interaction)**：
    * **射线拾取**：系统能精确识别手指指向的特定照片进行放大，拒绝随机。
    * **智能防抖**：内置“确认帧”算法，有效过滤手部微颤和误触，操作稳如泰山。

* **📱 全端完美适配 (Mobile Optimized)**：
    * **自动前置镜头**：手机端自动调用前置摄像头。
    * **性能自适应**：针对移动设备优化了检测流分辨率，确保低发热、高帧率（60fps）。
    * **iOS 兼容**：完美解决 iOS Safari 的自动播放限制与权限策略。

---

## 🎮 交互模式 (Modes)

系统根据手势自动在以下三种状态间切换：

1.  **🌲 合拢态 (Tree Mode)**
    * **触发**：握拳 (Fist)
    * **描述**：所有粒子与照片汇聚，旋转组成一棵闪耀的 3D 圣诞树。

2.  **✨ 散开态 (Scatter Mode)**
    * **触发**：张开五指 (Open Palm)
    * **描述**：粒子炸开，化作无重力的漫天星河。照片在空中漂浮，支持通过手掌移动来旋转 360° 视角。

3.  **🖼️ 聚焦态 (Focus Mode)**
    * **触发**：指尖捏合 (Pinch)
    * **描述**：精准抓取选中的照片并放大至屏幕中央，背景保持虚化。

---

## ✋ 操作指南 (Controls)

界面右上角提供悬浮工具栏，同时支持手势控制。

### 🔧 顶部工具栏 (Toolbar)
| 图标 | 功能 | 说明 |
| :---: | :--- | :--- |
| **?** | **帮助** | 打开/关闭手势说明卡片。 |
| **◎** | **光圈开关** | 开启/关闭跟随手指的白色光圈（录屏时推荐关闭）。 |
| **📷** | **截屏** | 下载当前 3D 场景的高清截图（.png）。 |

### 🖐️ 手势控制 (Gestures)
| 手势 | 动作 | 功能 |
| :---: | :--- | :--- |
| ✊ | **握拳** | **召唤**：重组圣诞树。 |
| 🖐️ | **张开手** | **散开**：进入星空模式。 |
| 👌 | **捏合** | **抓取**：放大光标指向的照片（光标变金）。 |
| 👋 | **移动手** | **视角**：在散开模式下，控制场景旋转。 |

---

## 🛠️ 安装与部署 (Installation)

### 方式一：在线体验 (推荐)
**手机端必须使用此方式（需要 HTTPS）。**

1.  Fork 本仓库到您的 GitHub。
2.  在 **Vercel** (或 GitHub Pages) 中导入该项目并部署。
3.  打开生成的网址（如 `https://your-tree.vercel.app`）。
    * *注：您可以将仓库设为 Private，保护您的照片隐私，Vercel 依然可以正常部署。*

### 方式二：本地开发 (Localhost)

如果您想替换默认照片或音乐：

**1. 准备文件结构**
```text
Project/
├── index.html         (主程序)
├── ChristmasSong.mp3  (背景音乐)
└── photos/            (照片文件夹，文件名推荐小写)
    ├── 1.jpg
    ├── 2.jpg
    └── ...
````

**2. 修改配置**
打开 `index.html`，找到 `DEFAULT_PHOTO_PATHS`，填入您的照片路径：

```javascript
const DEFAULT_PHOTO_PATHS = [
  "photos/1.jpg",
  "photos/my-cat.jpg",
  // ...
];
```

**3. 启动本地服务器**
由于浏览器 CORS 安全策略，**不能**直接双击 HTML 打开。

```bash
# Python 3
python -m http.server 8000
# 然后访问 http://localhost:8000
```

-----

## ⚠️ 常见问题 (FAQ)

**Q: 手机上打不开摄像头？**
A: 请检查网址是否以 **`https://`** 开头。浏览器禁止在非安全环境（http）下调用摄像头。

**Q: 背景音乐不自动播放？**
A: 现代浏览器禁止自动播放音频。请**点击屏幕任意位置**即可开始播放。

**Q: 我上传的照片会被公开吗？**
A:

1.  使用界面上的 "Add Memories" 按钮上传的照片仅保存在浏览器内存中，**绝对安全**。
2.  如果您将照片放入 `photos/` 文件夹并推送到 GitHub，建议将仓库设为 **Private (私有)**。

-----

## 📝 技术栈

* **Three.js**: WebGL 3D 渲染
  * **MediaPipe**: Google 高性能手势识别
  * **Post-processing**: 辉光与电影感滤镜

christmas-tree

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README