handible

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! 🤏');
}

🎥 Webcam Only No special hardware

⚡ 60fps Performance Real-time tracking

🎯 21 Hand Points Precise detection

🔧 Easy Integration Drop-in solution

🚀 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

🎮 3D Games Natural hand controls	🎨 Creative Tools Gesture-based design	📊 Data Visualization Interactive exploration	🏫 Education Immersive learning
🛍️ E-commerce Product interaction	🏥 Healthcare Touchless interfaces	🎭 Entertainment Interactive experiences	🔬 Research Gesture analysis

🛠️ 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! ⭐