Neural Hand Particle Simulator

An immersive, high-performance, real-time 3D particle simulator running fully in the browser. Powered by Three.js and MediaPipe Hands, this app translates computer vision hand-tracking gestures into gravitational kinetic force fields acting on thousands of glowing cosmic-stellar particles.

---

🚀 Getting Started

To run this simulator locally, execute the following commands in your terminal:

# 1. Clone or extract the project files and open the folder
cd neural-hand-particle-simulator

# 2. Install dependencies (Vite, React, Three.js, Lucide, Motion, Tailwind)
npm install

# 3. Start the Vite development server
npm run dev

The application will run on http://localhost:3000 (or port configured in your environment).

---

🖐️ Gesture Command Directory

Engage your webcam and hold your hand in front of the camera to dispatch the following spatial force fields:

Gesture	Kinetic Effect	Visual Behavior
☝️ Raised Index	Rotate Swarm	Drifts the rotational torque of the particle field according to finger axis move path.
🖐️ Open Palm	Repel Force	Pushes celestial bodies outward from your palm using an exponential inverse-square dropoff.
✊ Closed Fist	Singularity Attraction	Creates a high-mass gravitational core at your knuckles, dragging all stars inward.
👌 Pinch (Thumb+Index)	Dimensional Pinch	Compresses the entire star count into an extremely compact, bright glowing central orb.
✌️ Peace Sign	Time Warp	Accelerates the flow rates of the particles by scaling up kinetic delta speed vectors.
💥 Fist Flash (Clap)	Supernova Explosion	Transitioning rapidly from Fist to open palm emits a high-impact audio/visual cosmic shockwave.

---

💻 Manual Cursor Fallback (No Webcam Required)

For systems without a webcam, blocked permissions, or when debugging, the simulator defaults to a physical mouse-cursor interactive fallback:

• Hover/Move Cursor: Automatically maps to 🖐️ Palm Repel (pushes particles away from your cursor).
• Hold Left Click & Drag: Automatically maps to ✊ Fist Attractor (gathers particles closer into custom orbits).

---

⚙️ Customization Guide

You can easily adjust parameters directly from the HUD sidebar or modify the underlying source files:

1. Adjusting Particle Density:

   • Slide the Particle Density Slider in the HUD sidebar.
   • Adjusts rendering dynamically from 1,000 up to 20,000 points in real time using a single high-performance Float32Array buffer system (see /src/components/ParticleScene.tsx).

2. Customizing Formations:

   • Math equations are declared in /src/utils/formations.ts.
   • Add new 3D parametric curves (e.g., toruses, Möbius strips, double helixes) by extending the generateFormation switch cases.

3. Modifying Color Palettes:

   • Tweak color hues inside getThemeColors in /src/components/ParticleScene.tsx.
   • Built-in palettes: Neon Cyberpunk, Biotech Neural, Electric Forest, and Solar Plasma.

---

🛠️ Troubleshooting

• Webcam Permission Denied:
  • Check the lock icon in your browser address bar. Select "Allow" for Camera access and click the Retry Connection button on the panel.
• Low FPS Rate:
  • The simulator automatically scales rendering down on mobile and high-density screens. If lagging, decrease the Particle Density slider to e.g., 8,000.
• Blank Screen:
  • Confirm that the MediaPipe scripts in index.html load successfully from jsDelivr's global CDN:
    • @mediapipe/camera_utils
    • @mediapipe/hands