# k-periodic/polylaue architecture

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

- Interactive diagram: https://gitdiagram.com/k-periodic/polylaue
- Repository: https://github.com/k-periodic/polylaue
- Video tour (about a minute): https://gitdiagram.com/k-periodic/polylaue/video

## Overview

PolyLaue is a desktop application for viewing and analyzing Laue X-ray diffraction scans. The principal workflow is to load a reflections file and scan series, inspect scan images, define mapping regions, and run analysis such as grain-orientation/CSL calculations. Its domain model organizes projects, sections, series, and scans; a useful internal layer provides serialization and editable parameter validation. The README documents the fork’s grain-orientation capability, while the source excerpts do not expose all analysis wiring, so uncertain links are omitted.

Main entry points: [`polylaue/ui/main_window.py`](https://github.com/k-periodic/polylaue/blob/main/polylaue/ui/main_window.py) (Main window), [`polylaue/model/roi_manager.py`](https://github.com/k-periodic/polylaue/blob/main/polylaue/model/roi_manager.py) (ROI manager), [`polylaue/model/hkl_provider.py`](https://github.com/k-periodic/polylaue/blob/main/polylaue/model/hkl_provider.py) (HKL provider), [`polylaue/ui/region_mapping/dialog.py`](https://github.com/k-periodic/polylaue/blob/main/polylaue/ui/region_mapping/dialog.py) (Region mapping)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application UI"]
  node_launcher["Application launcher<br/>[main.py]"]
  node_window["Main window<br/>[main_window.py]"]
  node_image["Scan image view<br/>[image_view.py]"]
  node_project_nav["Project navigator"]
  node_roi_nav["Region navigator"]
  node_hkl_nav["HKL region navigator"]
  node_mapping["Region mapping<br/>[dialog.py]"]
  node_grain_ui["Grain orientation dialog"]
end

subgraph group_project["Project and scans"]
  node_projects["Project manager<br/>[project_manager.py]"]
  node_project_model["Project model<br/>[project.py]"]
  node_section["Section model<br/>[section.py]"]
  node_series["Scan series<br/>[series.py]"]
  node_scan["Scan model<br/>[scan.py]"]
  node_io["Scan and project I/O<br/>[io.py]"]
  node_editable["Editable parameters<br/>[editable.py]"]
  node_serialization["Serialization<br/>[serializable.py]"]
end

subgraph group_regions["Regions and reflections"]
  node_roi_manager["ROI manager<br/>[roi_manager.py]"]
  node_hkl_provider["HKL provider<br/>[hkl_provider.py]"]
  node_reflections["External reflections<br/>[external.py]"]
  node_reflections_editor["Reflections table editor"]
end

subgraph group_analysis["Diffraction analysis"]
  node_find["Reflection finding<br/>[find.py]"]
  node_burn["Burn reflections"]
  node_tracking["Grain tracking<br/>[track.py]"]
  node_angular["Angular shift<br/>[angular_shift.py]"]
  node_geometry["Diffraction geometry<br/>[geometry.py]"]
  node_orientation["Orientation relationship"]
end

node_user(("Scientist"))

node_user -->|"launches"| node_launcher
node_launcher -->|"creates"| node_window
node_window -->|"uses"| node_project_nav
node_window -->|"uses"| node_image
node_window -->|"opens"| node_roi_nav
node_window -->|"opens"| node_hkl_nav
node_window -->|"opens"| node_mapping
node_window -->|"opens"| node_grain_ui
node_window -->|"uses"| node_projects
node_window -->|"uses"| node_project_model
node_window -->|"uses"| node_section
node_window -->|"loads"| node_series
node_window -->|"uses"| node_scan
node_window -->|"uses"| node_io
node_window -->|"uses"| node_roi_manager
node_window -->|"uses"| node_hkl_provider
node_grain_ui -.->|"calculates"| node_orientation
node_roi_nav -->|"edits"| node_roi_manager
node_hkl_nav -->|"edits"| node_roi_manager
node_hkl_nav -->|"resolves HKL"| node_hkl_provider
node_mapping -->|"reads regions"| node_roi_manager
node_mapping -->|"resolves HKL"| node_hkl_provider
node_mapping -->|"reads scan data"| node_series
node_projects -->|"serializes"| node_project_model
node_project_model -->|"uses"| node_section
node_section -->|"organizes"| node_series
node_series -->|"contains"| node_scan
node_hkl_provider -->|"queries"| node_reflections
node_roi_manager -->|"uses HKL type"| node_hkl_provider
node_editable -->|"extends"| node_serialization
node_project_model -->|"uses"| node_editable
node_reflections_editor -.->|"edits table format"| node_reflections
node_window -.->|"launches analysis"| node_find
node_window -.->|"launches analysis"| node_burn
node_window -.->|"launches analysis"| node_tracking
node_window -.->|"launches analysis"| node_angular

click node_launcher "https://github.com/k-periodic/polylaue/blob/main/polylaue/ui/main.py"
click node_window "https://github.com/k-periodic/polylaue/blob/main/polylaue/ui/main_window.py"
click node_image "https://github.com/k-periodic/polylaue/blob/main/polylaue/ui/image_view.py"
click node_project_nav "https://github.com/k-periodic/polylaue/tree/main/polylaue/ui/project_navigator"
click node_roi_nav "https://github.com/k-periodic/polylaue/tree/main/polylaue/ui/regions_navigator"
click node_hkl_nav "https://github.com/k-periodic/polylaue/tree/main/polylaue/ui/hkl_regions_navigator"
click node_mapping "https://github.com/k-periodic/polylaue/blob/main/polylaue/ui/region_mapping/dialog.py"
click node_grain_ui "https://github.com/k-periodic/polylaue/blob/main/polylaue/ui/grain_orientation_dialog.py"
click node_projects "https://github.com/k-periodic/polylaue/blob/main/polylaue/model/project_manager.py"
click node_project_model "https://github.com/k-periodic/polylaue/blob/main/polylaue/model/project.py"
click node_section "https://github.com/k-periodic/polylaue/blob/main/polylaue/model/section.py"
click node_series "https://github.com/k-periodic/polylaue/blob/main/polylaue/model/series.py"
click node_scan "https://github.com/k-periodic/polylaue/blob/main/polylaue/model/scan.py"
click node_io "https://github.com/k-periodic/polylaue/blob/main/polylaue/model/io.py"
click node_roi_manager "https://github.com/k-periodic/polylaue/blob/main/polylaue/model/roi_manager.py"
click node_hkl_provider "https://github.com/k-periodic/polylaue/blob/main/polylaue/model/hkl_provider.py"
click node_reflections "https://github.com/k-periodic/polylaue/blob/main/polylaue/model/reflections/external.py"
click node_reflections_editor "https://github.com/k-periodic/polylaue/blob/main/utils/reflections_table_editor/reflections_table_editor.py"
click node_editable "https://github.com/k-periodic/polylaue/blob/main/polylaue/model/editable.py"
click node_serialization "https://github.com/k-periodic/polylaue/blob/main/polylaue/model/serializable.py"
click node_find "https://github.com/k-periodic/polylaue/blob/main/polylaue/model/core/find.py"
click node_burn "https://github.com/k-periodic/polylaue/blob/main/polylaue/model/core/burn_reflections.py"
click node_tracking "https://github.com/k-periodic/polylaue/blob/main/polylaue/model/core/track.py"
click node_angular "https://github.com/k-periodic/polylaue/blob/main/polylaue/model/core/angular_shift.py"
click node_geometry "https://github.com/k-periodic/polylaue/blob/main/polylaue/model/core/geometry.py"
click node_orientation "https://github.com/k-periodic/polylaue/blob/main/polylaue/model/core/orientation_relationship.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_launcher,node_window,node_image,node_project_nav,node_roi_nav,node_hkl_nav,node_mapping,node_grain_ui toneBlue
class node_projects,node_project_model,node_section,node_series,node_scan,node_io,node_editable,node_serialization toneAmber
class node_roi_manager,node_hkl_provider,node_reflections,node_reflections_editor toneMint
class node_find,node_burn,node_tracking,node_angular,node_geometry,node_orientation toneRose
class node_user toneIndigo
```

## Components

### Application UI

- [Application launcher](https://github.com/k-periodic/polylaue/blob/main/polylaue/ui/main.py): `polylaue/ui/main.py`
- [Main window](https://github.com/k-periodic/polylaue/blob/main/polylaue/ui/main_window.py): `polylaue/ui/main_window.py`
- [Scan image view](https://github.com/k-periodic/polylaue/blob/main/polylaue/ui/image_view.py): `polylaue/ui/image_view.py`
- [Project navigator](https://github.com/k-periodic/polylaue/tree/main/polylaue/ui/project_navigator): `polylaue/ui/project_navigator`
- [Region navigator](https://github.com/k-periodic/polylaue/tree/main/polylaue/ui/regions_navigator): `polylaue/ui/regions_navigator`
- [HKL region navigator](https://github.com/k-periodic/polylaue/tree/main/polylaue/ui/hkl_regions_navigator): `polylaue/ui/hkl_regions_navigator`
- [Region mapping](https://github.com/k-periodic/polylaue/blob/main/polylaue/ui/region_mapping/dialog.py): `polylaue/ui/region_mapping/dialog.py`
- [Grain orientation dialog](https://github.com/k-periodic/polylaue/blob/main/polylaue/ui/grain_orientation_dialog.py): `polylaue/ui/grain_orientation_dialog.py`

### Project and scans

- [Project manager](https://github.com/k-periodic/polylaue/blob/main/polylaue/model/project_manager.py): `polylaue/model/project_manager.py`
- [Project model](https://github.com/k-periodic/polylaue/blob/main/polylaue/model/project.py): `polylaue/model/project.py`
- [Section model](https://github.com/k-periodic/polylaue/blob/main/polylaue/model/section.py): `polylaue/model/section.py`
- [Scan series](https://github.com/k-periodic/polylaue/blob/main/polylaue/model/series.py): `polylaue/model/series.py`
- [Scan model](https://github.com/k-periodic/polylaue/blob/main/polylaue/model/scan.py): `polylaue/model/scan.py`
- [Scan and project I/O](https://github.com/k-periodic/polylaue/blob/main/polylaue/model/io.py): `polylaue/model/io.py`
- [Editable parameters](https://github.com/k-periodic/polylaue/blob/main/polylaue/model/editable.py): `polylaue/model/editable.py`
- [Serialization](https://github.com/k-periodic/polylaue/blob/main/polylaue/model/serializable.py): `polylaue/model/serializable.py`

### Regions and reflections

- [ROI manager](https://github.com/k-periodic/polylaue/blob/main/polylaue/model/roi_manager.py): `polylaue/model/roi_manager.py`
- [HKL provider](https://github.com/k-periodic/polylaue/blob/main/polylaue/model/hkl_provider.py): `polylaue/model/hkl_provider.py`
- [External reflections](https://github.com/k-periodic/polylaue/blob/main/polylaue/model/reflections/external.py): `polylaue/model/reflections/external.py`
- [Reflections table editor](https://github.com/k-periodic/polylaue/blob/main/utils/reflections_table_editor/reflections_table_editor.py): `utils/reflections_table_editor/reflections_table_editor.py`

### Diffraction analysis

- [Reflection finding](https://github.com/k-periodic/polylaue/blob/main/polylaue/model/core/find.py): `polylaue/model/core/find.py`
- [Burn reflections](https://github.com/k-periodic/polylaue/blob/main/polylaue/model/core/burn_reflections.py): `polylaue/model/core/burn_reflections.py`
- [Grain tracking](https://github.com/k-periodic/polylaue/blob/main/polylaue/model/core/track.py): `polylaue/model/core/track.py`
- [Angular shift](https://github.com/k-periodic/polylaue/blob/main/polylaue/model/core/angular_shift.py): `polylaue/model/core/angular_shift.py`
- [Diffraction geometry](https://github.com/k-periodic/polylaue/blob/main/polylaue/model/core/geometry.py): `polylaue/model/core/geometry.py`
- [Orientation relationship](https://github.com/k-periodic/polylaue/blob/main/polylaue/model/core/orientation_relationship.py): `polylaue/model/core/orientation_relationship.py`

### Other components

- **Scientist**

## Connections

- Scientist → Application launcher: launches (evidence: `polylaue/ui/main.py`)
- Application launcher → Main window: creates (evidence: `polylaue/ui/main.py`)
- Main window → Project navigator: uses (evidence: `polylaue/ui/main_window.py`)
- Main window → Scan image view: uses (evidence: `polylaue/ui/main_window.py`)
- Main window → Region navigator: opens (evidence: `polylaue/ui/main_window.py`)
- Main window → HKL region navigator: opens (evidence: `polylaue/ui/main_window.py`)
- Main window → Region mapping: opens (evidence: `polylaue/ui/main_window.py`)
- Main window → Grain orientation dialog: opens (evidence: `polylaue/ui/main_window.py`)
- Main window → Project manager: uses (evidence: `polylaue/ui/main_window.py`)
- Main window → Project model: uses (evidence: `polylaue/ui/main_window.py`)
- Main window → Section model: uses (evidence: `polylaue/ui/main_window.py`)
- Main window → Scan series: loads (evidence: `polylaue/ui/main_window.py`)
- Main window → Scan model: uses (evidence: `polylaue/ui/main_window.py`)
- Main window → Scan and project I/O: uses (evidence: `polylaue/ui/main_window.py`)
- Main window → ROI manager: uses (evidence: `polylaue/ui/main_window.py`)
- Main window → HKL provider: uses (evidence: `polylaue/ui/main_window.py`)
- Grain orientation dialog → Orientation relationship: calculates
- Region navigator → ROI manager: edits (evidence: `polylaue/ui/regions_navigator/dialog.py`)
- HKL region navigator → ROI manager: edits (evidence: `polylaue/ui/hkl_regions_navigator/dialog.py`)
- HKL region navigator → HKL provider: resolves HKL (evidence: `polylaue/ui/hkl_regions_navigator/dialog.py`)
- Region mapping → ROI manager: reads regions (evidence: `polylaue/ui/region_mapping/dialog.py`)
- Region mapping → HKL provider: resolves HKL (evidence: `polylaue/ui/region_mapping/dialog.py`)
- Region mapping → Scan series: reads scan data (evidence: `polylaue/ui/region_mapping/dialog.py`)
- Project manager → Project model: serializes (evidence: `polylaue/model/project_manager.py`)
- Project model → Section model: uses (evidence: `polylaue/model/project.py`)
- Section model → Scan series: organizes (evidence: `polylaue/model/section.py`)
- Scan series → Scan model: contains (evidence: `polylaue/model/series.py`)
- HKL provider → External reflections: queries (evidence: `polylaue/model/hkl_provider.py`)
- ROI manager → HKL provider: uses HKL type (evidence: `polylaue/model/roi_manager.py`)
- Editable parameters → Serialization: extends (evidence: `polylaue/model/editable.py`)
- Project model → Editable parameters: uses (evidence: `polylaue/model/project.py`)
- Reflections table editor → External reflections: edits table format
- Main window → Reflection finding: launches analysis
- Main window → Burn reflections: launches analysis
- Main window → Grain tracking: launches analysis
- Main window → Angular shift: launches analysis