✋ Hand Controlled 3D Particles

简体中文 | English | 한국어 | Français | Deutsch | 日本語 | Русский | Español | Português | Italiano | Tiếng Việt | العربية

🎮 Control 3D particle effects with hand gestures — no hardware needed, just a camera!

---

✨ Features

• 🖐️ Real-time Hand Tracking - Powered by MediaPipe Hands, AI runs directly in browser
• 🌍 Multiple Particle Shapes - Earth, Heart, Saturn, Tree, Fireworks - 5 shapes to switch
• 🎯 Gesture-based Interaction
  • 👊 Fist → Particles contract + switch shape
  • 🖐️ Open hand → Particles spread out
  • ✋ Left hand fist → Previous shape
  • 🤚 Right hand fist → Next shape
• 🎨 Visual Effects - Random color changes, fog effect, auto-rotation
• 📱 Responsive Design - Works on desktop and mobile

🎬 Demo

Open your camera and control 4000 particles switching between different shapes with your hands!

Earth	Heart	Saturn
🌍 Earth	💖 Heart	🪐 Saturn

Tree	Fireworks
🎄 Tree	🎆 Fireworks

🚀 Quick Start

Install Dependencies

git clone https://github.com/wangmiaozero/hand-controlled-particles.git
cd hand-controlled-particles
npm install

Start Development Server

npm run dev

Open http://localhost:5173 in your browser and allow camera access to start!

Build for Production

npm run build

🛠️ Tech Stack

Technology	Description
Vue 3	Progressive JavaScript Framework
Three.js	3D Graphics Library
MediaPipe Hands	Google Hand Tracking AI Model
TypeScript	Type-safe JavaScript
Vite	Next Generation Frontend Tooling

📁 Project Structure

hand-controlled-particles/
├── index.html
├── package.json
├── vite.config.ts
├── tsconfig.json
└── src/
    ├── main.ts                 # Entry file
    ├── App.vue                 # Main component
    ├── style.css               # Global styles
    ├── components/
    │   ├── VideoContainer.vue  # Camera preview component
    │   ├── BottomBar.vue       # Bottom control bar component
    │   └── LoadingOverlay.vue  # Loading animation component
    └── composables/
        ├── useParticleSystem.ts # Three.js particle system
        └── useHandTracking.ts   # MediaPipe hand tracking

🎮 User Guide

Gesture Controls

Gesture	Effect
👊 Fist (Right hand)	Contract particles + switch to next shape
👊 Fist (Left hand)	Contract particles + switch to previous shape
🖐️ Open palm	Spread particles outward
✊ Neutral state	Particles stay at default size

UI Controls

• Click shape buttons at bottom to switch directly
• Drag mouse to rotate view
• Scroll wheel to zoom in/out

🔧 Configuration

Particle Parameters

Adjust in src/composables/useParticleSystem.ts:

const PARTICLE_COUNT = 4000  // Number of particles
const PARTICLE_SIZE = 0.15   // Particle size

Gesture Sensitivity

Adjust thresholds in src/App.vue:

const CLOSE_THRESHOLD = 0.08  // Fist detection threshold
const OPEN_THRESHOLD = 0.16   // Open hand detection threshold

🌐 Browser Support

Browser	Support
Chrome	✅ Recommended
Edge	✅
Firefox	✅
Safari	⚠️ Requires HTTPS

⚠️ Requires WebGL and getUserMedia API support

📄 License

MIT

🤝 Contributing

Issues and PRs are welcome!

1. Fork this repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

⭐ Star History

If you find this project helpful, please give it a ⭐!

---

Made with ❤️ by wangmiaozero