Hand-Controlled Mouse (MediaPipe)

This project uses your computer's webcam with OpenCV and the MediaPipe library to enable hands-free mouse control, including cursor movement, clicking/dragging, and scrolling.

1. Prerequisites

You must have Python installed. MediaPipe's official support range for Python is 3.9 - 3.12.

IMPORTANT WINDOWS PREREQUISITE (Fixes DLL Load Failed Error)

If you are on Windows, you MUST install the Microsoft Visual C++ Redistributable for Visual Studio 2015-2022. This is required by the underlying C++ binaries used by MediaPipe and other libraries.

1. Download: Get the latest official Redistributable installer: Microsoft Visual C++ Redistributable

2. Install: Download and run the x64 version for 64-bit Windows.

3. Run: Execute the installer.

2. Setup and Installation

2.1: Create a Virtual Environment (Recommended)

Using a virtual environment prevents conflicts with other Python projects.

python -m venv venv_hand_mouse
# Activate on Windows:
.\venv_hand_mouse\Scripts\activate
# Activate on macOS/Linux:
source venv_hand_mouse/bin/activate

2.2: Install Required Libraries

Install the following packages using pip. Ensure your virtual environment is activated first.

pip install opencv-python mediapipe numpy pyautogui

Package	Purpose
opencv-python	Handles webcam input and video display (cv2).
mediapipe	Provides the highly accurate hand-tracking model.
numpy	Essential for fast array manipulations and calculations.
pyautogui	Controls the operating system's mouse and keyboard.

3. Running the Application

3.1: Save the Code

Save the main Python application code as a file named mp_handpos_mouse.py.

3.2: Execute

Run the script from your terminal:

python mp_handpos_mouse.py

4. Controls and Gestures

The script will open a window displaying your webcam feed, along with real-time feedback on the detection status.

Gesture	Action
Move Hand	Controls the cursor position on the screen.
Index-to-Thumb Pinch	Left-Click / Drag (while the pinch is held).
Middle-to-Thumb Pinch	Activates Scroll Mode. Move your pinched hand up or down to scroll the page.
Two-Hand Index-to-Thumb Pinch	Executes a Double-Click.
Press 'q' key	Stops the script and closes the video window.

Important Note for Linux Users (Optional)

If pyautogui fails to control the mouse on your Linux distribution, you may need additional dependencies:

sudo apt-get install python3-tk python3-dev