# Gesture Particles 3D

**Repository Path**: aidenpxx/gesture-particles-3d

## Basic Information

- **Project Name**: Gesture Particles 3D
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-26
- **Last Updated**: 2025-11-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Gesture Particles 3D - 手势驱动的 3D 粒子交互系统

<div align="center">
  <br/>
  <a href="http://Gesture.pxx.net" target="_blank">
    <img src="https://img.shields.io/badge/Live_Demo-在线体验-blue?style=for-the-badge&logo=google-chrome&logoColor=white" alt="Live Demo" />
  </a>
  <br/><br/>
  <p>
    👉 <b><a href="http://Gesture.pxx.net">Gesture.pxx.net</a></b> 👈
  </p>
  <br/>
  <p>
    🖐️ <b>手势识别</b> &nbsp;|&nbsp; ✨ <b>3D 粒子物理</b> &nbsp;|&nbsp; 🚀 <b>完全离线运行</b>
  </p>
</div>

## 📖 项目简介

这是一个基于 React + Three.js + MediaPipe 的 **3D 手势交互实验项目**。它利用你的摄像头捕捉手部动作，并实时驱动一个拥有数千个粒子的物理系统。

与传统的粒子展示不同，本项目强调**物理交互感**与**视觉沉浸感**。粒子不仅会跟随你的手势变换形状，还会受到引力、风场和爆炸冲击波的影响。

**最大的亮点：** 本项目已实现**完全本地化**，AI 模型文件内置，断网亦可流畅运行。

## ✨ 核心特性

- **🤖 实时手势追踪**：集成 Google MediaPipe Hand Landmarker，支持高精度的手掌开合度、位置和捏合检测。
- **🎨 六大粒子形态**：
  - **🪐 土星 (Saturn)**：拥有光环的星系，手势控制宇宙膨胀与公转速度。
  - **🎆 烟花 (Fireworks)**：真实的物理模拟，支持蓄力、发射、重力下坠与多彩拖尾。
  - **❤️ 爱心 (Heart)**：3D 立体爱心，随手势跳动。
  - **🌪️ 螺旋 (Spiral)**、**🌸 花朵 (Flower)**、**🔮 球体 (Sphere)** 等。
- **⚡️ 高性能物理引擎**：
  - 粒子拥有**惯性、阻力与引力**，不再是僵硬的模型旋转。
  - 针对 React 进行了极致优化，手势数据绕过 React 渲染循环，直接驱动 WebGL，实现 **60FPS** 丝滑体验。
- **🖥️ 现代 UI 设计**：
  - 全中文界面。
  - 暗色玻璃拟态风格 (Glassmorphism)。
  - 侧边栏支持折叠，提供沉浸式全屏体验。
- **📦 开箱即用**：所有 AI 模型资源已本地化，无需科学上网，无需配置环境。

## 🚀 快速开始

### 1. 安装依赖

确保你的电脑上安装了 Node.js。

```bash
npm install
```

### 2. 启动项目

```bash
npm run dev
```

打开浏览器访问 `http://localhost:5173`，允许摄像头权限即可开始体验。

## 🎮 操作指南

| 手势动作        | 效果                                                        |
| --------------- | ----------------------------------------------------------- |
| **🖐️ 张开手掌** | **爆发/扩张**：粒子向外飞散，土星光环扩大，烟花发射。       |
| **✊ 握紧拳头** | **聚拢/蓄力**：粒子向中心坍缩，土星变成高能核心，烟花蓄力。 |
| **👋 移动手掌** | **引力牵引**：粒子会被你的手“吸”过去，并产生流体般的扰动。  |
| **🤏 捏合手指** | **缩放**：控制粒子整体的大小（部分模式适用）。              |

## 🛠️ 技术栈

- **框架**: [React 18](https://react.dev/) + [Vite](https://vitejs.dev/) + [TypeScript](https://www.typescriptlang.org/)
- **3D 引擎**: [Three.js](https://threejs.org/) + [@react-three/fiber](https://docs.pmnd.rs/react-three-fiber)
- **AI 视觉**: [MediaPipe Tasks Vision](https://developers.google.com/mediapipe)
- **样式**: [Tailwind CSS](https://tailwindcss.com/)
- **图标**: [Lucide React](https://lucide.dev/)

## 📂 项目结构

```
gesture-particles-3d/
├── public/
│   └── models/          # 本地化的 AI 模型文件 (无需联网)
├── src/
│   ├── components/
│   │   ├── HandTracker.tsx    # 手势识别核心组件
│   │   ├── ParticleSystem.tsx # 粒子物理与渲染逻辑 (核心)
│   │   └── UIOverlay.tsx      # 悬浮 UI 界面
│   ├── utils/
│   │   └── geometry.ts        # 各种形状的粒子生成算法
│   ├── types.ts
│   └── App.tsx
└── package.json
```

## 📝 开发笔记

本项目在原有基础上进行了大量优化：

1.  **解决抖动**：将手势数据流从 State 改为 Ref，避免了 React 组件的高频重渲染。
2.  **视觉升级**：使用 Canvas 动态生成发光粒子纹理，替代了默认的方块粒子。
3.  **物理化**：为“烟花”模式增加了重力与初速度模拟；为“土星”模式增加了开普勒轨道运动。
4.  **模型本地化**：手动下载了 MediaPipe 的 `.task` 和 `.wasm` 文件，解决了国内网络加载慢的问题。

---

Made with ❤️ by Kris