# sigz26/nhlstenden-air-hockey-ai architecture

> Architecture diagram of the GitHub repository sigz26/nhlstenden-air-hockey-ai, 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/sigz26/nhlstenden-air-hockey-ai
- Repository: https://github.com/sigz26/nhlstenden-air-hockey-ai

## Overview

Orion Vision is a desktop air-hockey vision and reinforcement-learning application. The user enters through the Qt interface, chooses a dashboard, and can process live camera input into puck telemetry; the live path can bridge observations to a simulation and SAC agent. A separate trainer workflow builds and trains agents against opponent policies. The README confirms simulation and reinforcement learning, while the source index shows UI wiring and worker dependencies. Several modules are unsampled, so their internal links are omitted where the available evidence does not establish them.

Main entry points: [`Orion Vision/ui/main_window.py`](https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/ui/main_window.py) (Main window), [`Orion Vision/ui/live_dashboard.py`](https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/ui/live_dashboard.py) (Live dashboard), [`Orion Vision/core/live_worker.py`](https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/core/live_worker.py) (Camera worker), [`Orion Vision/core/gige_worker.py`](https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/core/gige_worker.py) (GigE worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Desktop interface"]
  node_main["Application entry<br/>[main.py]"]
  node_window["Main window<br/>[main_window.py]"]
  node_menu["Main menu<br/>[main_menu.py]"]
  node_intro["Intro screen<br/>[intro_widget.py]"]
  node_dashboard["Video dashboard<br/>[dashboard.py]"]
  node_liveui["Live dashboard<br/>[live_dashboard.py]"]
  node_settings["Settings dashboard"]
  node_trainerui["Trainer dashboard"]
  node_twin["Digital twin view"]
end

subgraph group_vision["Vision pipeline"]
  node_liveworker["Camera worker<br/>[live_worker.py]"]
  node_gigeworker["GigE worker<br/>[gige_worker.py]"]
  node_engines["Detection engines"]
  node_aruco["ArUco tracking<br/>[aruco_tracker.py]"]
  node_calibration["Auto calibration"]
  node_overlay["Table overlay<br/>[table_overlay.py]"]
end

subgraph group_simulation["Simulation and AI"]
  node_simbridge["Telemetry bridge<br/>[sim_bridge.py]"]
  node_environment["Air-hockey environment<br/>[air_hockey_env.py]"]
  node_sac["SAC controller<br/>[sac_controller.py]"]
  node_agentworker["Agent worker<br/>[agent_worker.py]"]
end

subgraph group_training["Agent training"]
  node_trainerworker["Trainer worker<br/>[trainer_worker.py]"]
  node_opponents["Opponent policies"]
  node_models["Trained policies"]
end

node_user(("Operator"))
node_externalcamera(("Camera"))
node_video(("Video source"))

node_user -->|"starts"| node_main
node_main -->|"opens"| node_window
node_window -->|"shows"| node_intro
node_window -->|"routes to"| node_menu
node_window -->|"routes to"| node_dashboard
node_window -->|"routes to"| node_liveui
node_window -->|"routes to"| node_settings
node_window -->|"routes to"| node_trainerui
node_dashboard -.->|"reads"| node_video
node_dashboard -.->|"uses"| node_liveworker
node_liveui -->|"starts"| node_liveworker
node_liveui -->|"starts"| node_gigeworker
node_externalcamera -.->|"supplies frames"| node_liveworker
node_externalcamera -.->|"supplies frames"| node_gigeworker
node_liveworker -->|"dispatches frames"| node_engines
node_gigeworker -->|"dispatches frames"| node_engines
node_liveworker -->|"publishes telemetry"| node_simbridge
node_gigeworker -->|"publishes telemetry"| node_simbridge
node_liveworker -->|"uses tracking"| node_aruco
node_gigeworker -->|"uses tracking"| node_aruco
node_liveworker -->|"uses overlay"| node_overlay
node_gigeworker -->|"uses overlay"| node_overlay
node_liveui -->|"configures"| node_calibration
node_liveui -->|"configures"| node_simbridge
node_liveui -->|"starts"| node_agentworker
node_liveui -->|"opens"| node_twin
node_twin -->|"reads state"| node_simbridge
node_agentworker -->|"uses"| node_sac
node_sac -->|"reads observations"| node_simbridge
node_trainerui -->|"starts"| node_trainerworker
node_trainerworker -->|"trains in"| node_environment
node_trainerworker -->|"uses"| node_sac
node_environment -->|"uses opponents"| node_opponents
node_trainerworker -.->|"saves policies"| node_models

click node_main "https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/main.py"
click node_window "https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/ui/main_window.py"
click node_menu "https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/ui/main_menu.py"
click node_intro "https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/intro/intro_widget.py"
click node_dashboard "https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/ui/dashboard.py"
click node_liveui "https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/ui/live_dashboard.py"
click node_settings "https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/ui/settings_dashboard.py"
click node_trainerui "https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/ui/ai_trainer_dashboard.py"
click node_twin "https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/ui/widgets/digital_twin_widget.py"
click node_liveworker "https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/core/live_worker.py"
click node_gigeworker "https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/core/gige_worker.py"
click node_engines "https://github.com/sigz26/nhlstenden-air-hockey-ai/tree/main/Orion%20Vision/core/engines"
click node_aruco "https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/core/engines/aruco_tracker.py"
click node_calibration "https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/core/auto_calibration.py"
click node_overlay "https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/core/table_overlay.py"
click node_simbridge "https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/core/sim_bridge.py"
click node_environment "https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/ai/air_hockey_env.py"
click node_sac "https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/ai/sac_controller.py"
click node_agentworker "https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/ai/agent_worker.py"
click node_trainerworker "https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/ai/trainer_worker.py"
click node_opponents "https://github.com/sigz26/nhlstenden-air-hockey-ai/tree/main/Orion%20Vision/ai/opponents"
click node_models "https://github.com/sigz26/nhlstenden-air-hockey-ai/tree/main/Orion%20Vision/models"

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_main,node_window,node_menu,node_intro,node_dashboard,node_liveui,node_settings,node_trainerui,node_twin toneBlue
class node_liveworker,node_gigeworker,node_engines,node_aruco,node_calibration,node_overlay toneAmber
class node_simbridge,node_environment,node_sac,node_agentworker toneMint
class node_trainerworker,node_opponents,node_models toneRose
class node_user,node_externalcamera,node_video toneIndigo
```

## Components

### Desktop interface

- [Application entry](https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/main.py): `Orion Vision/main.py`
- [Main window](https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/ui/main_window.py): `Orion Vision/ui/main_window.py`
- [Main menu](https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/ui/main_menu.py): `Orion Vision/ui/main_menu.py`
- [Intro screen](https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/intro/intro_widget.py): `Orion Vision/intro/intro_widget.py`
- [Video dashboard](https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/ui/dashboard.py): `Orion Vision/ui/dashboard.py`
- [Live dashboard](https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/ui/live_dashboard.py): `Orion Vision/ui/live_dashboard.py`
- [Settings dashboard](https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/ui/settings_dashboard.py): `Orion Vision/ui/settings_dashboard.py`
- [Trainer dashboard](https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/ui/ai_trainer_dashboard.py): `Orion Vision/ui/ai_trainer_dashboard.py`
- [Digital twin view](https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/ui/widgets/digital_twin_widget.py): `Orion Vision/ui/widgets/digital_twin_widget.py`

### Vision pipeline

- [Camera worker](https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/core/live_worker.py): `Orion Vision/core/live_worker.py`
- [GigE worker](https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/core/gige_worker.py): `Orion Vision/core/gige_worker.py`
- [Detection engines](https://github.com/sigz26/nhlstenden-air-hockey-ai/tree/main/Orion%20Vision/core/engines): `Orion Vision/core/engines`
- [ArUco tracking](https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/core/engines/aruco_tracker.py): `Orion Vision/core/engines/aruco_tracker.py`
- [Auto calibration](https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/core/auto_calibration.py): `Orion Vision/core/auto_calibration.py`
- [Table overlay](https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/core/table_overlay.py): `Orion Vision/core/table_overlay.py`

### Simulation and AI

- [Telemetry bridge](https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/core/sim_bridge.py): `Orion Vision/core/sim_bridge.py`
- [Air-hockey environment](https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/ai/air_hockey_env.py): `Orion Vision/ai/air_hockey_env.py`
- [SAC controller](https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/ai/sac_controller.py): `Orion Vision/ai/sac_controller.py`
- [Agent worker](https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/ai/agent_worker.py): `Orion Vision/ai/agent_worker.py`

### Agent training

- [Trainer worker](https://github.com/sigz26/nhlstenden-air-hockey-ai/blob/main/Orion%20Vision/ai/trainer_worker.py): `Orion Vision/ai/trainer_worker.py`
- [Opponent policies](https://github.com/sigz26/nhlstenden-air-hockey-ai/tree/main/Orion%20Vision/ai/opponents): `Orion Vision/ai/opponents`
- [Trained policies](https://github.com/sigz26/nhlstenden-air-hockey-ai/tree/main/Orion%20Vision/models): `Orion Vision/models`

### Other components

- **Operator**
- **Camera**
- **Video source**

## Connections

- Operator → Application entry: starts (evidence: `Orion Vision/main.py`)
- Application entry → Main window: opens (evidence: `Orion Vision/main.py`)
- Main window → Intro screen: shows (evidence: `Orion Vision/ui/main_window.py`)
- Main window → Main menu: routes to (evidence: `Orion Vision/ui/main_window.py`)
- Main window → Video dashboard: routes to (evidence: `Orion Vision/ui/main_window.py`)
- Main window → Live dashboard: routes to (evidence: `Orion Vision/ui/main_window.py`)
- Main window → Settings dashboard: routes to (evidence: `Orion Vision/ui/main_window.py`)
- Main window → Trainer dashboard: routes to (evidence: `Orion Vision/ui/main_window.py`)
- Video dashboard → Video source: reads (evidence: `Orion Vision/ui/dashboard.py`)
- Video dashboard → Camera worker: uses
- Live dashboard → Camera worker: starts (evidence: `Orion Vision/ui/live_dashboard.py`)
- Live dashboard → GigE worker: starts (evidence: `Orion Vision/ui/live_dashboard.py`)
- Camera → Camera worker: supplies frames
- Camera → GigE worker: supplies frames
- Camera worker → Detection engines: dispatches frames (evidence: `Orion Vision/core/live_worker.py`)
- GigE worker → Detection engines: dispatches frames (evidence: `Orion Vision/core/gige_worker.py`)
- Camera worker → Telemetry bridge: publishes telemetry (evidence: `Orion Vision/core/live_worker.py`)
- GigE worker → Telemetry bridge: publishes telemetry (evidence: `Orion Vision/core/gige_worker.py`)
- Camera worker → ArUco tracking: uses tracking (evidence: `Orion Vision/core/live_worker.py`)
- GigE worker → ArUco tracking: uses tracking (evidence: `Orion Vision/core/gige_worker.py`)
- Camera worker → Table overlay: uses overlay (evidence: `Orion Vision/core/live_worker.py`)
- GigE worker → Table overlay: uses overlay (evidence: `Orion Vision/core/gige_worker.py`)
- Live dashboard → Auto calibration: configures (evidence: `Orion Vision/ui/live_dashboard.py`)
- Live dashboard → Telemetry bridge: configures (evidence: `Orion Vision/ui/live_dashboard.py`)
- Live dashboard → Agent worker: starts (evidence: `Orion Vision/ui/live_dashboard.py`)
- Live dashboard → Digital twin view: opens (evidence: `Orion Vision/ui/live_dashboard.py`)
- Digital twin view → Telemetry bridge: reads state (evidence: `Orion Vision/ui/widgets/digital_twin_widget.py`)
- Agent worker → SAC controller: uses (evidence: `Orion Vision/ai/agent_worker.py`)
- SAC controller → Telemetry bridge: reads observations (evidence: `Orion Vision/ai/sac_controller.py`)
- Trainer dashboard → Trainer worker: starts (evidence: `Orion Vision/ui/ai_trainer_dashboard.py`)
- Trainer worker → Air-hockey environment: trains in (evidence: `Orion Vision/ai/trainer_worker.py`)
- Trainer worker → SAC controller: uses (evidence: `Orion Vision/ai/trainer_worker.py`)
- Air-hockey environment → Opponent policies: uses opponents (evidence: `Orion Vision/ai/air_hockey_env.py`)
- Trainer worker → Trained policies: saves policies
