# frosty-8/eye-cursor architecture

> Architecture diagram of the GitHub repository frosty-8/eye-cursor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/frosty-8/eye-cursor
- Repository: https://github.com/frosty-8/eye-cursor

## Overview

##### Project type and purpose
- This is a single-module Python computer-vision application that tracks eye landmarks via MediaPipe/​OpenCV, detects blinks, and issues system mouse commands with PyAutoGUI. Its core purpose is real-time, hands-free cursor movement and click control.

##### File structure
- Top-level:
- main.py – the entire application
- Makefile – setup automation
- requirements.txt – dependencies
- No separate frontend/backend, no database; it’s a simple pipeline: camera in → ML/​CV processing → OS interaction.

##### README for insights
- Dependencies: mediapipe, opencv-python, pyautogui
- Workflow described: FaceMesh → extract right-eye landmarks for movement → blink detection for clicks → PyAutoGUI issues mouse events.
- No external services, no multi-stage build beyond Python venv.

a. Main components:
1) Input Device – Webcam
2) Video Capture Module (OpenCV)
3) FaceMesh Engine (MediaPipe)
4) Landmark Processor (separate routines in main.py)
- Eye-movement mapper
- Blink detector
5) Cursor Controller (PyAutoGUI interface)
6) User Interface / CLI (captures ‘Q’ to exit)
b. Relationships & data flow:
- Webcam → Video Capture → FaceMesh Engine
- FaceMesh Engine → Landmark Processor
- Landmark Processor → Cursor Controller → OS Mouse API
- CLI monitors keypress events in parallel, feeding back to terminate pipeline
c. Architectural patterns & design principles:
– Pipeline pattern: sequential processing stages
– Single-threaded loop orchestrating capture, processing, actuation
– Clear separation of concerns: capture vs. ML vs. I/O
d. Key technologies & libraries:
– OpenCV (cv2) for frame acquisition and pre/post-processing
– MediaPipe FaceMesh for real-time landmark detection
– PyAutoGUI for OS-level mouse events
– Python 3.x runtime and standard libraries

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Runtime Pipeline"
        direction TB
        Webcam["Input Device: Webcam"]:::input
        Video["Video Capture Module (OpenCV)"]:::processing
        FaceMesh["FaceMesh Engine (MediaPipe)"]:::processing
        subgraph "Landmark Processor"
            direction TB
            EyeMap["Eye-movement mapper"]:::processing
            BlinkDet["Blink detector (threshold <0.004)"]:::processing
        end
        Cursor["Cursor Controller (PyAutoGUI)"]:::actuation
        CLI["User Interface/CLI (exit key)"]:::control
    end

    Webcam -->|"video frame"| Video
    Video -->|"video frame"| FaceMesh
    FaceMesh -->|"landmark coords"| EyeMap
    FaceMesh -->|"landmark coords"| BlinkDet
    EyeMap -->|"cursor coords"| Cursor
    BlinkDet -->|"click event"| Cursor
    CLI -.->|"exit command"| Webcam

    subgraph "Project Files"
        direction TB
        Make["Setup Automation: Makefile"]:::control
        Req["Dependencies: requirements.txt"]:::control
        Readme["Documentation: README.md"]:::control
    end

    click Webcam "https://github.com/frosty-8/eye-cursor/blob/main/main.py"
    click Video "https://github.com/frosty-8/eye-cursor/blob/main/main.py"
    click FaceMesh "https://github.com/frosty-8/eye-cursor/blob/main/main.py"
    click EyeMap "https://github.com/frosty-8/eye-cursor/blob/main/main.py"
    click BlinkDet "https://github.com/frosty-8/eye-cursor/blob/main/main.py"
    click Cursor "https://github.com/frosty-8/eye-cursor/blob/main/main.py"
    click CLI "https://github.com/frosty-8/eye-cursor/blob/main/main.py"
    click Make "https://github.com/frosty-8/eye-cursor/tree/main/Makefile"
    click Req "https://github.com/frosty-8/eye-cursor/blob/main/requirements.txt"
    click Readme "https://github.com/frosty-8/eye-cursor/blob/main/README.md"

    classDef input fill:#D0E7FF,stroke:#333,stroke-width:1px
    classDef processing fill:#D0FFD6,stroke:#333,stroke-width:1px
    classDef actuation fill:#FFE2B3,stroke:#333,stroke-width:1px
    classDef control fill:#E0E0E0,stroke:#333,stroke-width:1px
```
