# wasifsohail5/virtual_mouse architecture

> Architecture diagram of the GitHub repository wasifsohail5/virtual_mouse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wasifsohail5/virtual_mouse
- Repository: https://github.com/wasifsohail5/virtual_mouse

## Overview

##### Project Type and Purpose
- This is a **single-process, full-stack algorithmic application** (no frontend UI beyond console/terminal) that captures webcam frames, processes them in real time to recognize gestures, and drives the OS mouse.
- Key libraries: **OpenCV** (capture & preprocessing), **MediaPipe** (landmark detection), custom **gesture logic** (distance checks + smoothing), **PyAutoGUI** (cursor control), **NumPy** (math).

##### Main Architectural Components
a. **Input Subsystem**
- Webcam Capture (OpenCV VideoStream)
b. **Hand Landmark Detection**
- MediaPipe Hands Module
- Landmark Extraction (21 keypoints per hand)
c. **Gesture Recognition & Smoothing**
- Distance Calculations (e.g., index-thumb pinch)
- State Machine for click, double-click, scroll modes
- Adaptive smoothing/filtering via NumPy
d. **Cursor Control & OS Interaction**
- Normalized hand positions to screen coordinates
- Mouse move, click, double-click, scroll via PyAutoGUI
e. **Configuration & Thresholds**
- Sensitivity parameters (click distance thresholds)
- Mode toggles (scroll on/off)

##### Architectural Patterns and Principles
- **Pipeline Pattern**: Sequential processing stages (capture → detect → recognize → control).
- **Separation of Concerns**: Each stage encapsulated in its own function/module.
- **Single Responsibility**: One class or function per major concept (e.g., “HandDetector,” “GestureController,” “CursorManager”).
- **Extensibility Points**: Insert new gesture modules or integrate voice commands by adding new pipeline stages.

##### Essential Elements
- **Component Labels**: e.g., “OpenCV VideoCapture,” “MediaPipe Hands,” “Gesture Engine,” “PyAutoGUI Driver.”
- **Container Boundaries**: Show that everything (except the webcam and OS mouse) lives inside a single Python process.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Virtual Mouse Process"
        direction TB
        Webcam["Webcam"]:::io
        Input["Input Subsystem<br/>(OpenCV VideoCapture & Preprocessing)"]:::processing
        Detection["Hand Landmark Detection<br/>(MediaPipe Hands & Landmark Extraction)"]:::processing
        Recognition["Gesture Recognition & Smoothing<br/>(Distance Calculations, State Machine, Filters)"]:::processing
        Control["Cursor Control & OS Interaction<br/>(PyAutoGUI Driver)"]:::processing
        Config["Configuration & Thresholds<br/>(Sensitivity Parameters & Mode Toggles)"]:::config

        Webcam -->|VideoFrame| Input
        Input -->|PreprocessedFrame| Detection
        Detection -->|LandmarkSet| Recognition
        Recognition -->|ControlCommands| Control

        Input -->|uses| Config
        Detection -->|uses| Config
        Recognition -->|uses| Config
        Control -->|uses| Config
    end

    OSMouse["OS Mouse"]:::io
    Control -->|OSMouseEvents| OSMouse

    subgraph "Project Assets"
        direction TB
        README["Project Documentation"]:::config
        GitIgnore["Git Exclusions/Environment Settings"]:::config
    end

    click Input "https://github.com/wasifsohail5/virtual_mouse/blob/main/Virtual Mouse.py"
    click Detection "https://github.com/wasifsohail5/virtual_mouse/blob/main/Virtual Mouse.py"
    click Recognition "https://github.com/wasifsohail5/virtual_mouse/blob/main/Virtual Mouse.py"
    click Control "https://github.com/wasifsohail5/virtual_mouse/blob/main/Virtual Mouse.py"
    click Config "https://github.com/wasifsohail5/virtual_mouse/blob/main/Virtual Mouse.py"
    click README "https://github.com/wasifsohail5/virtual_mouse/blob/main/README.md"
    click GitIgnore "https://github.com/wasifsohail5/virtual_mouse/blob/main/.gitignore"

    classDef io fill:#ADD8E6,stroke:#000
    classDef processing fill:#98FB98,stroke:#000
    classDef config fill:#D3D3D3,stroke:#000
```
