HandHalo - AI Gesture Control System

English | 简体中文

HandHalo is an AI-powered gesture recognition system that allows you to control your computer through hand gestures captured by your webcam.

✨ Features

• 🖐 Hand Tracking: Real-time 21-point hand landmark detection using MediaPipe
• 🦴 Skeleton Visualization: Display hand bones and joints in real-time
• 🖱️ Mouse Control: Move cursor, click, and drag using hand gestures
• 📸 System Actions: Take screenshots, control volume, media playback
• ⚙️ Flexible Configuration: JSON-based gesture-action bindings
• 🎯 Action Sequences: Complex actions like "grab" (open palm → fist)
• 🖥️ System Tray: Runs in background without interfering with work

🎬 Demo

video.mp4

Screenshots

Camera View	Skeleton Only

📋 Requirements

• Python 3.8+
• Windows 10/11 (other systems may have limited functionality)
• Webcam

🚀 Installation

# Clone the repository
git clone https://github.com/yourusername/HandHalo.git
cd HandHalo

# Install dependencies
pip install -r requirements.txt

🎮 Usage

Quick Start

# Start with preview window
python main.py --preview

# Start minimized to system tray
python main.py

# List available cameras
python main.py --list-cameras

# Use specific camera
python main.py --camera 1

Supported Gestures

Gesture	Description	Default Action
☝️ Pointing	Index finger extended	Mouse move
👊 Fist	All fingers closed	Part of "grab" action
✋ Open Palm	All fingers extended	Part of "grab" action
👌 Pinch	Thumb and index close	Mouse click

Action Sequences

Action	Sequence	Binding
Grab	Open palm → Fist	Screenshot
Release	Fist → Open palm	-
Click	Quick pinch	Mouse click

⚙️ Configuration

Edit configs/default.json to customize gestures and actions:

{
  "bindings": [
    {
      "name": "Screenshot",
      "binding_type": "action",
      "action_type_name": "grab",
      "action_target_type": "system",
      "action": "screenshot"
    }
  ]
}

🖼️ UI Controls

• Show Camera: Toggle camera feed display
• Mirror: Mirror the camera image
• Show Panel: Toggle control panel
• Always on Top: Keep window on top

📁 Project Structure

HandHalo/
├── src/
│   ├── core/          # Hand detection & gesture recognition
│   ├── actions/       # Mouse, keyboard, system actions
│   ├── bindings/      # Gesture-action binding engine
│   ├── ui/            # GUI (PyQt6)
│   └── utils/         # Utilities
├── configs/           # Configuration files
├── docs/              # Documentation & demo videos
├── main.py            # Entry point
└── requirements.txt

🤝 Contributing

Pull requests are welcome! For major changes, please open an issue first.

📝 License

MIT

🙏 Acknowledgments

• MediaPipe - Google's hand tracking solution
• PyAutoGUI - Cross-platform GUI automation
• PyQt6 - GUI framework