# illiaovcharenko/lung-segmentation architecture

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

## Overview

This repository implements supervised lung-area segmentation for chest X-rays. The workflow is to prepare labeled images and saved train/validation/test splits, resize and augment image-mask pairs, train a U-Net variant, retain model weights, then evaluate predicted masks with Jaccard and Dice scores. The README identifies main.ipynb as the workflow entry point and documents both a basic and a VGG11-pretrained model. Notebook internals were not sampled, so links from that orchestration node reflect documented workflow rather than inspected calls; dataset source details are also limited.

Main entry points: [`main.ipynb`](https://github.com/illiaovcharenko/lung-segmentation/blob/master/main.ipynb) (Train/evaluate), [`src/data.py`](https://github.com/illiaovcharenko/lung-segmentation/blob/master/src/data.py) (Image-mask pairs), [`src/metrics.py`](https://github.com/illiaovcharenko/lung-segmentation/blob/master/src/metrics.py) (Overlap metrics), [`src/models.py`](https://github.com/illiaovcharenko/lung-segmentation/blob/master/src/models.py) (VGG11 U-Net)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_pairs["Image-mask pairs<br/>[data.py]"]
  node_augment["Transforms<br/>[data.py]"]
  node_splits["Saved splits<br/>[splits.pk]"]
end

subgraph group_models["Segmentation models"]
  node_unet["Vanilla U-Net<br/>[models.py]"]
  node_pretrained["VGG11 U-Net<br/>[models.py]"]
  node_weights2["unet-2v weights<br/>[unet-2v.pt]"]
  node_weights6["unet-6v weights<br/>[unet-6v.pt]"]
end

subgraph group_workflow["Training workflow"]
  node_notebook["Train/evaluate<br/>[main.ipynb]"]
end

subgraph group_evaluation["Evaluation"]
  node_metrics["Overlap metrics<br/>[metrics.py]"]
  node_masks["Predicted masks"]
  node_results["Evaluation results"]
end

node_operator(("Researcher"))
node_cxr[("CXR dataset")]
node_vgg["ImageNet VGG11"]

node_operator -->|"runs workflow"| node_notebook
node_cxr -->|"provides images"| node_pairs
node_splits -->|"defines partitions"| node_notebook
node_pairs -->|"loads pairs"| node_augment
node_augment -->|"supplies batches"| node_notebook
node_notebook -->|"trains model"| node_unet
node_notebook -->|"trains variant"| node_pretrained
node_vgg -.->|"initializes encoder"| node_pretrained
node_notebook -->|"saves best weights"| node_weights2
node_notebook -->|"saves best weights"| node_weights6
node_notebook -->|"evaluates masks"| node_metrics
node_notebook -->|"produces predictions"| node_masks
node_metrics -->|"computes scores"| node_results
node_operator -->|"reviews scores"| node_results

click node_pairs "https://github.com/illiaovcharenko/lung-segmentation/blob/master/src/data.py"
click node_augment "https://github.com/illiaovcharenko/lung-segmentation/blob/master/src/data.py"
click node_splits "https://github.com/illiaovcharenko/lung-segmentation/blob/master/splits.pk"
click node_notebook "https://github.com/illiaovcharenko/lung-segmentation/blob/master/main.ipynb"
click node_unet "https://github.com/illiaovcharenko/lung-segmentation/blob/master/src/models.py"
click node_pretrained "https://github.com/illiaovcharenko/lung-segmentation/blob/master/src/models.py"
click node_weights2 "https://github.com/illiaovcharenko/lung-segmentation/blob/master/models/unet-2v.pt"
click node_weights6 "https://github.com/illiaovcharenko/lung-segmentation/blob/master/models/unet-6v.pt"
click node_metrics "https://github.com/illiaovcharenko/lung-segmentation/blob/master/src/metrics.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_pairs,node_augment,node_splits toneBlue
class node_unet,node_pretrained,node_weights2,node_weights6,node_cxr toneAmber
class node_notebook toneMint
class node_metrics,node_masks,node_results toneRose
class node_operator,node_vgg toneIndigo
```

## Components

### Data preparation

- [Image-mask pairs](https://github.com/illiaovcharenko/lung-segmentation/blob/master/src/data.py): `src/data.py`
- [Transforms](https://github.com/illiaovcharenko/lung-segmentation/blob/master/src/data.py): `src/data.py`
- [Saved splits](https://github.com/illiaovcharenko/lung-segmentation/blob/master/splits.pk): `splits.pk`

### Segmentation models

- [Vanilla U-Net](https://github.com/illiaovcharenko/lung-segmentation/blob/master/src/models.py): `src/models.py`
- [VGG11 U-Net](https://github.com/illiaovcharenko/lung-segmentation/blob/master/src/models.py): `src/models.py`
- [unet-2v weights](https://github.com/illiaovcharenko/lung-segmentation/blob/master/models/unet-2v.pt): `models/unet-2v.pt`
- [unet-6v weights](https://github.com/illiaovcharenko/lung-segmentation/blob/master/models/unet-6v.pt): `models/unet-6v.pt`

### Training workflow

- [Train/evaluate](https://github.com/illiaovcharenko/lung-segmentation/blob/master/main.ipynb): `main.ipynb`

### Evaluation

- [Overlap metrics](https://github.com/illiaovcharenko/lung-segmentation/blob/master/src/metrics.py): `src/metrics.py`
- **Predicted masks**
- **Evaluation results**

### Other components

- **Researcher**
- **CXR dataset**
- **ImageNet VGG11**

## Connections

- Researcher → Train/evaluate: runs workflow
- CXR dataset → Image-mask pairs: provides images
- Saved splits → Train/evaluate: defines partitions
- Image-mask pairs → Transforms: loads pairs
- Transforms → Train/evaluate: supplies batches
- Train/evaluate → Vanilla U-Net: trains model
- Train/evaluate → VGG11 U-Net: trains variant
- ImageNet VGG11 → VGG11 U-Net: initializes encoder
- Train/evaluate → unet-2v weights: saves best weights
- Train/evaluate → unet-6v weights: saves best weights
- Train/evaluate → Overlap metrics: evaluates masks
- Train/evaluate → Predicted masks: produces predictions
- Overlap metrics → Evaluation results: computes scores
- Researcher → Evaluation results: reviews scores