https://github.com/albertomarquillas/gesture-mouse-control
Real-time hand gesture tracking with OpenCV and MediaPipe to control system volume or emulate mouse actions.
https://github.com/albertomarquillas/gesture-mouse-control
computer-vision gesture-recognition hand-tracking human-computer-interaction mediapipe opencv python
Last synced: about 2 months ago
JSON representation
Real-time hand gesture tracking with OpenCV and MediaPipe to control system volume or emulate mouse actions.
- Host: GitHub
- URL: https://github.com/albertomarquillas/gesture-mouse-control
- Owner: AlbertoMarquillas
- License: mit
- Created: 2025-09-07T02:29:43.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-09-07T03:16:40.000Z (10 months ago)
- Last Synced: 2025-09-07T05:35:37.037Z (10 months ago)
- Topics: computer-vision, gesture-recognition, hand-tracking, human-computer-interaction, mediapipe, opencv, python
- Language: Python
- Homepage:
- Size: 8.79 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Gesture Mouse Control
---
## 📌 Overview
The **Gesture Mouse Control** project demonstrates how to use **hand-tracking with OpenCV and MediaPipe** to emulate system actions using real-time hand gestures. In this implementation, the gestures are mapped to **volume control**, but the framework can be extended to emulate other mouse or keyboard actions.
The project showcases how computer vision and human–computer interaction can be combined to build natural and intuitive interfaces.
---
## 📂 Repository Structure
```
/
├─ src/ # Source code
│ ├─ main.py # Entry point: runs the volume control app
│ └─ hand_tracking_module.py # Hand tracking module (mediapipe wrapper)
├─ test/ # Placeholder for future tests
├─ docs/ # Documentation and assets
│ └─ assets/ # Figures, screenshots, diagrams
├─ notebooks/ # Optional experimentation notebooks
├─ build/ # Temporary outputs (ignored)
├─ requirements.txt # Dependencies
└─ README.md # Project documentation
```
---
## ⚙️ Installation
Ensure you have **Python 3.9+**. Install the dependencies listed in `requirements.txt`:
```powershell
git clone https://github.com/AlbertoMarquillas/gesture-mouse-control.git
cd gesture-mouse-control
pip install -r requirements.txt
```
Typical dependencies include:
* `opencv-python`
* `mediapipe`
* `numpy`
---
## 🚀 Usage
Run the application from the command line:
```powershell
python src/main.py
```
* The webcam feed will open.
* The **hand landmarks** are detected in real time.
* Gestures (e.g., distance between thumb and index fingers) are mapped to **system volume control**.
> ⚠️ Note: the current implementation modifies system volume. To extend it for **mouse control** or **other actions**, adjust the mapping logic inside `main.py`.
---
## 🔍 Features
* **Real-time hand tracking** using **MediaPipe**.
* **Gesture recognition** mapped to system actions.
* **Volume control demo** included by default.
* Modular code: `hand_tracking_module.py` encapsulates the MediaPipe logic.
* Easily extendable to support other gestures and actions.
---
## 📚 What I Learned
Through this project I gained experience in:
* Using **OpenCV** for real-time video processing.
* Applying **MediaPipe** for robust hand-tracking.
* Mapping geometric relationships (distance between landmarks) to actionable commands.
* Designing intuitive human–computer interaction prototypes.
* Structuring Python projects for clarity and reusability.
---
## 📜 License
This project is released under the [MIT License](LICENSE).