H a n d i b l e

Revolutionary hand tracking and gesture control for the web

Transform any webcam into a powerful 3D controller

✨ 60fps Real-time • 🌐 Web-based • 🚀 Zero Setup

🎬 Demo

npm install handible

📖 Documentation • ⚡ Try Demo • 🚀 Get Started

🌟 Why Handible?

Handible makes hand tracking accessible to every developer. No expensive hardware, no complex setup—just your webcam and imagination. Super easy to use.

import { startGestureControl, isPinching2D } from 'handible';

// 🚀 Start tracking
await startGestureControl(videoElement, scene);

// 🎯 Detect gestures  
if (isPinching2D(0)) {
  console.log('Hand 0 is pinching! 🤏');
}

🚀 Features

🎮 Core Capabilities

• 🤏 Pinch Detection - Precise finger-to-thumb interactions
• 👋 Palm Recognition - Detect palm orientation and facing direction
• 📍 3D Hand Tracking - Real-time 21-point hand landmarks
• 🎯 Multi-Hand Support - Track up to 2 hands simultaneously
• 🎨 Surface Interaction - Virtual buttons, sliders, and UI panels

🛠️ Developer Experience

• 📦 Zero Config - Works out of the box with Three.js
• 🔧 Modular API - Use only what you need
• 🎨 Customizable - Extensive styling and behavior options
• ⚡ Performance Optimized - GPU-accelerated tracking

📦 Installation

# npm
npm install handible

# yarn  
yarn add handible

# pnpm
pnpm add handible

⚡ Quick Start

1. Basic Setup

import { startGestureControl, setSceneObjects } from 'handible';

// Initialize hand tracking
const videoElement = document.querySelector('#video');
const scene = new THREE.Scene();

await startGestureControl(videoElement, scene);
setSceneObjects(scene, camera, renderer);

2. Detect Gestures

import { isPinching2D, getHandPosition } from 'handible';

// Check for pinch gesture
if (isPinching2D(0)) {
  const position = getHandPosition(0);
  console.log('Pinching at:', position);
}

3. Surface Interactions

import { SurfaceInteractionSystem } from 'handible';

// Create interactive surface
const surface = new THREE.Mesh(geometry, material);
SurfaceInteractionSystem.registerSurface(surface, {
  width: 2,
  height: 1.5,
  cursorScaleFactor: 3.0
});

� Documentation

| Section | Description | |---------|-------------| | 🚀 Getting Started | Installation and basic setup | | 💡 Core Concepts | Understanding gestures and tracking | | 📚 API Reference | Complete function documentation | | 🎯 Advanced Features | Surface systems and custom interactions |

🎯 Use Cases

🛠️ Built With

• Three.js - 3D graphics and rendering
• MediaPipe - Real-time hand tracking
• WebGL - GPU-accelerated performance

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

🐛 Report Bug • 💡 Request Feature • 💬 Discussions

Development Setup

git clone https://github.com/gust10/Handible.git
cd Handible
npm install
npm run dev

📊 Performance

| Metric | Value | Description | |--------|-------|-------------| | Frame Rate | 60fps | Real-time tracking performance | | Latency | ~16ms | Input to response time | | Hand Points | 21 | Landmark precision per hand | | Max Hands | 2 | Simultaneous tracking |

📄 License

MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• MediaPipe Team - For the incredible hand tracking technology
• Three.js Community - For the powerful 3D graphics framework
• Contributors - Everyone who helped make this project better

Made with ❤️ by Hyunsung Shin

Transform your ideas into gestures

⭐ Star this repo if you find it useful! ⭐