# saadwazir/medcagd architecture

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

- Interactive diagram: https://gitdiagram.com/saadwazir/medcagd
- Repository: https://github.com/saadwazir/medcagd
- Video tour (about a minute): https://gitdiagram.com/saadwazir/medcagd/video

## Overview

MedCAGD is a PyTorch medical-image segmentation project, configured by default for retinal vessel patches. Its main workflow is paired-image training, iterative validation-based checkpoint selection and early stopping, then final test evaluation and experiment summaries. The model combines a pretrained timm encoder with a custom context-aware decoder and auxiliary segmentation and edge outputs; training uses configurable losses and augmentation. Separate utilities patch images and reconstruct patch sets. The README documents the experiment stages; sampled source confirms key model, data, metric, and runner behavior, while some subsystem wiring is based on README documentation.

Main entry points: [`xrun.py`](https://github.com/saadwazir/medcagd/blob/main/xrun.py) (Experiment runner), [`train.py`](https://github.com/saadwazir/medcagd/blob/main/train.py) (Training loop), [`val_eval.py`](https://github.com/saadwazir/medcagd/blob/main/val_eval.py) (Validation evaluation), [`test_eval.py`](https://github.com/saadwazir/medcagd/blob/main/test_eval.py) (Test evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experiment["Experiment workflow"]
  node_config["Experiment settings<br/>[cfgs.py]"]
  node_runner["Experiment runner<br/>[xrun.py]"]
  node_trainer["Training loop<br/>[train.py]"]
  node_combos["Augmentation combinations"]
  node_earlystop["Early stopping<br/>[stopearly.py]"]
end

subgraph group_segmentation["Segmentation runtime"]
  node_data["Dataset loading and augmentation<br/>[data.py]"]
  node_model["Gated decoder model<br/>[model.py]"]
  node_loss["Segmentation and edge losses<br/>[loss.py]"]
end

subgraph group_evaluation["Validation and results"]
  node_valcheck["Best checkpoint selection<br/>[check_val.py]"]
  node_valeval["Validation evaluation<br/>[val_eval.py]"]
  node_testeval["Test evaluation<br/>[test_eval.py]"]
  node_metrics["Segmentation metrics<br/>[eval_metrics.py]"]
  node_results["Experiment results"]
end

subgraph group_patching["Patch utilities"]
  node_patcher["Image patch extraction<br/>[patch.py]"]
  node_reconstructor["Patch reconstruction<br/>[unpatch.py]"]
end

node_user(("Experiment user"))
node_dataset["Paired image splits"]
node_encoder["Pretrained timm encoder"]
node_patchfiles["Patch files"]

node_user -->|"configures"| node_config
node_user -->|"prepares"| node_dataset
node_user -->|"starts"| node_runner
node_config -->|"configures"| node_runner
node_runner -->|"runs"| node_trainer
node_runner -->|"runs"| node_valeval
node_runner -->|"runs"| node_valcheck
node_runner -->|"runs"| node_earlystop
node_runner -->|"runs"| node_testeval
node_runner -->|"cycles settings"| node_combos
node_runner -->|"writes summary"| node_results
node_dataset -->|"supplies splits"| node_data
node_trainer -->|"loads training data"| node_data
node_trainer -->|"trains"| node_model
node_trainer -->|"computes loss"| node_loss
node_model -.->|"creates encoder"| node_encoder
node_trainer -->|"saves checkpoints"| node_results
node_valeval -->|"loads validation data"| node_data
node_valeval -->|"evaluates"| node_model
node_valeval -->|"computes metrics"| node_metrics
node_valeval -->|"writes validation results"| node_results
node_valcheck -->|"reads validation scores"| node_results
node_valcheck -->|"records best checkpoint"| node_results
node_earlystop -->|"reads best score"| node_results
node_earlystop -->|"writes stop state"| node_results
node_testeval -->|"loads test data"| node_data
node_testeval -->|"evaluates"| node_model
node_testeval -->|"computes metrics"| node_metrics
node_testeval -->|"writes test results"| node_results
node_user -->|"runs utility"| node_patcher
node_patcher -->|"reads images and masks"| node_dataset
node_patcher -->|"writes patches"| node_patchfiles
node_user -->|"runs utility"| node_reconstructor
node_patchfiles -->|"supplies patches"| node_reconstructor
node_reconstructor -->|"writes reconstructed images"| node_results

click node_config "https://github.com/saadwazir/medcagd/blob/main/cfgs.py"
click node_runner "https://github.com/saadwazir/medcagd/blob/main/xrun.py"
click node_trainer "https://github.com/saadwazir/medcagd/blob/main/train.py"
click node_combos "https://github.com/saadwazir/medcagd/blob/main/train_random_comb.csv"
click node_earlystop "https://github.com/saadwazir/medcagd/blob/main/stopearly.py"
click node_valcheck "https://github.com/saadwazir/medcagd/blob/main/check_val.py"
click node_valeval "https://github.com/saadwazir/medcagd/blob/main/val_eval.py"
click node_testeval "https://github.com/saadwazir/medcagd/blob/main/test_eval.py"
click node_metrics "https://github.com/saadwazir/medcagd/blob/main/eval_metrics.py"
click node_data "https://github.com/saadwazir/medcagd/blob/main/data.py"
click node_model "https://github.com/saadwazir/medcagd/blob/main/model.py"
click node_loss "https://github.com/saadwazir/medcagd/blob/main/loss.py"
click node_patcher "https://github.com/saadwazir/medcagd/blob/main/patch.py"
click node_reconstructor "https://github.com/saadwazir/medcagd/blob/main/unpatch.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_config,node_runner,node_trainer,node_combos,node_earlystop,node_user toneBlue
class node_data,node_model,node_loss toneAmber
class node_valcheck,node_valeval,node_testeval,node_metrics,node_results toneMint
class node_patcher,node_reconstructor toneRose
class node_dataset,node_encoder,node_patchfiles toneIndigo
```

## Components

### Experiment workflow

- [Experiment settings](https://github.com/saadwazir/medcagd/blob/main/cfgs.py): `cfgs.py`
- [Experiment runner](https://github.com/saadwazir/medcagd/blob/main/xrun.py): `xrun.py`
- [Training loop](https://github.com/saadwazir/medcagd/blob/main/train.py): `train.py`
- [Augmentation combinations](https://github.com/saadwazir/medcagd/blob/main/train_random_comb.csv): `train_random_comb.csv`
- [Early stopping](https://github.com/saadwazir/medcagd/blob/main/stopearly.py): `stopearly.py`

### Segmentation runtime

- [Dataset loading and augmentation](https://github.com/saadwazir/medcagd/blob/main/data.py): `data.py`
- [Gated decoder model](https://github.com/saadwazir/medcagd/blob/main/model.py): `model.py`
- [Segmentation and edge losses](https://github.com/saadwazir/medcagd/blob/main/loss.py): `loss.py`

### Validation and results

- [Best checkpoint selection](https://github.com/saadwazir/medcagd/blob/main/check_val.py): `check_val.py`
- [Validation evaluation](https://github.com/saadwazir/medcagd/blob/main/val_eval.py): `val_eval.py`
- [Test evaluation](https://github.com/saadwazir/medcagd/blob/main/test_eval.py): `test_eval.py`
- [Segmentation metrics](https://github.com/saadwazir/medcagd/blob/main/eval_metrics.py): `eval_metrics.py`
- **Experiment results**

### Patch utilities

- [Image patch extraction](https://github.com/saadwazir/medcagd/blob/main/patch.py): `patch.py`
- [Patch reconstruction](https://github.com/saadwazir/medcagd/blob/main/unpatch.py): `unpatch.py`

### Other components

- **Experiment user**
- **Paired image splits**
- **Pretrained timm encoder**
- **Patch files**

## Connections

- Experiment user → Experiment settings: configures
- Experiment user → Paired image splits: prepares
- Experiment user → Experiment runner: starts
- Experiment settings → Experiment runner: configures
- Experiment runner → Training loop: runs
- Experiment runner → Validation evaluation: runs
- Experiment runner → Best checkpoint selection: runs
- Experiment runner → Early stopping: runs
- Experiment runner → Test evaluation: runs
- Experiment runner → Augmentation combinations: cycles settings
- Experiment runner → Experiment results: writes summary
- Paired image splits → Dataset loading and augmentation: supplies splits
- Training loop → Dataset loading and augmentation: loads training data
- Training loop → Gated decoder model: trains
- Training loop → Segmentation and edge losses: computes loss
- Gated decoder model → Pretrained timm encoder: creates encoder
- Training loop → Experiment results: saves checkpoints
- Validation evaluation → Dataset loading and augmentation: loads validation data
- Validation evaluation → Gated decoder model: evaluates
- Validation evaluation → Segmentation metrics: computes metrics
- Validation evaluation → Experiment results: writes validation results
- Best checkpoint selection → Experiment results: reads validation scores
- Best checkpoint selection → Experiment results: records best checkpoint
- Early stopping → Experiment results: reads best score
- Early stopping → Experiment results: writes stop state
- Test evaluation → Dataset loading and augmentation: loads test data
- Test evaluation → Gated decoder model: evaluates
- Test evaluation → Segmentation metrics: computes metrics
- Test evaluation → Experiment results: writes test results
- Experiment user → Image patch extraction: runs utility
- Image patch extraction → Paired image splits: reads images and masks
- Image patch extraction → Patch files: writes patches
- Experiment user → Patch reconstruction: runs utility
- Patch files → Patch reconstruction: supplies patches
- Patch reconstruction → Experiment results: writes reconstructed images