Skip to content

README.md

Latest commit

 

History

History
169 lines (116 loc) · 4.45 KB

README.md

File metadata and controls

169 lines (116 loc) · 4.45 KB

🖐 TouchLess - Gesture-Based Mouse Control

Control your computer mouse with hand gestures through your webcam.

✨ Features

  • 🎯 Intuitive Gesture Control - Point your finger to move the cursor
  • 🖱️ Easy Clicking - Quick pinch gesture to click
  • 📜 Natural Scrolling - Scroll with ring finger and thumb
  • ⚡ Real-time Performance - Smooth, responsive control
  • 🎨 Edge Amplification - Reach screen edges easily

🚀 Quick Start

Prerequisites

  • Python 3.8 or higher
  • Webcam
  • macOS, Linux, or Windows

Installation

  1. Clone the repository

    git clone https://github.com/yourusername/TouchLess.git
cd TouchLess

  2. Create virtual environment (recommended)

    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

  3. Install dependencies

    pip install -r requirements.txt

Run

python main.py

Press q to quit.

🎮 Gestures

  • Long Pinch (0.7s): Hold thumb and middle finger together for 0.7 seconds to toggle between ACTIVE/IDLE mode
  • Point Index Finger: Point your index finger - cursor follows your finger movement
  • Quick Pinch: Briefly touch thumb and middle finger to perform a left click (only in ACTIVE mode)
  • Ring Finger + Thumb: Hold ring finger and thumb, move up/down to scroll

🧠 Features

  • Smooth Movement: ML-powered predictive movement for fluid cursor control
  • Jitter Reduction: Filters out unwanted micro-movements
  • Edge Amplification: Non-linear mapping allows reaching screen edges easily

⚙️ Configuration

All settings are in config.py. Key parameters:

  • ML_ENABLED: Enable ML smoothing for fluid movement
  • EDGE_AMPLIFICATION: Amplification factor for edge movement (default: 2.5)
  • PINCH_THRESHOLD: Sensitivity for pinch detection (default: 0.22)
  • LONG_PINCH_DURATION: Duration for mode toggle (default: 0.7 seconds)

📁 Project Structure

TouchLess/
├── main.py              # Main application entry point
├── config.py            # Configuration settings
├── hand_tracking.py     # MediaPipe hand tracking
├── gestures.py          # Gesture detection and recognition
├── control.py           # Mouse control and cursor movement
├── intent_engine.py     # Smart target detection and attraction
├── ml_predictor.py      # ML-based cursor prediction
├── ml_advanced.py       # Advanced ML features (for future)
├── requirements.txt     # Python dependencies
└── README.md            # This file

🔧 Troubleshooting

Camera not detected

  • Make sure your webcam is connected and not being used by another application
  • Check camera permissions in system settings

Hand not detected

  • Ensure good lighting
  • Keep your hand fully visible in the camera frame
  • Try moving closer to the camera

Cursor not moving smoothly

  • Adjust ML_SMOOTHING_FACTOR in config.py (higher = smoother)
  • Check that ML_ENABLED = True

Clicking not working

  • Make sure you're in ACTIVE mode (green indicator)
  • Try a more deliberate pinch gesture
  • Check PINCH_THRESHOLD in config.py

🎯 Use Cases

  • Presentations: Control your computer from a distance
  • Accessibility: Alternative input method for users with mobility challenges
  • Gaming: Unique input method for games
  • Productivity: Hands-free mouse control while working
  • Demos: Impressive gesture-based interface demonstrations

🛠️ Technology Stack

  • MediaPipe: Hand landmark detection
  • OpenCV: Camera capture and image processing
  • PyAutoGUI: Mouse and keyboard control
  • NumPy: Numerical computations

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

📧 Contact

For questions, issues, or suggestions, please open an issue on GitHub.

🙏 Acknowledgments

  • MediaPipe for hand tracking
  • OpenCV for computer vision
  • Inspired by handTrack and similar gesture control projects