# thaqibrahman/ai-virtual-mouse architecture

> Architecture diagram of the GitHub repository thaqibrahman/ai-virtual-mouse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thaqibrahman/ai-virtual-mouse
- Repository: https://github.com/thaqibrahman/ai-virtual-mouse

## Overview

This is a real-time, webcam-driven virtual mouse. The main loop captures and processes frames, passes hand landmarks into gesture interpretation, and maps recognized gestures to cursor, click, screenshot, and volume actions. README capabilities such as double-click and volume control are represented where documented and visible in the sampled runtime. The implementation is concentrated in main.py; util.py provides geometry helpers, but the shown code does not call them. Relationships reflect the shown code and README, not an assumed pipeline beyond it.

Main entry points: [`AI Virtual Mouse/main.py`](https://github.com/thaqibrahman/ai-virtual-mouse/blob/main/AI%20Virtual%20Mouse/main.py) (Frame loop), [`AI Virtual Mouse/util.py`](https://github.com/thaqibrahman/ai-virtual-mouse/blob/main/AI%20Virtual%20Mouse/util.py) (Geometry helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_vision["Vision and gesture input"]
  node_main_loop["Frame loop<br/>[main.py]"]
  node_hand_tracking["Hand tracking<br/>[main.py]"]
  node_gesture_mapping["Gesture mapping<br/>[main.py]"]
end

subgraph group_actions["System actions"]
  node_cursor["Cursor movement<br/>[main.py]"]
  node_mouse_events["Click actions<br/>[main.py]"]
  node_screenshot["Screenshot capture<br/>[main.py]"]
  node_volume["Volume control<br/>[main.py]"]
end

subgraph group_helpers["Geometry helpers"]
  node_geometry_helpers["Geometry helpers<br/>[util.py]"]
end

node_user(("User hand gestures"))
node_webcam["Webcam"]
node_os_mouse["Desktop mouse"]
node_volume_service["Windows volume"]
node_image_file["Screenshot file"]
node_display["Video display"]

node_user -->|"gestures"| node_webcam
node_webcam -->|"provides frames"| node_main_loop
node_main_loop -->|"processes frames"| node_hand_tracking
node_main_loop -->|"passes landmarks"| node_gesture_mapping
node_main_loop -->|"shows video"| node_display
node_gesture_mapping -->|"moves cursor"| node_cursor
node_cursor -->|"moves pointer"| node_os_mouse
node_gesture_mapping -->|"triggers clicks"| node_mouse_events
node_mouse_events -->|"sends clicks"| node_os_mouse
node_gesture_mapping -->|"captures image"| node_screenshot
node_screenshot -->|"saves image"| node_image_file
node_gesture_mapping -->|"adjusts volume"| node_volume
node_volume -->|"sends key events"| node_volume_service
node_main_loop -->|"imports"| node_geometry_helpers

click node_main_loop "https://github.com/thaqibrahman/ai-virtual-mouse/blob/main/AI%20Virtual%20Mouse/main.py"
click node_hand_tracking "https://github.com/thaqibrahman/ai-virtual-mouse/blob/main/AI%20Virtual%20Mouse/main.py"
click node_gesture_mapping "https://github.com/thaqibrahman/ai-virtual-mouse/blob/main/AI%20Virtual%20Mouse/main.py"
click node_geometry_helpers "https://github.com/thaqibrahman/ai-virtual-mouse/blob/main/AI%20Virtual%20Mouse/util.py"
click node_cursor "https://github.com/thaqibrahman/ai-virtual-mouse/blob/main/AI%20Virtual%20Mouse/main.py"
click node_mouse_events "https://github.com/thaqibrahman/ai-virtual-mouse/blob/main/AI%20Virtual%20Mouse/main.py"
click node_screenshot "https://github.com/thaqibrahman/ai-virtual-mouse/blob/main/AI%20Virtual%20Mouse/main.py"
click node_volume "https://github.com/thaqibrahman/ai-virtual-mouse/blob/main/AI%20Virtual%20Mouse/main.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main_loop,node_hand_tracking,node_gesture_mapping,node_user,node_image_file toneBlue
class node_cursor,node_mouse_events,node_screenshot,node_volume toneAmber
class node_geometry_helpers toneMint
class node_webcam,node_os_mouse,node_volume_service,node_display toneIndigo
```

## Components

### Vision and gesture input

- [Frame loop](https://github.com/thaqibrahman/ai-virtual-mouse/blob/main/AI%20Virtual%20Mouse/main.py): `AI Virtual Mouse/main.py`
- [Hand tracking](https://github.com/thaqibrahman/ai-virtual-mouse/blob/main/AI%20Virtual%20Mouse/main.py): `AI Virtual Mouse/main.py`
- [Gesture mapping](https://github.com/thaqibrahman/ai-virtual-mouse/blob/main/AI%20Virtual%20Mouse/main.py): `AI Virtual Mouse/main.py`

### System actions

- [Cursor movement](https://github.com/thaqibrahman/ai-virtual-mouse/blob/main/AI%20Virtual%20Mouse/main.py): `AI Virtual Mouse/main.py`
- [Click actions](https://github.com/thaqibrahman/ai-virtual-mouse/blob/main/AI%20Virtual%20Mouse/main.py): `AI Virtual Mouse/main.py`
- [Screenshot capture](https://github.com/thaqibrahman/ai-virtual-mouse/blob/main/AI%20Virtual%20Mouse/main.py): `AI Virtual Mouse/main.py`
- [Volume control](https://github.com/thaqibrahman/ai-virtual-mouse/blob/main/AI%20Virtual%20Mouse/main.py): `AI Virtual Mouse/main.py`

### Geometry helpers

- [Geometry helpers](https://github.com/thaqibrahman/ai-virtual-mouse/blob/main/AI%20Virtual%20Mouse/util.py): `AI Virtual Mouse/util.py`

### Other components

- **User hand gestures**
- **Webcam**
- **Desktop mouse**
- **Windows volume**
- **Screenshot file**
- **Video display**

## Connections

- User hand gestures → Webcam: gestures (evidence: `README.md`)
- Webcam → Frame loop: provides frames (evidence: `AI Virtual Mouse/main.py`)
- Frame loop → Hand tracking: processes frames (evidence: `AI Virtual Mouse/main.py`)
- Frame loop → Gesture mapping: passes landmarks (evidence: `AI Virtual Mouse/main.py`)
- Frame loop → Video display: shows video (evidence: `AI Virtual Mouse/main.py`)
- Gesture mapping → Cursor movement: moves cursor (evidence: `AI Virtual Mouse/main.py`)
- Cursor movement → Desktop mouse: moves pointer (evidence: `AI Virtual Mouse/main.py`)
- Gesture mapping → Click actions: triggers clicks (evidence: `AI Virtual Mouse/main.py`)
- Click actions → Desktop mouse: sends clicks (evidence: `AI Virtual Mouse/main.py`)
- Gesture mapping → Screenshot capture: captures image (evidence: `AI Virtual Mouse/main.py`)
- Screenshot capture → Screenshot file: saves image (evidence: `AI Virtual Mouse/main.py`)
- Gesture mapping → Volume control: adjusts volume (evidence: `AI Virtual Mouse/main.py`)
- Volume control → Windows volume: sends key events (evidence: `AI Virtual Mouse/main.py`)
- Frame loop → Geometry helpers: imports (evidence: `AI Virtual Mouse/main.py`)
