# chbergmann/opticsworkbench architecture

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

- Interactive diagram: https://gitdiagram.com/chbergmann/opticsworkbench
- Repository: https://github.com/chbergmann/opticsworkbench

## Overview

Optics Workbench is a FreeCAD add-on for geometrical ray tracing. The principal workflow is to prepare CAD geometry, assign it optical behavior, create ray or beam sources, and recompute the document to trace light through the scene. Users can then inspect recorded hit and energy data through plots or spreadsheet export. The graph includes documented lenses, gratings, and analysis tools; some subsystem links are based on the README because their implementation was not sampled.

Main entry points: [`Ray.py`](https://github.com/chbergmann/opticsworkbench/blob/main/Ray.py) (Ray Sources), [`OpticsWorkbench.py`](https://github.com/chbergmann/opticsworkbench/blob/main/OpticsWorkbench.py) (Workbench Operations), [`InitGui.py`](https://github.com/chbergmann/opticsworkbench/blob/main/InitGui.py) (Workbench Commands), [`OpticalObject.py`](https://github.com/chbergmann/opticsworkbench/blob/main/OpticalObject.py) (Optical Elements)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Workbench Setup"]
  node_workbench["Workbench Commands<br/>[InitGui.py]"]
  node_api["Workbench Operations<br/>[OpticsWorkbench.py]"]
end

subgraph group_scene["Optical Scene"]
  node_cad["CAD Geometry"]
  node_optics["Optical Elements<br/>[OpticalObject.py]"]
end

subgraph group_tracing["Ray Tracing"]
  node_ray["Ray Sources<br/>[Ray.py]"]
  node_sunray["Spectral Sources<br/>[SunRay.py]"]
  node_document["FreeCAD Document"]
end

subgraph group_analysis["Results Analysis"]
  node_hits["Hit Statistics<br/>[Ray.py]"]
  node_plots["Hit And Energy Plots<br/>[Plot.py]"]
  node_export["Spreadsheet Export<br/>[OpticsWorkbench.py]"]
end

node_user(("FreeCAD User"))
node_freecad["FreeCAD Runtime"]

node_user -->|"chooses tools"| node_workbench
node_workbench -->|"registers workbench"| node_freecad
node_user -->|"creates geometry"| node_cad
node_user -->|"invokes commands"| node_workbench
node_workbench -->|"dispatches operations"| node_api
node_api -->|"creates sources"| node_ray
node_api -->|"creates elements"| node_optics
node_api -->|"creates spectral group"| node_sunray
node_sunray -->|"creates wavelength rays"| node_ray
node_optics -->|"references base geometry"| node_cad
node_ray -->|"creates ray shapes"| node_document
node_optics -->|"stores optical properties"| node_document
node_ray -->|"traces interactions"| node_optics
node_ray -->|"records hit data"| node_hits
node_plots -->|"reads hit data"| node_hits
node_export -->|"reads hit data"| node_hits
node_user -->|"requests analysis"| node_plots
node_user -->|"requests export"| node_export
node_plots -->|"displays plots"| node_freecad
node_export -->|"creates spreadsheet"| node_document

click node_workbench "https://github.com/chbergmann/opticsworkbench/blob/main/InitGui.py"
click node_api "https://github.com/chbergmann/opticsworkbench/blob/main/OpticsWorkbench.py"
click node_optics "https://github.com/chbergmann/opticsworkbench/blob/main/OpticalObject.py"
click node_ray "https://github.com/chbergmann/opticsworkbench/blob/main/Ray.py"
click node_sunray "https://github.com/chbergmann/opticsworkbench/blob/main/SunRay.py"
click node_hits "https://github.com/chbergmann/opticsworkbench/blob/main/Ray.py"
click node_plots "https://github.com/chbergmann/opticsworkbench/blob/main/Plot.py"
click node_export "https://github.com/chbergmann/opticsworkbench/blob/main/OpticsWorkbench.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_workbench,node_api,node_user toneBlue
class node_cad,node_optics toneAmber
class node_ray,node_sunray,node_document toneMint
class node_hits,node_plots,node_export toneRose
class node_freecad toneIndigo
```

## Components

### Workbench Setup

- [Workbench Commands](https://github.com/chbergmann/opticsworkbench/blob/main/InitGui.py): `InitGui.py`
- [Workbench Operations](https://github.com/chbergmann/opticsworkbench/blob/main/OpticsWorkbench.py): `OpticsWorkbench.py`

### Optical Scene

- **CAD Geometry**
- [Optical Elements](https://github.com/chbergmann/opticsworkbench/blob/main/OpticalObject.py): `OpticalObject.py`

### Ray Tracing

- [Ray Sources](https://github.com/chbergmann/opticsworkbench/blob/main/Ray.py): `Ray.py`
- [Spectral Sources](https://github.com/chbergmann/opticsworkbench/blob/main/SunRay.py): `SunRay.py`
- **FreeCAD Document**

### Results Analysis

- [Hit Statistics](https://github.com/chbergmann/opticsworkbench/blob/main/Ray.py): `Ray.py`
- [Hit And Energy Plots](https://github.com/chbergmann/opticsworkbench/blob/main/Plot.py): `Plot.py`
- [Spreadsheet Export](https://github.com/chbergmann/opticsworkbench/blob/main/OpticsWorkbench.py): `OpticsWorkbench.py`

### Other components

- **FreeCAD User**
- **FreeCAD Runtime**

## Connections

- FreeCAD User → Workbench Commands: chooses tools
- Workbench Commands → FreeCAD Runtime: registers workbench
- FreeCAD User → CAD Geometry: creates geometry
- FreeCAD User → Workbench Commands: invokes commands
- Workbench Commands → Workbench Operations: dispatches operations
- Workbench Operations → Ray Sources: creates sources
- Workbench Operations → Optical Elements: creates elements
- Workbench Operations → Spectral Sources: creates spectral group
- Spectral Sources → Ray Sources: creates wavelength rays
- Optical Elements → CAD Geometry: references base geometry
- Ray Sources → FreeCAD Document: creates ray shapes
- Optical Elements → FreeCAD Document: stores optical properties
- Ray Sources → Optical Elements: traces interactions
- Ray Sources → Hit Statistics: records hit data
- Hit And Energy Plots → Hit Statistics: reads hit data
- Spreadsheet Export → Hit Statistics: reads hit data
- FreeCAD User → Hit And Energy Plots: requests analysis
- FreeCAD User → Spreadsheet Export: requests export
- Hit And Energy Plots → FreeCAD Runtime: displays plots
- Spreadsheet Export → FreeCAD Document: creates spreadsheet