# kenny-fred/cursor architecture

> Architecture diagram of the GitHub repository kenny-fred/cursor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kenny-fred/cursor
- Repository: https://github.com/kenny-fred/cursor
- Video tour (about a minute): https://gitdiagram.com/kenny-fred/cursor/video

## Overview

Cursor is a local webcam-based eye-tracking application: users calibrate their gaze against screen targets, then use the personal mapping to control the Windows cursor. Its runtime combines feature extraction, calibration mapping, and grid-based stabilization; separate scripts validate the camera, prototype eye detection, and analyze calibration quality. The main application and its tracking path are only partially excerpted, so their documented relationships are cited to the README; the accuracy script’s dataset read is visible in its source.

Main entry points: [`main.py`](https://github.com/kenny-fred/cursor/blob/main/main.py) (Cursor App), [`3_calibration.py`](https://github.com/kenny-fred/cursor/blob/main/3_calibration.py) (Target Capture), [`5_calib_test.py`](https://github.com/kenny-fred/cursor/blob/main/5_calib_test.py) (Windows Cursor), [`1_cam_test.py`](https://github.com/kenny-fred/cursor/blob/main/1_cam_test.py) (Camera Check)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_calibration["Calibration"]
  node_calibration_capture["Target Capture<br/>[3_calibration.py]"]
  node_feature_extraction["Feature Extraction<br/>[3_calibration.py]"]
  node_calibration_data["Calibration Dataset"]
end

subgraph group_runtime["Cursor Runtime"]
  node_cursor_app["Cursor App<br/>[main.py]"]
  node_gaze_mapping["Gaze Mapping<br/>[main.py]"]
  node_grid_filter["Grid Stabilization<br/>[main.py]"]
  node_cursor_control["Windows Cursor<br/>[5_calib_test.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_accuracy_analysis["Dataset Analysis<br/>[4_accuracy.py]"]
end

subgraph group_prototypes["Hardware Prototypes"]
  node_camera_check["Camera Check<br/>[1_cam_test.py]"]
  node_eye_prototype["Eye Prototype<br/>[2_eye_test.py]"]
end

node_user(("User"))
node_webcam["Webcam"]
node_mediapipe["MediaPipe"]

node_user -->|"tests camera"| node_camera_check
node_webcam -->|"provides frames"| node_camera_check
node_user -->|"tests detection"| node_eye_prototype
node_webcam -->|"provides frames"| node_eye_prototype
node_user -->|"looks at targets"| node_calibration_capture
node_webcam -->|"provides frames"| node_calibration_capture
node_calibration_capture -->|"collects measurements"| node_feature_extraction
node_mediapipe -->|"detects landmarks"| node_feature_extraction
node_feature_extraction -->|"stores samples"| node_calibration_data
node_calibration_data -->|"loads dataset"| node_accuracy_analysis
node_user -->|"starts tracking"| node_cursor_app
node_webcam -->|"provides frames"| node_cursor_app
node_mediapipe -->|"extracts landmarks"| node_cursor_app
node_calibration_data -->|"fits personal model"| node_gaze_mapping
node_cursor_app -->|"maps features"| node_gaze_mapping
node_gaze_mapping -->|"filters positions"| node_grid_filter
node_grid_filter -->|"stabilizes movement"| node_cursor_control
node_cursor_control -->|"moves pointer"| node_user

click node_camera_check "https://github.com/kenny-fred/cursor/blob/main/1_cam_test.py"
click node_eye_prototype "https://github.com/kenny-fred/cursor/blob/main/2_eye_test.py"
click node_calibration_capture "https://github.com/kenny-fred/cursor/blob/main/3_calibration.py"
click node_feature_extraction "https://github.com/kenny-fred/cursor/blob/main/3_calibration.py"
click node_accuracy_analysis "https://github.com/kenny-fred/cursor/blob/main/4_accuracy.py"
click node_cursor_app "https://github.com/kenny-fred/cursor/blob/main/main.py"
click node_gaze_mapping "https://github.com/kenny-fred/cursor/blob/main/main.py"
click node_grid_filter "https://github.com/kenny-fred/cursor/blob/main/main.py"
click node_cursor_control "https://github.com/kenny-fred/cursor/blob/main/5_calib_test.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_calibration_capture,node_feature_extraction,node_calibration_data,node_user toneBlue
class node_cursor_app,node_gaze_mapping,node_grid_filter,node_cursor_control toneAmber
class node_accuracy_analysis,node_mediapipe toneMint
class node_camera_check,node_eye_prototype toneRose
class node_webcam toneIndigo
```

## Components

### Calibration

- [Target Capture](https://github.com/kenny-fred/cursor/blob/main/3_calibration.py): `3_calibration.py`
- [Feature Extraction](https://github.com/kenny-fred/cursor/blob/main/3_calibration.py): `3_calibration.py`
- **Calibration Dataset**

### Cursor Runtime

- [Cursor App](https://github.com/kenny-fred/cursor/blob/main/main.py): `main.py`
- [Gaze Mapping](https://github.com/kenny-fred/cursor/blob/main/main.py): `main.py`
- [Grid Stabilization](https://github.com/kenny-fred/cursor/blob/main/main.py): `main.py`
- [Windows Cursor](https://github.com/kenny-fred/cursor/blob/main/5_calib_test.py): `5_calib_test.py`

### Evaluation

- [Dataset Analysis](https://github.com/kenny-fred/cursor/blob/main/4_accuracy.py): `4_accuracy.py`

### Hardware Prototypes

- [Camera Check](https://github.com/kenny-fred/cursor/blob/main/1_cam_test.py): `1_cam_test.py`
- [Eye Prototype](https://github.com/kenny-fred/cursor/blob/main/2_eye_test.py): `2_eye_test.py`

### Other components

- **User**
- **Webcam**
- **MediaPipe**

## Connections

- User → Camera Check: tests camera (evidence: `README.md`)
- Webcam → Camera Check: provides frames (evidence: `README.md`)
- User → Eye Prototype: tests detection (evidence: `README.md`)
- Webcam → Eye Prototype: provides frames (evidence: `README.md`)
- User → Target Capture: looks at targets (evidence: `README.md`)
- Webcam → Target Capture: provides frames (evidence: `README.md`)
- Target Capture → Feature Extraction: collects measurements (evidence: `README.md`)
- MediaPipe → Feature Extraction: detects landmarks (evidence: `README.md`)
- Feature Extraction → Calibration Dataset: stores samples (evidence: `README.md`)
- Calibration Dataset → Dataset Analysis: loads dataset (evidence: `4_accuracy.py`)
- User → Cursor App: starts tracking (evidence: `README.md`)
- Webcam → Cursor App: provides frames (evidence: `README.md`)
- MediaPipe → Cursor App: extracts landmarks (evidence: `README.md`)
- Calibration Dataset → Gaze Mapping: fits personal model (evidence: `README.md`)
- Cursor App → Gaze Mapping: maps features (evidence: `README.md`)
- Gaze Mapping → Grid Stabilization: filters positions (evidence: `README.md`)
- Grid Stabilization → Windows Cursor: stabilizes movement (evidence: `README.md`)
- Windows Cursor → User: moves pointer (evidence: `README.md`)
