# raselmandol/brainseg architecture

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

- Interactive diagram: https://gitdiagram.com/raselmandol/brainseg
- Repository: https://github.com/raselmandol/brainseg

## Overview

1. **Overall shape**
   - This is a **desktop GUI application** built around **PyQt6** for brain MRI segmentation.
   - The core runtime is a single-process GUI app that loads an image, runs **PyTorch/UNet inference** from a `.pth` checkpoint, and displays outputs in multiple synchronized views.

2. **Entry points and startup**
   - `brainseg/__main__.py` and `brainseg/main.py` are the launch paths.
   - They bootstrap the Qt application and hand control to the main window, so the app can be started either with `python -m brainseg` or the legacy script path.

3. **Primary UI shell**
   - `brainseg/main_window.py` is the central composition layer.
   - It likely owns the menu/toolbar, dock controls, file actions, run button, progress bar, and coordinates all subwindows and canvases.
   - This is the main boundary between user interaction and the rest of the application.

4. **Image viewing subsystem**
   - `brainseg/canvas.py` provides the interactive image panels.
   - The README describes three synchronized canvases: original image, segmentation mask, and highlighted overlay.
   - These views preserve zoom/pan state while brightness/contrast is adjusted, so the canvas layer is responsible for both rendering and navigation state.

5. **Image preprocessing and display transforms**
   - `brainseg/image_utils.py` likely handles loading MRI slices, resizing, normalization, and conversion between file data and Qt displayable images.
   - The README notes resizing to dimensions compatible with the model encoder, especially multiples of 32, which is an important preprocessing boundary before inference.

6. **Model loading and inference**
   - `brainseg/model.py` is the ML boundary.
   - It likely defines the UNet architecture and the logic for loading `.pth` checkpoints.
   - The app validates selected models immediately and surfaces incompatibility errors, so model loading is an explicit step rather than an implicit runtime failure.

7. **Background execution**
   - `brainseg/worker.py` is the asynchronous execution layer.
   - It likely runs segmentation and/or validation off the UI thread, updating progress and returning results to the main window.
   - This separation keeps the Qt event loop responsive during inference, which matters for larger checkpoints and CPU/GPU execution time.

8. **Statistics and evaluation**
   - `brainseg/statistics_tracker.py` and `brainseg/statistics_window.py` form the measurement subsystem.
   - The app records segmentation metrics such as Dice, Jaccard, Hausdorff, latency, and memory, then presents them in a dedicated statistics window with plots/trends.
   - When ground truth is loaded, the tracker has both prediction and reference inputs for comparison.

9. **Auxiliary windows and user configuration**
   - `brainseg/settings_window.py`, `help_window.py`, `system_info_window.py`, and `statistics_window.py` are supporting dialogs.
   - These are separate UI surfaces for theme/brightness settings, user help, machine/environment details, and metrics review.
   - Their separation suggests a modular dialog-based Qt architecture rather than a monolithic screen.

10. **Theme, palette, and branding**
   - `brainseg/theme.py` and `brainseg/intensity_palette.py` handle visual styling.
   - The app supports light/dark themes and accent colors, plus a custom color palette applied across controls and docks.
   - This is a presentation-layer concern, distinct from image processing and inference.

11. **Assets and packaging**
   - `brainseg/assets` contains bundled resources used by the UI.
   - The repo is packaged for Python distribution via `pyproject.toml`, `setup.py`, and `requirements.txt`, with a GitHub Actions workflow in `.github/workflows/ci-cd.yml`.
   - The README shows both source install and PyPI distribution (`brainseg-ai`), so packaging is part of the public architecture, not just development tooling.

12. **Key data flow to capture in a diagram**
   - User opens an MRI image → image utilities prepare it → main window pushes it to the original canvas.
   - User optionally loads ground truth and a `.pth` model → model layer validates the checkpoint.
   - User runs segmentation → worker executes inference → predicted mask and overlay are rendered to their canvases.
   - Metrics are computed/recorded → statistics tracker updates the statistics window.
   - Settings/theme changes propagate back into the main UI and canvases without restarting the app.

13. **External dependencies that materially shape the architecture**
   - **PyQt6** defines the event-driven desktop UI model and separate dialog/window structure.
   - **PyTorch** defines the inference/runtime boundary and the need for checkpoint validation.
   - The project is oriented toward **Windows desktop usage** but organized as a Python package, so the architecture is portable at the code level even if the primary target platform is Windows.

Main entry points: [`brainseg/main_window.py`](https://github.com/raselmandol/brainseg/blob/main/brainseg/main_window.py) (Main window), [`brainseg/worker.py`](https://github.com/raselmandol/brainseg/blob/main/brainseg/worker.py) (Worker), [`brainseg/theme.py`](https://github.com/raselmandol/brainseg/blob/main/brainseg/theme.py) (Theme), [`brainseg/canvas.py`](https://github.com/raselmandol/brainseg/blob/main/brainseg/canvas.py) (Canvases)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["App runtime"]
  node_entry_main["Entry point<br/>bootstrap<br/>[__main__.py]"]
  node_legacy_main["Legacy main<br/>bootstrap<br/>[main.py]"]
  node_image_utils["Image utils<br/>preprocess<br/>[image_utils.py]"]
  node_model["UNet model<br/>ml-inference<br/>[model.py]"]
  node_worker["Worker<br/>background-task<br/>[worker.py]"]
  node_statistics_tracker["Stats tracker<br/>metrics"]
end

subgraph group_ui["User interface"]
  node_main_window["Main window<br/>orchestrator<br/>[main_window.py]"]
  node_canvas["Canvases<br/>viewer<br/>[canvas.py]"]
  node_statistics_window["Stats window<br/>reporting-ui"]
  node_settings_window["Settings<br/>dialog<br/>[settings_window.py]"]
  node_help_window["Help<br/>dialog<br/>[help_window.py]"]
  node_system_info_window["System info<br/>dialog"]
  node_theme["Theme<br/>presentation<br/>[theme.py]"]
  node_intensity_palette["Palette<br/>presentation"]
  node_assets["Assets<br/>resources"]
end

subgraph group_distribution["Distribution"]
  node_pyproject["Build config<br/>packaging<br/>[pyproject.toml]"]
  node_setup["Setup script<br/>packaging<br/>[setup.py]"]
  node_requirements["Requirements<br/>packaging<br/>[requirements.txt]"]
  node_ci_workflow["CI workflow<br/>release<br/>[ci-cd.yml]"]
end

node_pyqt6(("PyQt6<br/>external-ui"))
node_pytorch(("PyTorch<br/>external-ml"))

node_entry_main -->|"boot"| node_main_window
node_legacy_main -->|"boot"| node_main_window
node_main_window -->|"render"| node_canvas
node_main_window -->|"prepare"| node_image_utils
node_main_window -->|"load model"| node_model
node_main_window -->|"run"| node_worker
node_main_window -->|"open"| node_statistics_window
node_main_window -->|"open"| node_settings_window
node_main_window -->|"open"| node_help_window
node_main_window -->|"open"| node_system_info_window
node_main_window -->|"style"| node_theme
node_main_window -->|"palette"| node_intensity_palette
node_main_window -->|"load resources"| node_assets
node_worker -->|"infer"| node_model
node_worker -->|"record"| node_statistics_tracker
node_statistics_tracker -->|"report"| node_statistics_window
node_image_utils -->|"format"| node_canvas
node_theme -->|"configure"| node_settings_window
node_theme -->|"style"| node_canvas
node_requirements -->|"depends on"| node_pyqt6
node_requirements -->|"depends on"| node_pytorch
node_pyproject -->|"packaging"| node_setup
node_ci_workflow -->|"build"| node_pyproject

click node_entry_main "https://github.com/raselmandol/brainseg/blob/main/brainseg/__main__.py"
click node_legacy_main "https://github.com/raselmandol/brainseg/blob/main/brainseg/main.py"
click node_main_window "https://github.com/raselmandol/brainseg/blob/main/brainseg/main_window.py"
click node_canvas "https://github.com/raselmandol/brainseg/blob/main/brainseg/canvas.py"
click node_image_utils "https://github.com/raselmandol/brainseg/blob/main/brainseg/image_utils.py"
click node_model "https://github.com/raselmandol/brainseg/blob/main/brainseg/model.py"
click node_worker "https://github.com/raselmandol/brainseg/blob/main/brainseg/worker.py"
click node_statistics_tracker "https://github.com/raselmandol/brainseg/blob/main/brainseg/statistics_tracker.py"
click node_statistics_window "https://github.com/raselmandol/brainseg/blob/main/brainseg/statistics_window.py"
click node_settings_window "https://github.com/raselmandol/brainseg/blob/main/brainseg/settings_window.py"
click node_help_window "https://github.com/raselmandol/brainseg/blob/main/brainseg/help_window.py"
click node_system_info_window "https://github.com/raselmandol/brainseg/blob/main/brainseg/system_info_window.py"
click node_theme "https://github.com/raselmandol/brainseg/blob/main/brainseg/theme.py"
click node_intensity_palette "https://github.com/raselmandol/brainseg/blob/main/brainseg/intensity_palette.py"
click node_assets "https://github.com/raselmandol/brainseg/tree/main/brainseg/assets"
click node_pyproject "https://github.com/raselmandol/brainseg/blob/main/pyproject.toml"
click node_setup "https://github.com/raselmandol/brainseg/blob/main/setup.py"
click node_requirements "https://github.com/raselmandol/brainseg/blob/main/requirements.txt"
click node_ci_workflow "https://github.com/raselmandol/brainseg/blob/main/.github/workflows/ci-cd.yml"

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_entry_main,node_legacy_main,node_image_utils,node_model,node_worker,node_statistics_tracker toneBlue
class node_main_window,node_canvas,node_statistics_window,node_settings_window,node_help_window,node_system_info_window,node_theme,node_intensity_palette,node_assets toneAmber
class node_pyproject,node_setup,node_requirements,node_ci_workflow toneMint
class node_pyqt6,node_pytorch toneNeutral
```

## Components

### App runtime

Qt desktop application, image processing, inference, and statistics.

- [Entry point](https://github.com/raselmandol/brainseg/blob/main/brainseg/__main__.py): bootstrap · Qt application startup via module or script entry. · `brainseg/__main__.py`
- [Legacy main](https://github.com/raselmandol/brainseg/blob/main/brainseg/main.py): bootstrap · Legacy launch path that hands off to the Qt app. · `brainseg/main.py`
- [Image utils](https://github.com/raselmandol/brainseg/blob/main/brainseg/image_utils.py): preprocess · Load, resize, normalize, and convert MRI data for display and model input. · `brainseg/image_utils.py`
- [UNet model](https://github.com/raselmandol/brainseg/blob/main/brainseg/model.py): ml-inference · Checkpoint loading and segmentation model boundary. · `brainseg/model.py`
- [Worker](https://github.com/raselmandol/brainseg/blob/main/brainseg/worker.py): background-task · Runs inference and validation off the UI thread. · `brainseg/worker.py`
- [Stats tracker](https://github.com/raselmandol/brainseg/blob/main/brainseg/statistics_tracker.py): metrics · Collects segmentation quality, latency, and memory metrics. · `brainseg/statistics_tracker.py`

### User interface

Main window plus supporting dialogs and visualization surfaces.

- [Main window](https://github.com/raselmandol/brainseg/blob/main/brainseg/main_window.py): orchestrator · Central UI shell coordinating loading, inference, views, and dialogs. · `brainseg/main_window.py`
- [Canvases](https://github.com/raselmandol/brainseg/blob/main/brainseg/canvas.py): viewer · Synchronized MRI, mask, and overlay panels with zoom and pan state. · `brainseg/canvas.py`
- [Stats window](https://github.com/raselmandol/brainseg/blob/main/brainseg/statistics_window.py): reporting-ui · Dedicated view for metrics, plots, and trends. · `brainseg/statistics_window.py`
- [Settings](https://github.com/raselmandol/brainseg/blob/main/brainseg/settings_window.py): dialog · Theme and display configuration dialog. · `brainseg/settings_window.py`
- [Help](https://github.com/raselmandol/brainseg/blob/main/brainseg/help_window.py): dialog · User-facing help and guidance window. · `brainseg/help_window.py`
- [System info](https://github.com/raselmandol/brainseg/blob/main/brainseg/system_info_window.py): dialog · Environment and machine details window. · `brainseg/system_info_window.py`
- [Theme](https://github.com/raselmandol/brainseg/blob/main/brainseg/theme.py): presentation · Light/dark styling and accent coordination across the UI. · `brainseg/theme.py`
- [Palette](https://github.com/raselmandol/brainseg/blob/main/brainseg/intensity_palette.py): presentation · Color mapping used for image display and overlays. · `brainseg/intensity_palette.py`
- [Assets](https://github.com/raselmandol/brainseg/tree/main/brainseg/assets): resources · Bundled UI resources and packaged artwork. · `brainseg/assets`

### Distribution

Packaging and release metadata for installing and shipping the app.

- [Build config](https://github.com/raselmandol/brainseg/blob/main/pyproject.toml): packaging · Python package metadata and distribution configuration. · `pyproject.toml`
- [Setup script](https://github.com/raselmandol/brainseg/blob/main/setup.py): packaging · Legacy installation and build entry for packaging. · `setup.py`
- [Requirements](https://github.com/raselmandol/brainseg/blob/main/requirements.txt): packaging · Pinned runtime dependencies for installation. · `requirements.txt`
- [CI workflow](https://github.com/raselmandol/brainseg/blob/main/.github/workflows/ci-cd.yml): release · Automated build and publish pipeline. · `.github/workflows/ci-cd.yml`

### Other components

- **PyQt6**: external-ui · Event-driven desktop GUI framework.
- **PyTorch**: external-ml · Tensor inference runtime for the segmentation model.

## Connections

- Entry point → Main window: boot · Starts the Qt application and opens the main shell.
- Legacy main → Main window: boot · Alternative launch path into the same UI shell.
- Main window → Canvases: render · Feeds loaded images and prediction results into synchronized views.
- Main window → Image utils: prepare · Uses preprocessing for load, resize, and display conversion.
- Main window → UNet model: load model · Validates and opens the selected checkpoint.
- Main window → Worker: run · Dispatches segmentation work without blocking the UI.
- Main window → Stats window: open · Shows metrics and trend reporting.
- Main window → Settings: open · Opens application settings and display controls.
- Main window → Help: open · Shows help content to the user.
- Main window → System info: open · Displays environment and system details.
- Main window → Theme: style · Applies global UI appearance and accent settings.
- Main window → Palette: palette · Uses intensity color mapping for display surfaces.
- Main window → Assets: load resources · Loads bundled icons and UI resources.
- Worker → UNet model: infer · Runs model inference on prepared image data.
- Worker → Stats tracker: record · Captures metrics from segmentation execution.
- Stats tracker → Stats window: report · Supplies measured values for display and plots.
- Image utils → Canvases: format · Converts image data into display-ready buffers.
- Theme → Settings: configure · Themes and visual preferences are adjusted here.
- Theme → Canvases: style · Canvas rendering follows global theme settings.
- Requirements → PyQt6: depends on · Declares the GUI framework dependency.
- Requirements → PyTorch: depends on · Declares the ML runtime dependency.
- Build config → Setup script: packaging · Project metadata and build configuration align package installation.
- CI workflow → Build config: build · CI uses project metadata to validate and ship releases.