# wangwilly/gaze-correction-cam architecture

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

- Interactive diagram: https://gitdiagram.com/wangwilly/gaze-correction-cam
- Repository: https://github.com/wangwilly/gaze-correction-cam

## Overview

The repository implements a Python webcam gaze-correction workflow: capture frames, detect eye landmarks, estimate and correct gaze, then display the result. The README also describes a macOS virtual-camera output and app controls, but the visible runtime code is the single-window Python CLI; the virtual-camera connection is documented but not shown in source. Model internals are decomposed into network layers and spatial warping. Relationships among sampled modules follow source excerpts and the SOURCE INDEX; no native macOS implementation is present in the tree.

Main entry points: [`displayers/dis_single_window.py`](https://github.com/wangwilly/gaze-correction-cam/blob/master/displayers/dis_single_window.py) (Single-window runner), [`model_managers/gaze_corrector_v1.py`](https://github.com/wangwilly/gaze-correction-cam/blob/master/model_managers/gaze_corrector_v1.py) (Gaze correction), [`tf_models/gaze_corrector_v1/gaze_warp_model.py`](https://github.com/wangwilly/gaze-correction-cam/blob/master/tf_models/gaze_corrector_v1/gaze_warp_model.py) (Gaze warp network), [`bin_single_window.py`](https://github.com/wangwilly/gaze-correction-cam/blob/master/bin_single_window.py) (Python entry point)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Capture and display"]
  node_cli["Python entry point"]
  node_window["Single-window runner"]
end

subgraph group_vision["Face and gaze"]
  node_predictor["Face predictor backends<br/>[face_predictor.py]"]
  node_corrector["Gaze correction"]
end

subgraph group_network["Warping model"]
  node_warp_model["Gaze warp network<br/>[gaze_warp_model.py]"]
  node_layers["Neural network layers<br/>[layers.py]"]
  node_spatial["Spatial transforms"]
end

subgraph group_state["Settings and support"]
  node_settings_db[("User settings store")]
  node_logger["Logger<br/>[logger.py]"]
end

node_user(("Camera user"))
node_camera["Webcam"]
node_camera_output["Virtual camera"]

node_user -->|"starts"| node_cli
node_cli -->|"creates runner"| node_window
node_camera -->|"provides frames"| node_window
node_window -->|"detects eyes"| node_predictor
node_window -->|"corrects frames"| node_corrector
node_corrector -->|"runs inference"| node_warp_model
node_warp_model -->|"uses blocks"| node_layers
node_warp_model -->|"uses transforms"| node_spatial
node_corrector -->|"loads and saves"| node_settings_db
node_window -->|"logs events"| node_logger
node_corrector -->|"logs model events"| node_logger
node_window -.->|"outputs corrected video"| node_camera_output

click node_cli "https://github.com/wangwilly/gaze-correction-cam/blob/master/bin_single_window.py"
click node_window "https://github.com/wangwilly/gaze-correction-cam/blob/master/displayers/dis_single_window.py"
click node_predictor "https://github.com/wangwilly/gaze-correction-cam/blob/master/displayers/face_predictor.py"
click node_corrector "https://github.com/wangwilly/gaze-correction-cam/blob/master/model_managers/gaze_corrector_v1.py"
click node_warp_model "https://github.com/wangwilly/gaze-correction-cam/blob/master/tf_models/gaze_corrector_v1/gaze_warp_model.py"
click node_layers "https://github.com/wangwilly/gaze-correction-cam/blob/master/tf_models/gaze_corrector_v1/layers.py"
click node_spatial "https://github.com/wangwilly/gaze-correction-cam/blob/master/tf_models/gaze_corrector_v1/spatial_transform.py"
click node_settings_db "https://github.com/wangwilly/gaze-correction-cam/blob/master/model_managers/user_settings_db.py"
click node_logger "https://github.com/wangwilly/gaze-correction-cam/blob/master/utils/logger.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_cli,node_window,node_user toneBlue
class node_predictor,node_corrector toneAmber
class node_warp_model,node_layers,node_spatial toneMint
class node_settings_db,node_logger toneRose
class node_camera,node_camera_output toneIndigo
```

## Components

### Capture and display

- [Python entry point](https://github.com/wangwilly/gaze-correction-cam/blob/master/bin_single_window.py): `bin_single_window.py`
- [Single-window runner](https://github.com/wangwilly/gaze-correction-cam/blob/master/displayers/dis_single_window.py): `displayers/dis_single_window.py`

### Face and gaze

- [Face predictor backends](https://github.com/wangwilly/gaze-correction-cam/blob/master/displayers/face_predictor.py): `displayers/face_predictor.py`
- [Gaze correction](https://github.com/wangwilly/gaze-correction-cam/blob/master/model_managers/gaze_corrector_v1.py): `model_managers/gaze_corrector_v1.py`

### Warping model

- [Gaze warp network](https://github.com/wangwilly/gaze-correction-cam/blob/master/tf_models/gaze_corrector_v1/gaze_warp_model.py): `tf_models/gaze_corrector_v1/gaze_warp_model.py`
- [Neural network layers](https://github.com/wangwilly/gaze-correction-cam/blob/master/tf_models/gaze_corrector_v1/layers.py): `tf_models/gaze_corrector_v1/layers.py`
- [Spatial transforms](https://github.com/wangwilly/gaze-correction-cam/blob/master/tf_models/gaze_corrector_v1/spatial_transform.py): `tf_models/gaze_corrector_v1/spatial_transform.py`

### Settings and support

- [User settings store](https://github.com/wangwilly/gaze-correction-cam/blob/master/model_managers/user_settings_db.py): `model_managers/user_settings_db.py`
- [Logger](https://github.com/wangwilly/gaze-correction-cam/blob/master/utils/logger.py): `utils/logger.py`

### Other components

- **Camera user**
- **Webcam**
- **Virtual camera**

## Connections

- Camera user → Python entry point: starts (evidence: `README.md`)
- Python entry point → Single-window runner: creates runner (evidence: `bin_single_window.py`)
- Webcam → Single-window runner: provides frames (evidence: `README.md`)
- Single-window runner → Face predictor backends: detects eyes (evidence: `displayers/dis_single_window.py`)
- Single-window runner → Gaze correction: corrects frames (evidence: `displayers/dis_single_window.py`)
- Gaze correction → Gaze warp network: runs inference (evidence: `model_managers/gaze_corrector_v1.py`)
- Gaze warp network → Neural network layers: uses blocks (evidence: `tf_models/gaze_corrector_v1/gaze_warp_model.py`)
- Gaze warp network → Spatial transforms: uses transforms (evidence: `tf_models/gaze_corrector_v1/gaze_warp_model.py`)
- Gaze correction → User settings store: loads and saves (evidence: `model_managers/gaze_corrector_v1.py`)
- Single-window runner → Logger: logs events (evidence: `displayers/dis_single_window.py`)
- Gaze correction → Logger: logs model events (evidence: `model_managers/gaze_corrector_v1.py`)
- Single-window runner → Virtual camera: outputs corrected video (evidence: `README.md`)
