HandScroll ✋

Hands-free scrolling and mouse control using MediaPipe Hands + OpenCV + PyAutoGUI.

Control your desktop without touching a mouse — raise a finger to scroll, pinch to click, and drag with your hand in front of your webcam.

Features

• Scroll mode — raise any non-thumb finger and move your hand up or down to scroll. The anchor-based ratchet means returning toward the anchor never scrolls, so you can reposition without accidental input.
• Mouse mode — raise your index finger to move the cursor across the full screen.
• Pinch gestures — thumb + index pinch for left click (hold to drag), thumb + middle pinch for right click.
• Adaptive tracking — gestures and pinch thresholds are normalized to hand size, so they work reliably whether your hand is close to or far from the camera.
• Persistent settings — your hand preference, scroll speed, and mouse sensitivity are saved between runs.
• Camera resilience — automatically reconnects if the camera feed is lost.

Requirements

• Python 3.9+
• A webcam

Installation

# Create and activate a virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Usage

python hand_scroll.py

A window will open showing your webcam feed. Show your hand and start gesturing.

Controls

Key	Action
Q	Quit
SPACE	Pause / Resume
M	Toggle SCROLL / MOUSE mode
H	Switch between Left / Right hand
+ / -	Increase / decrease scroll speed or mouse sensitivity
R	Reset current gesture state

Scroll mode

1. Raise any non-thumb finger.
2. Hold your hand still briefly to establish the anchor.
3. Move up or down away from the anchor to scroll.
4. Return toward the anchor to reposition — it won't scroll.

Mouse mode

Gesture	Action
Raise index finger	Move the cursor
Thumb + index pinch	Left click (hold to drag)
Thumb + middle pinch	Right click

Safety: PyAutoGUI fail-safe is enabled. Moving your physical mouse into a screen corner instantly stops all mouse control.

Configuration

Adjust camera index, scroll speed, sensitivity, and more in the SETTINGS section at the top of hand_scroll.py.

How it works

• MediaPipe Hands detects and tracks up to two hands with 21 landmarks per hand.
• Finger extension is measured relative to hand size, making pose detection robust to hand distance and rotation.
• Scroll direction uses a smoothed wrist position with an anchor-based ratchet, so scrolling only fires when you move away from the anchor.
• Mouse movement is smoothed with adaptive alpha and mapped from the camera frame to your full screen resolution.

License

MIT