✋ Magic Hand Tracker — AI Particle System

A futuristic real-time hand tracking web application with cinematic particle effects, 10 color modes, and gesture recognition — built with React + Vite + MediaPipe Hands.

---

🚀 Quick Start

Prerequisites

• Node.js 18+
• A modern browser with webcam access (Chrome recommended)

Install & Run

# Clone / unzip the project
cd magic-hand-tracker

# Install dependencies
npm install

# Start dev server
npm run dev

# Open http://localhost:3000

Build for Production

npm run build
npm run preview

---

📁 File Structure

magic-hand-tracker/
├── index.html                          # Entry HTML with Google Fonts
├── vite.config.js                      # Vite + React config
├── tailwind.config.js                  # Tailwind + custom animations
├── postcss.config.js
├── package.json
├── public/
│   └── favicon.svg
└── src/
    ├── main.jsx                        # React root
    ├── App.jsx                         # Main orchestrator component
    ├── styles/
    │   └── index.css                   # Global CSS, glassmorphism, animations
    ├── utils/
    │   ├── colorModes.js               # 10 color mode definitions + helpers
    │   ├── particleEngine.js           # Canvas particle physics engine
    │   └── gestureRecognition.js       # MediaPipe landmark → gesture
    ├── hooks/
    │   └── useHandTracking.js          # MediaPipe camera + hands hook
    └── components/
        ├── Logo.jsx                    # Animated top-left logo
        ├── WebcamView.jsx              # Video + particle canvas overlay
        ├── ControlPanel.jsx            # Right-side floating control panel
        ├── ColorModeSelector.jsx       # 10-mode grid with live previews
        ├── StatusBar.jsx               # Bottom FPS / gesture / particle bar
        └── LoadingScreen.jsx           # Animated boot sequence

---

🎨 Color Modes

#	Mode	Effect
1	✨ Golden Magic	Warm gold sparks + fire aura
2	⚡ Neon Blue	Electric holographic particles
3	🌌 Purple Galaxy	Cosmic purple + pink glow
4	🌿 Emerald Green	Matrix-style energy trails
5	🔥 Fire Red	Fiery orange/red flames
6	❄️ Ice Cyan	Crystal cool shimmer
7	🌈 Rainbow Mode	Continuously shifting RGB
8	🌑 Dark Shadow	Smoky black/purple aura
9	👼 White Angelic	Soft glowing light
10	🎨 Custom	HEX color picker

---

🖐 Gesture Controls

Gesture	Action
Open Palm 🖐	Particle explosion
Pinch 🤏	Energy orb
Fist ✊	Pulse shockwave
Peace ✌️	Cycle color mode
Point ☝️	Light beam
Swipe 👋	Light streaks

---

⚙️ Architecture

Particle Engine (particleEngine.js)

• Canvas 2D with additive blending (lighter) for bloom glow
• Particle types: normal, explosion, orb, shockwave
• Trail rendering with motion blur fade (rgba(0,0,0,0.18) per frame)
• Radial gradient glow per particle
• Light streak renderer with linear gradients

Gesture Recognition (gestureRecognition.js)

• Analyses 21 MediaPipe hand landmarks
• Extension detection via Y-coordinate comparisons
• Pinch via tip-to-tip distance threshold
• Swipe via palm velocity between frames
• 800ms cooldown prevents gesture spam

Color Mode System (colorModes.js)

• Each mode defines: primary, secondary, glow, ambient, particles[], background
• applyModeVars() writes CSS custom properties to :root
• Rainbow mode uses sin() phase-shifted RGB oscillation
• All UI components consume var(--mode-primary) etc.

---

🛠 Tech Stack

Layer	Technology
Framework	React 18 + Vite 5
Styling	Tailwind CSS 3 + custom CSS
Animation	Framer Motion
Hand Tracking	MediaPipe Hands (CDN)
Rendering	Canvas 2D API
Fonts	Orbitron + Rajdhani + Exo 2

---

📱 Performance Tips

• Chrome is recommended for best WebGL/Canvas performance
• Close other camera apps before starting
• On lower-end machines, reduce maxParticles in particleEngine.js (line 50)
• The engine runs at 60 FPS with up to 2000 simultaneous particles

---

🔧 Customisation

Add a new color mode

Edit src/utils/colorModes.js, add an entry to COLOR_MODES:

myMode: {
  id: 'myMode',
  name: 'My Mode',
  emoji: '🚀',
  primary: '#XX0000',
  secondary: '#YY0000',
  glow: 'rgba(R,G,B,0.5)',
  ambient: 'rgba(R,G,B,0.08)',
  particles: ['#XX0000', '#YY0000'],
  background: '#000',
  trailColor: 'rgba(R,G,B,',
}

Adjust particle physics

In particleEngine.js, Particle constructor — modify speed, gravity, decay, maxTrail.

---

📄 License

MIT — free for personal and commercial use.