raselmandol/brainseg

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.