# ninjacat10/eye-head-mouse architecture

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

- Interactive diagram: https://gitdiagram.com/ninjacat10/eye-head-mouse
- Repository: https://github.com/ninjacat10/eye-head-mouse
- Video tour (about a minute): https://gitdiagram.com/ninjacat10/eye-head-mouse/video

## Overview

Eye + Head Mouse is a Windows webcam-based hands-free mouse. A worker processes camera frames into facial features and either gesture or head-nod click signals; a confidence gate and Brain coordinate pointing, clicks, and interaction modes before issuing mouse actions. The Qt panel, calibration window, and overlay expose controls and feedback. README documents additional menu actions and optional eye-gaze calibration. Some internal wiring is unsampled, so edges for documented but unseen relationships cite the README; the graph omits uncertain implementation details.

Main entry points: [`src/main.py`](https://github.com/ninjacat10/eye-head-mouse/blob/main/src/main.py) (Frame worker), [`src/eyemouse/state_manager.py`](https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/state_manager.py) (Tracking Brain), [`src/eyemouse/control_panel.py`](https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/control_panel.py) (Control panel), [`src/eyemouse/eye_tracker.py`](https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/eye_tracker.py) (Face features)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_vision["Vision and input"]
  node_worker["Frame worker<br/>[main.py]"]
  node_camera["Camera capture<br/>[camera.py]"]
  node_eye["Face features<br/>[eye_tracker.py]"]
  node_classifier["Head classifier<br/>[head_classifier.py]"]
  node_gestures["Gesture detection<br/>[gestures.py]"]
end

subgraph group_control["Tracking control"]
  node_gate["Confidence gate<br/>[confidence_gate.py]"]
  node_brain["Tracking Brain<br/>[state_manager.py]"]
  node_headmap["Head mapping<br/>[head_pointer.py]"]
  node_gazemap["Gaze calibration<br/>[gaze_mapper.py]"]
  node_smoothing["Signal smoothing<br/>[smoothing.py]"]
  node_clicks["Click state machine"]
  node_caldata[("Calibration data<br/>[paths.py]")]
end

subgraph group_interaction["Mouse interaction"]
  node_scroll_drag["Scroll and drag<br/>[scroll_drag.py]"]
  node_cursor["System cursor"]
end

subgraph group_interface["UI and calibration"]
  node_panel["Control panel<br/>[control_panel.py]"]
  node_overlay["Navigator overlay<br/>[overlay.py]"]
  node_calibration["Calibration UI<br/>[calibration_ui.py]"]
  node_config["Settings<br/>[config.py]"]
end

node_user(("User"))
node_webcam["Webcam"]
node_os["Windows desktop"]

node_user -->|"faces"| node_webcam
node_webcam -->|"captures frames"| node_camera
node_worker -->|"reads frames"| node_camera
node_worker -->|"processes frames"| node_eye
node_worker -->|"runs nod model"| node_classifier
node_worker -->|"checks probabilities"| node_gate
node_worker -->|"detects gestures"| node_gestures
node_worker -->|"updates tracking"| node_brain
node_eye -->|"supplies pose"| node_headmap
node_eye -->|"supplies features"| node_gazemap
node_gestures -->|"provides click signal"| node_gate
node_gate -->|"provides confidence"| node_brain
node_brain -->|"maps head pointing"| node_headmap
node_brain -->|"maps eye gaze"| node_gazemap
node_brain -->|"smooths pointing"| node_smoothing
node_brain -->|"advances click state"| node_clicks
node_brain -->|"controls modes"| node_scroll_drag
node_brain -->|"issues mouse actions"| node_cursor
node_cursor -->|"moves and clicks"| node_os
node_user -->|"sets controls"| node_panel
node_panel -->|"sends commands"| node_worker
node_worker -->|"reports status"| node_panel
node_worker -->|"publishes status"| node_overlay
node_user -->|"provides calibration targets"| node_calibration
node_calibration -->|"returns mapper"| node_worker
node_headmap -->|"loads and saves calibration"| node_caldata
node_gazemap -->|"loads and saves calibration"| node_caldata
node_panel -->|"tunes and saves settings"| node_config
node_brain -->|"supplies display state"| node_overlay

click node_worker "https://github.com/ninjacat10/eye-head-mouse/blob/main/src/main.py"
click node_camera "https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/camera.py"
click node_eye "https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/eye_tracker.py"
click node_classifier "https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/head_classifier.py"
click node_gestures "https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/gestures.py"
click node_gate "https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/confidence_gate.py"
click node_brain "https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/state_manager.py"
click node_headmap "https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/head_pointer.py"
click node_gazemap "https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/gaze_mapper.py"
click node_smoothing "https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/smoothing.py"
click node_clicks "https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/click_controller.py"
click node_scroll_drag "https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/scroll_drag.py"
click node_cursor "https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/cursor_controller.py"
click node_panel "https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/control_panel.py"
click node_overlay "https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/overlay.py"
click node_calibration "https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/calibration_ui.py"
click node_config "https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/config.py"
click node_caldata "https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/paths.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_worker,node_camera,node_eye,node_classifier,node_gestures,node_user toneBlue
class node_gate,node_brain,node_headmap,node_gazemap,node_smoothing,node_clicks,node_caldata toneAmber
class node_scroll_drag,node_cursor toneMint
class node_panel,node_overlay,node_calibration,node_config toneRose
class node_webcam,node_os toneIndigo
```

## Components

### Vision and input

- [Frame worker](https://github.com/ninjacat10/eye-head-mouse/blob/main/src/main.py): `src/main.py`
- [Camera capture](https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/camera.py): `src/eyemouse/camera.py`
- [Face features](https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/eye_tracker.py): `src/eyemouse/eye_tracker.py`
- [Head classifier](https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/head_classifier.py): `src/eyemouse/head_classifier.py`
- [Gesture detection](https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/gestures.py): `src/eyemouse/gestures.py`

### Tracking control

- [Confidence gate](https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/confidence_gate.py): `src/eyemouse/confidence_gate.py`
- [Tracking Brain](https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/state_manager.py): `src/eyemouse/state_manager.py`
- [Head mapping](https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/head_pointer.py): `src/eyemouse/head_pointer.py`
- [Gaze calibration](https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/gaze_mapper.py): `src/eyemouse/gaze_mapper.py`
- [Signal smoothing](https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/smoothing.py): `src/eyemouse/smoothing.py`
- [Click state machine](https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/click_controller.py): `src/eyemouse/click_controller.py`
- [Calibration data](https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/paths.py): `src/eyemouse/paths.py`

### Mouse interaction

- [Scroll and drag](https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/scroll_drag.py): `src/eyemouse/scroll_drag.py`
- [System cursor](https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/cursor_controller.py): `src/eyemouse/cursor_controller.py`

### UI and calibration

- [Control panel](https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/control_panel.py): `src/eyemouse/control_panel.py`
- [Navigator overlay](https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/overlay.py): `src/eyemouse/overlay.py`
- [Calibration UI](https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/calibration_ui.py): `src/eyemouse/calibration_ui.py`
- [Settings](https://github.com/ninjacat10/eye-head-mouse/blob/main/src/eyemouse/config.py): `src/eyemouse/config.py`

### Other components

- **User**
- **Webcam**
- **Windows desktop**

## Connections

- User → Webcam: faces (evidence: `README.md`)
- Webcam → Camera capture: captures frames (evidence: `README.md`)
- Frame worker → Camera capture: reads frames (evidence: `src/main.py`)
- Frame worker → Face features: processes frames (evidence: `src/main.py`)
- Frame worker → Head classifier: runs nod model (evidence: `src/main.py`)
- Frame worker → Confidence gate: checks probabilities (evidence: `src/main.py`)
- Frame worker → Gesture detection: detects gestures (evidence: `src/main.py`)
- Frame worker → Tracking Brain: updates tracking (evidence: `src/main.py`)
- Face features → Head mapping: supplies pose (evidence: `README.md`)
- Face features → Gaze calibration: supplies features (evidence: `README.md`)
- Gesture detection → Confidence gate: provides click signal (evidence: `README.md`)
- Confidence gate → Tracking Brain: provides confidence (evidence: `src/main.py`)
- Tracking Brain → Head mapping: maps head pointing (evidence: `src/eyemouse/state_manager.py`)
- Tracking Brain → Gaze calibration: maps eye gaze (evidence: `src/eyemouse/state_manager.py`)
- Tracking Brain → Signal smoothing: smooths pointing (evidence: `src/eyemouse/state_manager.py`)
- Tracking Brain → Click state machine: advances click state (evidence: `src/eyemouse/state_manager.py`)
- Tracking Brain → Scroll and drag: controls modes (evidence: `src/eyemouse/state_manager.py`)
- Tracking Brain → System cursor: issues mouse actions (evidence: `src/eyemouse/state_manager.py`)
- System cursor → Windows desktop: moves and clicks (evidence: `src/eyemouse/cursor_controller.py`)
- User → Control panel: sets controls (evidence: `README.md`)
- Control panel → Frame worker: sends commands (evidence: `src/main.py`)
- Frame worker → Control panel: reports status (evidence: `src/main.py`)
- Frame worker → Navigator overlay: publishes status (evidence: `src/main.py`)
- User → Calibration UI: provides calibration targets (evidence: `README.md`)
- Calibration UI → Frame worker: returns mapper (evidence: `src/main.py`)
- Head mapping → Calibration data: loads and saves calibration (evidence: `src/eyemouse/head_pointer.py`)
- Gaze calibration → Calibration data: loads and saves calibration (evidence: `src/eyemouse/gaze_mapper.py`)
- Control panel → Settings: tunes and saves settings (evidence: `src/eyemouse/control_panel.py`)
- Tracking Brain → Navigator overlay: supplies display state (evidence: `README.md`)
