# donnahooshmand/retina_painter architecture

> Architecture diagram of the GitHub repository donnahooshmand/retina_painter, 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/donnahooshmand/retina_painter
- Repository: https://github.com/donnahooshmand/retina_painter

## Overview

RetinaPainter is a clinician-facing retinal OCT annotation and segmentation system paired with a training service. The principal workflow is to create a seeded project, review scans and paint sparse corrections, then train and view updated predictions in the painter. The trainer samples corrected tiles, applies masked segmentation loss, validates candidates, and manages checkpoints. The graph includes the documented U-Net, RETFound plain-decoder, and RFA-U-Net options, plus scan-review persistence and evaluation tools. Some connections reflect README claims or SOURCE INDEX references; unsampled code paths are not inferred beyond those references.

Main entry points: [`painter/src/main/python/retina_painter.py`](https://github.com/donnahooshmand/retina_painter/blob/master/painter/src/main/python/retina_painter.py) (Painter UI), [`trainer/src/trainer.py`](https://github.com/donnahooshmand/retina_painter/blob/master/trainer/src/trainer.py) (Project trainer), [`trainer/src/model_utils.py`](https://github.com/donnahooshmand/retina_painter/blob/master/trainer/src/model_utils.py) (Model selection), [`painter/src/main/python/create_project.py`](https://github.com/donnahooshmand/retina_painter/blob/master/painter/src/main/python/create_project.py) (Project setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_painter["Annotation Workstation"]
  node_app["Painter UI<br/>[retina_painter.py]"]
  node_launch["Application entry<br/>[main.py]"]
end

subgraph group_project["Project And Review"]
  node_project_create["Project setup<br/>[create_project.py]"]
  node_review_ui["Review controls<br/>[review_widget.py]"]
  node_review_data[("Review persistence<br/>[review_utils.py]")]
  node_dataset_tools["Dataset preparation<br/>[create_dataset.py]"]
  node_segment["Folder segmentation<br/>[segment_folder.py]"]
  node_metrics_plot["Segmentation metrics"]
end

subgraph group_training["Training Service"]
  node_trainer_entry["Trainer entry"]
  node_trainer["Project trainer<br/>[trainer.py]"]
  node_dataset["Tile sampling<br/>[datasets.py]"]
  node_image_utils["Image processing<br/>[im_utils.py]"]
  node_loss["Masked loss<br/>[loss.py]"]
  node_metrics["Validation metrics<br/>[metrics.py]"]
end

subgraph group_models["Segmentation Models"]
  node_model_utils["Model selection<br/>[model_utils.py]"]
  node_unet["U-Net<br/>[unet.py]"]
  node_retfound["RETFound decoder<br/>[retfound_model.py]"]
  node_rfa["RFA-U-Net decoder"]
  node_vit["RETFound ViT<br/>[retfound_vit.py]"]
end

node_clinician(("Clinician"))
node_oct["OCT scans"]
node_weights["Pretrained weights"]
node_instructions["Training instructions"]

node_clinician -->|"annotates scans"| node_app
node_oct -->|"selects scans"| node_project_create
node_launch -->|"starts"| node_app
node_app -->|"creates project"| node_project_create
node_project_create -->|"configures training"| node_instructions
node_app -->|"collects decisions"| node_review_ui
node_review_ui -->|"persists review"| node_review_data
node_app -->|"loads and saves"| node_review_data
node_app -->|"prepares data"| node_dataset_tools
node_app -->|"requests segmentation"| node_segment
node_app -->|"opens metrics"| node_metrics_plot
node_instructions -.->|"dispatches training"| node_trainer_entry
node_trainer_entry -->|"starts trainer"| node_trainer
node_trainer -->|"samples tiles"| node_dataset
node_dataset -->|"loads and transforms"| node_image_utils
node_trainer -->|"computes objective"| node_loss
node_trainer -->|"validates model"| node_metrics
node_trainer -->|"selects and checkpoints"| node_model_utils
node_model_utils -->|"uses"| node_unet
node_model_utils -->|"uses"| node_retfound
node_model_utils -->|"uses"| node_rfa
node_retfound -->|"encodes features"| node_vit
node_rfa -->|"encodes features"| node_vit
node_weights -->|"initializes encoder"| node_vit
node_trainer -.->|"returns predictions"| node_app
node_clinician -->|"records scan decision"| node_review_ui

click node_app "https://github.com/donnahooshmand/retina_painter/blob/master/painter/src/main/python/retina_painter.py"
click node_launch "https://github.com/donnahooshmand/retina_painter/blob/master/painter/src/main/python/main.py"
click node_project_create "https://github.com/donnahooshmand/retina_painter/blob/master/painter/src/main/python/create_project.py"
click node_review_ui "https://github.com/donnahooshmand/retina_painter/blob/master/painter/src/main/python/review_widget.py"
click node_review_data "https://github.com/donnahooshmand/retina_painter/blob/master/painter/src/main/python/review_utils.py"
click node_dataset_tools "https://github.com/donnahooshmand/retina_painter/blob/master/painter/src/main/python/create_dataset.py"
click node_segment "https://github.com/donnahooshmand/retina_painter/blob/master/painter/src/main/python/segment_folder.py"
click node_metrics_plot "https://github.com/donnahooshmand/retina_painter/blob/master/painter/src/main/python/plot_seg_metrics.py"
click node_trainer "https://github.com/donnahooshmand/retina_painter/blob/master/trainer/src/trainer.py"
click node_dataset "https://github.com/donnahooshmand/retina_painter/blob/master/trainer/src/datasets.py"
click node_image_utils "https://github.com/donnahooshmand/retina_painter/blob/master/trainer/src/im_utils.py"
click node_loss "https://github.com/donnahooshmand/retina_painter/blob/master/trainer/src/loss.py"
click node_metrics "https://github.com/donnahooshmand/retina_painter/blob/master/trainer/src/metrics.py"
click node_model_utils "https://github.com/donnahooshmand/retina_painter/blob/master/trainer/src/model_utils.py"
click node_unet "https://github.com/donnahooshmand/retina_painter/blob/master/trainer/src/unet.py"
click node_retfound "https://github.com/donnahooshmand/retina_painter/blob/master/trainer/src/retfound_model.py"
click node_rfa "https://github.com/donnahooshmand/retina_painter/blob/master/trainer/src/retfound_rfa_model.py"
click node_vit "https://github.com/donnahooshmand/retina_painter/blob/master/trainer/src/retfound_vit.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_app,node_launch toneBlue
class node_project_create,node_review_ui,node_review_data,node_dataset_tools,node_segment,node_metrics_plot toneAmber
class node_trainer_entry,node_trainer,node_dataset,node_image_utils,node_loss,node_metrics toneMint
class node_model_utils,node_unet,node_retfound,node_rfa,node_vit toneRose
class node_clinician,node_oct,node_weights,node_instructions toneIndigo
```

## Components

### Annotation Workstation

- [Painter UI](https://github.com/donnahooshmand/retina_painter/blob/master/painter/src/main/python/retina_painter.py): `painter/src/main/python/retina_painter.py`
- [Application entry](https://github.com/donnahooshmand/retina_painter/blob/master/painter/src/main/python/main.py): `painter/src/main/python/main.py`

### Project And Review

- [Project setup](https://github.com/donnahooshmand/retina_painter/blob/master/painter/src/main/python/create_project.py): `painter/src/main/python/create_project.py`
- [Review controls](https://github.com/donnahooshmand/retina_painter/blob/master/painter/src/main/python/review_widget.py): `painter/src/main/python/review_widget.py`
- [Review persistence](https://github.com/donnahooshmand/retina_painter/blob/master/painter/src/main/python/review_utils.py): `painter/src/main/python/review_utils.py`
- [Dataset preparation](https://github.com/donnahooshmand/retina_painter/blob/master/painter/src/main/python/create_dataset.py): `painter/src/main/python/create_dataset.py`
- [Folder segmentation](https://github.com/donnahooshmand/retina_painter/blob/master/painter/src/main/python/segment_folder.py): `painter/src/main/python/segment_folder.py`
- [Segmentation metrics](https://github.com/donnahooshmand/retina_painter/blob/master/painter/src/main/python/plot_seg_metrics.py): `painter/src/main/python/plot_seg_metrics.py`

### Training Service

- **Trainer entry**
- [Project trainer](https://github.com/donnahooshmand/retina_painter/blob/master/trainer/src/trainer.py): `trainer/src/trainer.py`
- [Tile sampling](https://github.com/donnahooshmand/retina_painter/blob/master/trainer/src/datasets.py): `trainer/src/datasets.py`
- [Image processing](https://github.com/donnahooshmand/retina_painter/blob/master/trainer/src/im_utils.py): `trainer/src/im_utils.py`
- [Masked loss](https://github.com/donnahooshmand/retina_painter/blob/master/trainer/src/loss.py): `trainer/src/loss.py`
- [Validation metrics](https://github.com/donnahooshmand/retina_painter/blob/master/trainer/src/metrics.py): `trainer/src/metrics.py`

### Segmentation Models

- [Model selection](https://github.com/donnahooshmand/retina_painter/blob/master/trainer/src/model_utils.py): `trainer/src/model_utils.py`
- [U-Net](https://github.com/donnahooshmand/retina_painter/blob/master/trainer/src/unet.py): `trainer/src/unet.py`
- [RETFound decoder](https://github.com/donnahooshmand/retina_painter/blob/master/trainer/src/retfound_model.py): `trainer/src/retfound_model.py`
- [RFA-U-Net decoder](https://github.com/donnahooshmand/retina_painter/blob/master/trainer/src/retfound_rfa_model.py): `trainer/src/retfound_rfa_model.py`
- [RETFound ViT](https://github.com/donnahooshmand/retina_painter/blob/master/trainer/src/retfound_vit.py): `trainer/src/retfound_vit.py`

### Other components

- **Clinician**
- **OCT scans**
- **Pretrained weights**
- **Training instructions**

## Connections

- Clinician → Painter UI: annotates scans
- OCT scans → Project setup: selects scans
- Application entry → Painter UI: starts (evidence: `painter/src/main/python/main.py`)
- Painter UI → Project setup: creates project (evidence: `painter/src/main/python/retina_painter.py`)
- Project setup → Training instructions: configures training (evidence: `painter/src/main/python/create_project.py`)
- Painter UI → Review controls: collects decisions (evidence: `painter/src/main/python/retina_painter.py`)
- Review controls → Review persistence: persists review (evidence: `painter/src/main/python/retina_painter.py`)
- Painter UI → Review persistence: loads and saves (evidence: `painter/src/main/python/retina_painter.py`)
- Painter UI → Dataset preparation: prepares data (evidence: `painter/src/main/python/retina_painter.py`)
- Painter UI → Folder segmentation: requests segmentation (evidence: `painter/src/main/python/retina_painter.py`)
- Painter UI → Segmentation metrics: opens metrics (evidence: `painter/src/main/python/retina_painter.py`)
- Training instructions → Trainer entry: dispatches training
- Trainer entry → Project trainer: starts trainer
- Project trainer → Tile sampling: samples tiles (evidence: `trainer/src/trainer.py`)
- Tile sampling → Image processing: loads and transforms (evidence: `trainer/src/datasets.py`)
- Project trainer → Masked loss: computes objective (evidence: `trainer/src/trainer.py`)
- Project trainer → Validation metrics: validates model (evidence: `trainer/src/trainer.py`)
- Project trainer → Model selection: selects and checkpoints (evidence: `trainer/src/trainer.py`)
- Model selection → U-Net: uses (evidence: `trainer/src/model_utils.py`)
- Model selection → RETFound decoder: uses (evidence: `trainer/src/model_utils.py`)
- Model selection → RFA-U-Net decoder: uses (evidence: `trainer/src/model_utils.py`)
- RETFound decoder → RETFound ViT: encodes features (evidence: `trainer/src/retfound_model.py`)
- RFA-U-Net decoder → RETFound ViT: encodes features (evidence: `trainer/src/retfound_rfa_model.py`)
- Pretrained weights → RETFound ViT: initializes encoder (evidence: `trainer/src/retfound_vit.py`)
- Project trainer → Painter UI: returns predictions
- Clinician → Review controls: records scan decision (evidence: `painter/src/main/python/review_widget.py`)