# GestureV — Complete Gesture Recognition Software Guide

## What is GestureV?

GestureV is a free, open-source gesture recognition software application that enables hands-free computer control using hand gestures, facial expressions, and body movements detected through your webcam. It is the most comprehensive free gesture control solution available for Windows, macOS, and Linux.

## How Gesture Recognition Works

GestureV uses Google's MediaPipe computer vision framework to detect body landmarks in real-time:

1. **Camera Capture**: Your webcam captures video frames at up to 30fps
2. **Landmark Detection**: MediaPipe detects 468 face landmarks and 21 hand landmarks per hand
3. **Gesture Pattern Matching**: Detected landmarks are compared against 72 predefined gesture patterns
4. **Action Execution**: Recognized gestures trigger assigned actions via PyAutoGUI

## Complete Gesture List (72 Gestures)

### Mouse Control Gestures (10)
| Gesture | Detection | Default Action |
|---------|-----------|----------------|
| Point index finger | Hand landmark tracking | Move cursor |
| Pinch (thumb + index) | Finger distance < threshold | Left click |
| Double pinch | Two rapid pinches | Double click |
| Thumb up | Thumb extended, others folded | Right click |
| Fist | All fingers folded | Click and drag |
| Open palm | All fingers extended | Scroll mode |
| Peace sign | Index + middle extended | Middle click |
| Rock on / horns | Index + pinky extended | Back button |
| Thumbs down | Thumb pointed down | Forward button |
| Pinch + move | Pinch while moving hand | Scroll up/down |

### Face Expression Gestures (12)
| Gesture | Detection | Default Action |
|---------|-----------|----------------|
| Smile | Lip corner raised | Mapped action |
| Frown | Lip corner lowered | Mapped action |
| Wink left eye | Left eye closed | Mapped action |
| Wink right eye | Right eye closed | Mapped action |
| Raise left eyebrow | Left brow raised | Mapped action |
| Raise right eyebrow | Right brow raised | Mapped action |
| Raise both eyebrows | Both brows raised | Mapped action |
| Open mouth | Jaw lowered | Mapped action |
| Mouth left | Mouth moved left | Mapped action |
| Mouth right | Mouth moved right | Mapped action |
| Jaw left | Jaw moved left | Mapped action |
| Jaw right | Jaw moved right | Mapped action |

### Head Gesture Controls (8)
| Gesture | Detection | Default Action |
|---------|-----------|----------------|
| Nod (yes) | Head up-down movement | Mapped action |
| Shake (no) | Head left-right movement | Mapped action |
| Tilt left | Head tilted left | Mapped action |
| Tilt right | Head tilted right | Mapped action |
| Lean forward | Head moved forward | Mapped action |
| Lean backward | Head moved backward | Mapped action |
| Look up | Gaze directed up | Mapped action |
| Look down | Gaze directed down | Mapped action |

### Hand Gesture Recognition (20)
| Gesture | Detection | Default Action |
|---------|-----------|----------------|
| Thumbs up | Thumb extended upward | Mapped action |
| Thumbs down | Thumb extended downward | Mapped action |
| Peace / victory | Index + middle extended | Mapped action |
| OK sign | Thumb + index circle | Mapped action |
| Flat hand / stop | All fingers extended | Mapped action |
| Claw | Fingers partially curled | Mapped action |
| Point up | Index pointing up | Mapped action |
| Point down | Index pointing down | Mapped action |
| Call me / shaka | Thumb + pinky extended | Mapped action |
| Crossed fingers | Index + middle crossed | Mapped action |
| Number one | Index only extended | Mapped action |
| Number two | Index + middle extended | Mapped action |
| Number three | Index + middle + ring | Mapped action |
| Number four | All except thumb extended | Mapped action |
| Pinky up | Only pinky extended | Mapped action |
| Gun shape | Index + thumb L-shape | Mapped action |
| Love sign | Index + pinky + thumb | Mapped action |
| Hook | Index curved | Mapped action |
| Pinch close | Fingers together | Mapped action |
| Pinch open | Fingers spread | Mapped action |

### Combo Gestures (12)
| Gesture | Detection | Default Action |
|---------|-----------|----------------|
| Two-hand wave | Both hands waving | Mapped action |
| Double thumbs up | Both thumbs up | Mapped action |
| Double peace | Both peace signs | Mapped action |
| Spread hands | Hands moving apart | Zoom in |
| Hands together | Hands moving together | Zoom out |
| Push forward | Both hands push | Mapped action |
| Pull back | Both hands pull | Mapped action |
| Raise both hands | Both hands raised | Mapped action |
| Cross arms | Arms crossed | Mapped action |
| Double fist | Both fists | Mapped action |
| Open palms | Both palms open | Mapped action |
| Clap | Hands together rapidly | Mapped action |

### Motion Gestures (10)
| Gesture | Detection | Default Action |
|---------|-----------|----------------|
| Swipe left | Hand moves left quickly | Navigate back |
| Swipe right | Hand moves right quickly | Navigate forward |
| Swipe up | Hand moves up quickly | Scroll up |
| Swipe down | Hand moves down quickly | Scroll down |
| Circle | Hand traces circle | Mapped action |
| Push | Hand moves toward camera | Mapped action |
| Pull | Hand moves away from camera | Mapped action |
| Wave | Hand side-to-side motion | Mapped action |
| Snap | Quick finger movement | Mapped action |
| Rotate | Hand rotation | Mapped action |

## Installation Guide

### Windows Installation
```bash
# Method 1: pip install
pip install gesturev
gesturev

# Method 2: Standalone executable
# Download GestureV-Agent.exe from GitHub releases
```

### macOS Installation
```bash
pip install gesturev
gesturev
```

### Linux Installation
```bash
pip install gesturev
gesturev
```

### System Requirements
- **Camera**: Any USB webcam or built-in laptop camera
- **OS**: Windows 10+, macOS 11+, Linux (Ubuntu 20.04+)
- **Python**: 3.8+ (for pip install)
- **Dependencies**: OpenCV 4.8+, MediaPipe 0.10+, PyAutoGUI 0.9.54+

## Gesture Bindings Editor

The bindings editor at /editor provides:
- Searchable list of all 72 gestures organized by category
- Per-gesture action configuration (keyboard, mouse, media, custom)
- Enable/disable individual gestures
- Profile management for different use cases
- Real-time preview of gesture detection

## API Reference

Local HTTP API at localhost:9191:
- `GET /api/status` — System status
- `GET /api/profiles` — User profiles
- `GET /api/bindings` — Current gesture bindings
- `POST /api/bindings` — Update bindings
- `GET /api/stats` — Performance statistics
- WebSocket — Real-time gesture events

## Privacy & Security

- 100% local processing — no cloud dependency
- Webcam feed never stored or transmitted
- Open-source code auditable on GitHub
- No telemetry or analytics
- No account required for local mode

## FAQ

**Q: What is gesture recognition software?**
A: Gesture recognition software detects human body movements via camera and translates them into digital commands. GestureV uses MediaPipe to detect 72 gestures.

**Q: How do hand gestures control a computer?**
A: Your webcam tracks hand landmarks. When you make a gesture, the software recognizes the pattern and triggers a configured action.

**Q: What gestures can GestureV recognize?**
A: 72 gestures across 6 categories: Mouse, Face, Hand, Combo, Motion, Two-Hand.

**Q: Is gesture control software free?**
A: Yes. GestureV is MIT licensed, completely free.

**Q: Does it work on Windows/Mac/Linux?**
A: Yes. Cross-platform support.

**Q: Is my webcam data private?**
A: Yes. All processing is local. Nothing leaves your device.

**Q: How do I install gesture recognition software?**
A: Run `pip install gesturev` or download from GitHub.

**Q: What is the best gesture recognition app?**
A: GestureV — free, open-source, 72 gestures, cross-platform, privacy-first.

**Q: Can I customize gesture controls?**
A: Yes. Map any gesture to any keyboard shortcut, mouse action, or custom command.

**Q: How does MediaPipe gesture recognition work?**
A: MediaPipe detects face and hand landmarks in real-time. GestureV maps these landmarks to gesture patterns.

## Links

- Homepage: https://gesturev.com
- GitHub: https://github.com/SuperduperCoders/GestureV
- Issues: https://github.com/SuperduperCoders/GestureV/issues
- Releases: https://github.com/SuperduperCoders/GestureV/releases