# q-cardia/qcardia architecture

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

- Interactive diagram: https://gitdiagram.com/q-cardia/qcardia
- Repository: https://github.com/q-cardia/qcardia

## Overview

qcardia is a cardiac-MR analysis package family: data preparation and model components support training, while qcardia classifies and disambiguates DICOM series, builds series objects, and runs inference. The desktop app loads a study, presents series in configurable cardiac-MR layouts, and displays analysis and segmentation results. README statements establish package-level dependencies; sampled source supports several app calls. Some documented app capabilities have unsampled implementations, so their internal links are omitted.

Main entry points: [`packages/qcardia-app/src/qcardia_app/model/dicom_model.py`](https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-app/src/qcardia_app/model/dicom_model.py) (DICOM study model), [`packages/qcardia-app/src/qcardia_app/controllers/dicom_controller.py`](https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-app/src/qcardia_app/controllers/dicom_controller.py) (Study controller), [`packages/qcardia/src/qcardia/series.py`](https://github.com/q-cardia/qcardia/blob/main/packages/qcardia/src/qcardia/series.py) (Series loading and inference), [`packages/qcardia-app/src/qcardia_app/main.py`](https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-app/src/qcardia_app/main.py) (App startup and sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_training_data["Training data"]
  node_data_setup["Dataset setup"]
  node_data_reformat["Dataset reformatting<br/>[reformat.py]"]
  node_data_split["Data splitting<br/>[data_split.py]"]
  node_data_pipeline["Transforms and caching"]
  node_data_prediction["Data prediction pipeline<br/>[data_predictor.py]"]
end

subgraph group_training_models["Training models"]
  node_model_networks["Model architectures<br/>[u_net2d.py]"]
  node_model_blocks["Network building blocks<br/>[building_blocks.py]"]
  node_model_objectives["Losses and metrics"]
end

subgraph group_analysis["Analysis and inference"]
  node_cardisort["CardiSort classification<br/>[cardisort.py]"]
  node_disambiguation["Series disambiguation<br/>[disambiguate.py]"]
  node_series_analysis["Series loading and inference<br/>[series.py]"]
  node_inference["Inference configuration"]
end

subgraph group_viewer["Desktop viewer"]
  node_app_entry["App startup and sessions<br/>[main.py]"]
  node_study_config["Study configuration<br/>[app_config.py]"]
  node_controller["Study controller"]
  node_background_worker["Background worker"]
  node_dicom_model["DICOM study model<br/>[dicom_model.py]"]
  node_hanging_protocols["Hanging protocols"]
  node_study_log["Study logging<br/>[study_log.py]"]
end

subgraph group_viewer_ui["Viewer interface"]
  node_main_window["Main window<br/>[main_window.py]"]
  node_series_browser["Series browser"]
  node_display_area["Image display area"]
  node_graphics_view["Image interaction"]
  node_viewer_capabilities["Cardiac-MR viewing"]
end

node_trained_weights["Trained weights"]
node_study_user(("Viewer user"))

node_data_setup -.->|"prepares datasets"| node_data_reformat
node_data_reformat -.->|"reformats data"| node_data_pipeline
node_data_split -->|"splits data"| node_data_prediction
node_data_pipeline -->|"transforms data"| node_data_prediction
node_model_networks -->|"uses blocks"| node_model_blocks
node_data_pipeline -.->|"supports training"| node_trained_weights
node_model_networks -.->|"supports training"| node_trained_weights
node_model_objectives -.->|"supports training"| node_trained_weights
node_trained_weights -.->|"provides weights"| node_cardisort
node_cardisort -->|"classifies candidates"| node_disambiguation
node_disambiguation -->|"resolves series"| node_series_analysis
node_trained_weights -.->|"provides weights"| node_series_analysis
node_inference -->|"configures inference"| node_series_analysis
node_study_user -.->|"starts study"| node_main_window
node_app_entry -->|"creates window"| node_main_window
node_app_entry -->|"creates controller"| node_controller
node_app_entry -->|"creates model"| node_dicom_model
node_app_entry -->|"starts session logs"| node_study_log
node_controller -->|"starts load worker"| node_background_worker
node_background_worker -->|"calls load patient"| node_dicom_model
node_dicom_model -->|"classifies studies"| node_cardisort
node_dicom_model -->|"resolves candidates"| node_disambiguation
node_dicom_model -->|"loads and analyzes"| node_series_analysis
node_controller -->|"records load events"| node_study_log
node_controller -->|"updates display"| node_display_area
node_controller -->|"builds browser cards"| node_series_browser
node_main_window -->|"hosts browser"| node_series_browser
node_display_area -->|"uses presets"| node_hanging_protocols
node_display_area -->|"renders panels"| node_graphics_view
node_main_window -.->|"presents viewing tools"| node_viewer_capabilities
node_series_analysis -.->|"feeds viewer"| node_dicom_model

click node_data_setup "https://github.com/q-cardia/qcardia/tree/main/packages/qcardia-data/src/qcardia_data/setup"
click node_data_reformat "https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-data/src/qcardia_data/setup/reformat/reformat.py"
click node_data_split "https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-data/src/qcardia_data/pipeline/data_split.py"
click node_data_pipeline "https://github.com/q-cardia/qcardia/tree/main/packages/qcardia-data/src/qcardia_data/pipeline"
click node_data_prediction "https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-data/src/qcardia_data/pipeline/data_predictor.py"
click node_model_networks "https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-models/src/qcardia_models/models/networks/u_net2d.py"
click node_model_blocks "https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-models/src/qcardia_models/models/building_blocks.py"
click node_model_objectives "https://github.com/q-cardia/qcardia/tree/main/packages/qcardia-models/src/qcardia_models/losses"
click node_cardisort "https://github.com/q-cardia/qcardia/blob/main/packages/qcardia/src/qcardia/cardisort.py"
click node_disambiguation "https://github.com/q-cardia/qcardia/blob/main/packages/qcardia/src/qcardia/disambiguate.py"
click node_series_analysis "https://github.com/q-cardia/qcardia/blob/main/packages/qcardia/src/qcardia/series.py"
click node_inference "https://github.com/q-cardia/qcardia/tree/main/packages/qcardia/src/qcardia/inference"
click node_app_entry "https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-app/src/qcardia_app/main.py"
click node_study_config "https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-app/src/qcardia_app/utils/app_config.py"
click node_controller "https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-app/src/qcardia_app/controllers/dicom_controller.py"
click node_background_worker "https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-app/src/qcardia_app/model/background_worker.py"
click node_dicom_model "https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-app/src/qcardia_app/model/dicom_model.py"
click node_hanging_protocols "https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-app/src/qcardia_app/utils/hanging_protocols.py"
click node_study_log "https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-app/src/qcardia_app/utils/study_log.py"
click node_main_window "https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-app/src/qcardia_app/view/main_window.py"
click node_series_browser "https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-app/src/qcardia_app/view/series_browser_widget.py"
click node_display_area "https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-app/src/qcardia_app/view/central_display_area_widget.py"
click node_graphics_view "https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-app/src/qcardia_app/view/custom_graphics_view.py"
click node_viewer_capabilities "https://github.com/q-cardia/qcardia/tree/main/packages/qcardia-app/src/qcardia_app/view"

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_data_setup,node_data_reformat,node_data_split,node_data_pipeline,node_data_prediction,node_study_user toneBlue
class node_model_networks,node_model_blocks,node_model_objectives toneAmber
class node_cardisort,node_disambiguation,node_series_analysis,node_inference toneMint
class node_app_entry,node_study_config,node_controller,node_background_worker,node_dicom_model,node_hanging_protocols,node_study_log toneRose
class node_main_window,node_series_browser,node_display_area,node_graphics_view,node_viewer_capabilities,node_trained_weights toneIndigo
```

## Components

### Training data

- [Dataset setup](https://github.com/q-cardia/qcardia/tree/main/packages/qcardia-data/src/qcardia_data/setup): `packages/qcardia-data/src/qcardia_data/setup`
- [Dataset reformatting](https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-data/src/qcardia_data/setup/reformat/reformat.py): `packages/qcardia-data/src/qcardia_data/setup/reformat/reformat.py`
- [Data splitting](https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-data/src/qcardia_data/pipeline/data_split.py): `packages/qcardia-data/src/qcardia_data/pipeline/data_split.py`
- [Transforms and caching](https://github.com/q-cardia/qcardia/tree/main/packages/qcardia-data/src/qcardia_data/pipeline): `packages/qcardia-data/src/qcardia_data/pipeline`
- [Data prediction pipeline](https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-data/src/qcardia_data/pipeline/data_predictor.py): `packages/qcardia-data/src/qcardia_data/pipeline/data_predictor.py`

### Training models

- [Model architectures](https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-models/src/qcardia_models/models/networks/u_net2d.py): `packages/qcardia-models/src/qcardia_models/models/networks/u_net2d.py`
- [Network building blocks](https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-models/src/qcardia_models/models/building_blocks.py): `packages/qcardia-models/src/qcardia_models/models/building_blocks.py`
- [Losses and metrics](https://github.com/q-cardia/qcardia/tree/main/packages/qcardia-models/src/qcardia_models/losses): `packages/qcardia-models/src/qcardia_models/losses`

### Analysis and inference

- [CardiSort classification](https://github.com/q-cardia/qcardia/blob/main/packages/qcardia/src/qcardia/cardisort.py): `packages/qcardia/src/qcardia/cardisort.py`
- [Series disambiguation](https://github.com/q-cardia/qcardia/blob/main/packages/qcardia/src/qcardia/disambiguate.py): `packages/qcardia/src/qcardia/disambiguate.py`
- [Series loading and inference](https://github.com/q-cardia/qcardia/blob/main/packages/qcardia/src/qcardia/series.py): `packages/qcardia/src/qcardia/series.py`
- [Inference configuration](https://github.com/q-cardia/qcardia/tree/main/packages/qcardia/src/qcardia/inference): `packages/qcardia/src/qcardia/inference`

### Desktop viewer

- [App startup and sessions](https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-app/src/qcardia_app/main.py): `packages/qcardia-app/src/qcardia_app/main.py`
- [Study configuration](https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-app/src/qcardia_app/utils/app_config.py): `packages/qcardia-app/src/qcardia_app/utils/app_config.py`
- [Study controller](https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-app/src/qcardia_app/controllers/dicom_controller.py): `packages/qcardia-app/src/qcardia_app/controllers/dicom_controller.py`
- [Background worker](https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-app/src/qcardia_app/model/background_worker.py): `packages/qcardia-app/src/qcardia_app/model/background_worker.py`
- [DICOM study model](https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-app/src/qcardia_app/model/dicom_model.py): `packages/qcardia-app/src/qcardia_app/model/dicom_model.py`
- [Hanging protocols](https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-app/src/qcardia_app/utils/hanging_protocols.py): `packages/qcardia-app/src/qcardia_app/utils/hanging_protocols.py`
- [Study logging](https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-app/src/qcardia_app/utils/study_log.py): `packages/qcardia-app/src/qcardia_app/utils/study_log.py`

### Viewer interface

- [Main window](https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-app/src/qcardia_app/view/main_window.py): `packages/qcardia-app/src/qcardia_app/view/main_window.py`
- [Series browser](https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-app/src/qcardia_app/view/series_browser_widget.py): `packages/qcardia-app/src/qcardia_app/view/series_browser_widget.py`
- [Image display area](https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-app/src/qcardia_app/view/central_display_area_widget.py): `packages/qcardia-app/src/qcardia_app/view/central_display_area_widget.py`
- [Image interaction](https://github.com/q-cardia/qcardia/blob/main/packages/qcardia-app/src/qcardia_app/view/custom_graphics_view.py): `packages/qcardia-app/src/qcardia_app/view/custom_graphics_view.py`
- [Cardiac-MR viewing](https://github.com/q-cardia/qcardia/tree/main/packages/qcardia-app/src/qcardia_app/view): `packages/qcardia-app/src/qcardia_app/view`

### Other components

- **Trained weights**
- **Viewer user**

## Connections

- Dataset setup → Dataset reformatting: prepares datasets (evidence: `packages/qcardia-data/src/qcardia_data/setup/reformat/reformat.py`)
- Dataset reformatting → Transforms and caching: reformats data
- Data splitting → Data prediction pipeline: splits data (evidence: `packages/qcardia-data/src/qcardia_data/pipeline/data_predictor.py`)
- Transforms and caching → Data prediction pipeline: transforms data (evidence: `packages/qcardia-data/src/qcardia_data/pipeline/data_predictor.py`)
- Model architectures → Network building blocks: uses blocks (evidence: `packages/qcardia-models/src/qcardia_models/models/networks/u_net2d.py`)
- Transforms and caching → Trained weights: supports training
- Model architectures → Trained weights: supports training
- Losses and metrics → Trained weights: supports training
- Trained weights → CardiSort classification: provides weights
- CardiSort classification → Series disambiguation: classifies candidates (evidence: `packages/qcardia/src/qcardia/disambiguate.py`)
- Series disambiguation → Series loading and inference: resolves series (evidence: `packages/qcardia/run.py`)
- Trained weights → Series loading and inference: provides weights
- Inference configuration → Series loading and inference: configures inference (evidence: `packages/qcardia/src/qcardia/series.py`)
- Viewer user → Main window: starts study
- App startup and sessions → Main window: creates window (evidence: `packages/qcardia-app/src/qcardia_app/main.py`)
- App startup and sessions → Study controller: creates controller (evidence: `packages/qcardia-app/src/qcardia_app/main.py`)
- App startup and sessions → DICOM study model: creates model (evidence: `packages/qcardia-app/src/qcardia_app/main.py`)
- App startup and sessions → Study logging: starts session logs (evidence: `packages/qcardia-app/src/qcardia_app/main.py`)
- Study controller → Background worker: starts load worker (evidence: `packages/qcardia-app/src/qcardia_app/controllers/dicom_controller.py`)
- Background worker → DICOM study model: calls load patient (evidence: `packages/qcardia-app/src/qcardia_app/controllers/dicom_controller.py`)
- DICOM study model → CardiSort classification: classifies studies (evidence: `packages/qcardia-app/src/qcardia_app/model/dicom_model.py`)
- DICOM study model → Series disambiguation: resolves candidates (evidence: `packages/qcardia-app/src/qcardia_app/model/dicom_model.py`)
- DICOM study model → Series loading and inference: loads and analyzes (evidence: `packages/qcardia-app/src/qcardia_app/model/dicom_model.py`)
- Study controller → Study logging: records load events (evidence: `packages/qcardia-app/src/qcardia_app/controllers/dicom_controller.py`)
- Study controller → Image display area: updates display (evidence: `packages/qcardia-app/src/qcardia_app/controllers/dicom_controller.py`)
- Study controller → Series browser: builds browser cards (evidence: `packages/qcardia-app/src/qcardia_app/controllers/dicom_controller.py`)
- Main window → Series browser: hosts browser (evidence: `packages/qcardia-app/src/qcardia_app/view/main_window.py`)
- Image display area → Hanging protocols: uses presets (evidence: `packages/qcardia-app/src/qcardia_app/view/central_display_area_widget.py`)
- Image display area → Image interaction: renders panels (evidence: `packages/qcardia-app/src/qcardia_app/view/central_display_area_widget.py`)
- Main window → Cardiac-MR viewing: presents viewing tools (evidence: `packages/qcardia-app/src/qcardia_app/view/main_window.py`)
- Series loading and inference → DICOM study model: feeds viewer (evidence: `packages/qcardia-app/src/qcardia_app/model/dicom_model.py`)
