From 9d4d16e36c2340f06e4e63b53e1f015920276d0d Mon Sep 17 00:00:00 2001 From: Bethvour Date: Sat, 30 Aug 2025 23:09:57 -0500 Subject: [PATCH] Update README.md to enhance project description and usage instructions - Revised project title and description for clarity. - Expanded features section to include detailed gesture controls and multi-hand support. - Updated requirements to specify Python version and included links to libraries. - Improved installation and usage instructions for better user guidance. - Added configuration options and project structure overview. - Clarified limitations and contribution guidelines. --- README.md | 96 ++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 66 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 162fb8e..2c14a21 100644 --- a/README.md +++ b/README.md @@ -1,56 +1,92 @@ -# AI Virtual Mouse Project +# AI Virtual Mouse -The AI Virtual Mouse Project is a Python application that enables the control of the mouse cursor using hand movements captured through a webcam. This project uses computer vision techniques to detect hand movements and translate them into mouse actions on the screen. +AI Virtual Mouse is a Python application that enables controlling the mouse cursor with **hand gestures** captured via a webcam. +It leverages **MediaPipe Hands** for landmark detection, **OpenCV** for video processing, and **PyAutoGUI** for system-level mouse control. ## Features -- Hand detection using color segmentation -- Movement of the mouse cursor corresponding to the detected hand's position -- Simple click action based on the size of the detected hand area +- Real-time hand detection and landmark tracking with **MediaPipe** +- Cursor movement mapped to index finger tip position +- Gesture-based controls: + - **Move Cursor** → move index finger + - **Left Click** → pinch index finger & thumb together + - **Right Click** → pinch middle finger & thumb + - **Scroll Up/Down** → vertical hand gestures +- Multi-hand support (detects left vs right hand) +- Configurable gesture mapping for customization ## Requirements -- Python 3.x -- OpenCV (`cv2`) -- NumPy -- PyAutoGUI +- Python **3.10+** +- [OpenCV](https://pypi.org/project/opencv-python/) +- [MediaPipe](https://developers.google.com/mediapipe/) +- [PyAutoGUI](https://pypi.org/project/PyAutoGUI/) +- [NumPy](https://pypi.org/project/numpy/) -## Installation - -To run the AI Virtual Mouse Project, you need to have Python installed on your system. If you haven't installed Python yet, download and install it from the [official Python website](https://www.python.org/downloads/). - -After installing Python, you can install the required libraries using pip. Open your terminal or command prompt and run the following commands: +Install them with: ```bash -pip install opencv-python -pip install numpy -pip install pyautogui +pip install opencv-python mediapipe pyautogui numpy ``` +```` + ## Usage -1. Ensure your webcam is connected and properly set up. -2. Clone the repository or download the `AIVirtualMouseProject.py` file to your local machine. -3. Open a terminal or command prompt and navigate to the directory containing `AIVirtualMouseProject.py`. -4. Run the script by executing the command: +1. Clone the repository: + ```bash - python AIVirtualMouseProject.py + git clone https://github.com/yourusername/ai-virtual-mouse.git + cd ai-virtual-mouse ``` -5. Once the application starts, it will use your webcam to detect your hand's movement. Move your hand to control the mouse cursor. -6. To perform a click action, make your hand's detected area small (e.g., by making a fist). -7. To exit the application, press the 'q' key while the webcam window is active. + +2. Run the application: + + ```bash + python main.py + ``` + +3. Place your hand in view of the webcam: + + - Move your index finger → cursor moves + - Pinch index & thumb → left click + - Pinch middle & thumb → right click + - Move hand up/down with open palm → scroll + +4. Press **`q`** to quit. ## Configuration -The hand detection sensitivity can be adjusted by changing the `hsv_lower` and `hsv_upper` values in the `ColorHandDetector` class initialization within the `main()` function. +- Sensitivity, smoothing, and gesture mappings can be adjusted in `config.py`. +- Debug overlays (landmarks, FPS, gesture labels) can be enabled by setting `draw_landmarks=True` when initializing `HandTracker`. + +## Project Structure + +``` +ai_virtual_mouse/ +├── main.py # Entry point +├── hand_tracker.py # MediaPipe hand detection wrapper +├── gesture_classifier.py # Maps landmarks → gestures +├── mouse_controller.py # Handles PyAutoGUI mouse actions +├── utils/ # Helper functions +└── tests/ # Unit & E2E tests +``` ## Limitations -- The application currently does not support right-click or scroll actions. -- Performance may vary based on lighting conditions and webcam quality. +- Requires consistent lighting and clear webcam view of hands. +- Latency may increase on low-end hardware. +- Currently optimized for single-user interaction. ## Contributions -Contributions to the AI Virtual Mouse Project are welcome. Please feel free to fork the repository, make your changes, and submit a pull request. +Contributions are welcome! + +- Fork the repo +- Create a feature branch +- Submit a pull request + +--- ---- \ No newline at end of file +Built using **Python, MediaPipe, OpenCV, and PyAutoGUI**. +````