# cheng98989/iris architecture

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

- Interactive diagram: https://gitdiagram.com/cheng98989/iris
- Repository: https://github.com/cheng98989/iris

## Overview

Iris is a local webcam-based desktop gesture controller. Its main workflow captures video, derives and smooths hand landmarks, recognizes gestures, advances a timed interaction state machine, and performs cursor, click, scroll, or media actions; the preview and tray/settings UI support that runtime. The README documents these modes and multi-monitor cursor use. Some subsystems are represented by their exact tree paths but were not sampled, so uncertain internal wiring is omitted.

Main entry points: [`main.py`](https://github.com/cheng98989/iris/blob/main/main.py) (Runtime loop), [`iris/ui.py`](https://github.com/cheng98989/iris/blob/main/iris/ui.py) (Preview & settings), [`iris/hand.py`](https://github.com/cheng98989/iris/blob/main/iris/hand.py) (Landmark detection), [`iris/recognition.py`](https://github.com/cheng98989/iris/blob/main/iris/recognition.py) (Gesture recognition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture & perception"]
  node_camera["Camera capture<br/>[camera.py]"]
  node_hand["Landmark detection<br/>[hand.py]"]
  node_selector["Hand selection<br/>[hand_selector.py]"]
  node_landmarks["Landmark model<br/>[landmarks.py]"]
  node_signals["Signal conditioning<br/>[signals.py]"]
end

subgraph group_control["Gesture control"]
  node_main["Runtime loop<br/>[main.py]"]
  node_recognition["Gesture recognition<br/>[recognition.py]"]
  node_state["State machine<br/>[state.py]"]
end

subgraph group_desktop["Desktop interaction"]
  node_actions["Gesture actions<br/>[actions.py]"]
  node_cursor["Cursor control<br/>[cursor.py]"]
  node_scroll["Scroll rate<br/>[scroll.py]"]
  node_screen["Monitor mapping<br/>[screen.py]"]
end

subgraph group_interface["Interface &amp; settings"]
  node_config["Configuration<br/>[config.py]"]
  node_audio["State audio<br/>[audio.py]"]
  node_overlay["Preview overlay<br/>[overlay.py]"]
  node_ui["Preview &amp; settings<br/>[ui.py]"]
  node_tray["System tray<br/>[ui.py]"]
  node_listener["Hotkey listener<br/>[listener.py]"]
end

node_user(("User"))
node_webcam(("Webcam"))
node_desktop_os(("Desktop OS"))

node_user -->|"presents gestures"| node_webcam
node_webcam -->|"provides frames"| node_camera
node_main -->|"reads frames"| node_camera
node_main -->|"submits frames"| node_hand
node_main -->|"selects hand"| node_selector
node_main -->|"smooths landmarks"| node_signals
node_main -->|"recognizes pose"| node_recognition
node_main -->|"updates state"| node_state
node_main -->|"dispatches actions"| node_actions
node_main -->|"moves pointer"| node_cursor
node_main -->|"computes scroll"| node_scroll
node_main -->|"maps monitors"| node_screen
node_main -->|"draws preview"| node_overlay
node_main -->|"shares preview frame"| node_ui
node_main -->|"checks quit"| node_listener
node_main -->|"loads settings"| node_config
node_main -->|"plays state sound"| node_audio
node_hand -->|"uses landmark schema"| node_landmarks
node_recognition -->|"interprets points"| node_landmarks
node_state -->|"requests sound"| node_audio
node_actions -->|"issues controls"| node_desktop_os
node_cursor -->|"controls pointer"| node_desktop_os
node_scroll -->|"emits wheel input"| node_desktop_os
node_screen -->|"queries displays"| node_desktop_os
node_user -->|"uses preview and settings"| node_ui
node_user -->|"opens tray menu"| node_tray
node_tray -->|"opens panels"| node_ui

click node_main "https://github.com/cheng98989/iris/blob/main/main.py"
click node_camera "https://github.com/cheng98989/iris/blob/main/iris/camera.py"
click node_hand "https://github.com/cheng98989/iris/blob/main/iris/hand.py"
click node_selector "https://github.com/cheng98989/iris/blob/main/iris/hand_selector.py"
click node_landmarks "https://github.com/cheng98989/iris/blob/main/iris/landmarks.py"
click node_signals "https://github.com/cheng98989/iris/blob/main/iris/signals.py"
click node_recognition "https://github.com/cheng98989/iris/blob/main/iris/recognition.py"
click node_state "https://github.com/cheng98989/iris/blob/main/iris/state.py"
click node_actions "https://github.com/cheng98989/iris/blob/main/iris/actions.py"
click node_cursor "https://github.com/cheng98989/iris/blob/main/iris/cursor.py"
click node_scroll "https://github.com/cheng98989/iris/blob/main/iris/scroll.py"
click node_screen "https://github.com/cheng98989/iris/blob/main/iris/screen.py"
click node_config "https://github.com/cheng98989/iris/blob/main/iris/config.py"
click node_audio "https://github.com/cheng98989/iris/blob/main/iris/audio.py"
click node_overlay "https://github.com/cheng98989/iris/blob/main/iris/overlay.py"
click node_ui "https://github.com/cheng98989/iris/blob/main/iris/ui.py"
click node_tray "https://github.com/cheng98989/iris/blob/main/iris/ui.py"
click node_listener "https://github.com/cheng98989/iris/blob/main/iris/listener.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_camera,node_hand,node_selector,node_landmarks,node_signals,node_user toneBlue
class node_main,node_recognition,node_state toneAmber
class node_actions,node_cursor,node_scroll,node_screen toneMint
class node_config,node_audio,node_overlay,node_ui,node_tray,node_listener toneRose
class node_webcam,node_desktop_os toneIndigo
```

## Components

### Capture & perception

- [Camera capture](https://github.com/cheng98989/iris/blob/main/iris/camera.py): `iris/camera.py`
- [Landmark detection](https://github.com/cheng98989/iris/blob/main/iris/hand.py): `iris/hand.py`
- [Hand selection](https://github.com/cheng98989/iris/blob/main/iris/hand_selector.py): `iris/hand_selector.py`
- [Landmark model](https://github.com/cheng98989/iris/blob/main/iris/landmarks.py): `iris/landmarks.py`
- [Signal conditioning](https://github.com/cheng98989/iris/blob/main/iris/signals.py): `iris/signals.py`

### Gesture control

- [Runtime loop](https://github.com/cheng98989/iris/blob/main/main.py): `main.py`
- [Gesture recognition](https://github.com/cheng98989/iris/blob/main/iris/recognition.py): `iris/recognition.py`
- [State machine](https://github.com/cheng98989/iris/blob/main/iris/state.py): `iris/state.py`

### Desktop interaction

- [Gesture actions](https://github.com/cheng98989/iris/blob/main/iris/actions.py): `iris/actions.py`
- [Cursor control](https://github.com/cheng98989/iris/blob/main/iris/cursor.py): `iris/cursor.py`
- [Scroll rate](https://github.com/cheng98989/iris/blob/main/iris/scroll.py): `iris/scroll.py`
- [Monitor mapping](https://github.com/cheng98989/iris/blob/main/iris/screen.py): `iris/screen.py`

### Interface & settings

- [Configuration](https://github.com/cheng98989/iris/blob/main/iris/config.py): `iris/config.py`
- [State audio](https://github.com/cheng98989/iris/blob/main/iris/audio.py): `iris/audio.py`
- [Preview overlay](https://github.com/cheng98989/iris/blob/main/iris/overlay.py): `iris/overlay.py`
- [Preview & settings](https://github.com/cheng98989/iris/blob/main/iris/ui.py): `iris/ui.py`
- [System tray](https://github.com/cheng98989/iris/blob/main/iris/ui.py): `iris/ui.py`
- [Hotkey listener](https://github.com/cheng98989/iris/blob/main/iris/listener.py): `iris/listener.py`

### Other components

- **User**
- **Webcam**
- **Desktop OS**

## Connections

- User → Webcam: presents gestures
- Webcam → Camera capture: provides frames
- Runtime loop → Camera capture: reads frames
- Runtime loop → Landmark detection: submits frames
- Runtime loop → Hand selection: selects hand
- Runtime loop → Signal conditioning: smooths landmarks
- Runtime loop → Gesture recognition: recognizes pose
- Runtime loop → State machine: updates state
- Runtime loop → Gesture actions: dispatches actions
- Runtime loop → Cursor control: moves pointer
- Runtime loop → Scroll rate: computes scroll
- Runtime loop → Monitor mapping: maps monitors
- Runtime loop → Preview overlay: draws preview
- Runtime loop → Preview & settings: shares preview frame
- Runtime loop → Hotkey listener: checks quit
- Runtime loop → Configuration: loads settings
- Runtime loop → State audio: plays state sound
- Landmark detection → Landmark model: uses landmark schema
- Gesture recognition → Landmark model: interprets points
- State machine → State audio: requests sound
- Gesture actions → Desktop OS: issues controls
- Cursor control → Desktop OS: controls pointer
- Scroll rate → Desktop OS: emits wheel input
- Monitor mapping → Desktop OS: queries displays
- User → Preview & settings: uses preview and settings
- User → System tray: opens tray menu
- System tray → Preview & settings: opens panels