# georgebatch/kvasir-seg architecture

> Architecture diagram of the GitHub repository georgebatch/kvasir-seg, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/georgebatch/kvasir-seg
- Repository: https://github.com/georgebatch/kvasir-seg

## Overview

##### Project type and purpose
- This is a research-oriented, deep-learning semantic segmentation pipeline built around U-Net variants, designed to train, evaluate, and submit polyp-segmentation predictions on the Kvasir-SEG dataset.
- The focus is on data ingestion, preprocessing, model training (with different loss functions and augmentations), checkpoint management, and final-submission benchmarking.

##### File structure
Top-level directories/scripts and their intent:
- data/          → handles downloading and organizing raw Kvasir-SEG images
- train-val-split/ → contains the official train/validation IDs for reproducible splits
- utils/         → Dataset class, transforms, loss/metrics utilities
- models/        → Python modules defining U-Net architectures
- train_models.py → orchestrates training loops, hyperparameterization, checkpoint saving
- notebooks/     → EDA, validation-curve analysis, test-set prediction exploration
- checkpoints/   → stored model weights, best-epoch indices, validation IoU logs
- submission/    → loads a trained model, runs inference frame-by-frame, measures FPS and aggregates predictions

##### README for additional insights
- The README confirms the use of PyTorch (torch, torchvision, torchmetrics), imageio, and defines reproducible commands for launching train_models.py with different loss functions and augmentation flags.
- There is a clear separation between “model development” (models/ + utils/), “training orchestration” (train_models.py + train-val-split + data/), and “analysis & submission” (notebooks/ + submission/).

##### Components
a. Data ingestion & storage
– External dataset (Kvasir-SEG) download → data/
– Train/Val split loader → train-val-split/*.txt
b. Preprocessing & augmentation
– utils/transforms.py plugged into torch DataLoader (utils/dataset.py)
c. Model architectures
– models/unet.py (could expand to multiple variant modules)
d. Training loop
– train_models.py orchestrates:
- reads Dataset from utils
- applies augmentations
- forwards through model
- computes IoULoss, BCEWithLogitsLoss, IoUBCELoss (utils/metrics.py)
- backprop, optimizer step
- checkpoint & best-epoch IoU logging → checkpoints/
e. Evaluation & visualization
– notebooks/eda.ipynb (data distribution, image/label samples)
– notebooks/validation_results.ipynb (learning curves from checkpoints/)
f. Submission pipeline
– submission/submission.py or .ipynb
– loads final checkpoint
– iterates single images, collects predicted masks + FPS
– outputs CSV/log with FPS and IoU reports

##### Relationships & data flow
1. External Storage → data/ → train-val-split → utils/dataset → DataLoader
2. DataLoader + utils/transforms → Model (models/unet) → Loss & Metrics → Backprop
3. Training script ↔ checkpoints
4. Checkpoints → notebooks for visualization
5. Final checkpoint → submission script → External evaluation (MediaEval submission interface)

##### Architectural patterns & design principles
– Pipeline pattern: clear separation of data, model, training, evaluation, submission
– Modular design: one file per concern (dataset, transforms, metrics, model)
– Reproducibility: train-val split files, script-driven training entry point

##### Final checklist
– [ ] All main components labeled
– [ ] Annotations on key technologies (PyTorch, imageio, torchmetrics)
– [ ] Note on external dependencies (dataset URLs, challenge submission endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External dataset
    External["Kvasir-SEG Dataset"]:::external

    %% Data Ingestion & Storage
    subgraph "Data Ingestion & Storage"
        DataCyl[(data/)]:::data
        TrainSplit["train-val-split/"]:::data
        TrainTxt["train.txt"]:::data
        ValTxt["val.txt"]:::data
    end

    %% Preprocessing & Augmentation
    subgraph "Preprocessing & Augmentation"
        Dataset["dataset.py"]:::code
        Transforms["transforms.py"]:::code
    end

    %% Model Architectures
    subgraph "Model Architectures"
        UNet["unet.py"]:::code
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        TrainScript["train_models.py"]:::code
        Metrics["metrics.py"]:::code
    end

    %% Checkpoints
    CheckpointsCyl[(checkpoints/)]:::data

    %% Evaluation & Visualization
    subgraph "Evaluation & Visualization"
        EDA["eda.ipynb"]:::notebook
        ValNb["validation_results.ipynb"]:::notebook
        TestNb["test_predictions.ipynb"]:::notebook
    end

    %% Submission Pipeline
    subgraph "Submission Pipeline"
        SubPy["submission.py"]:::notebook
        SubV2["submission-v2.py"]:::notebook
        SubNB["submission.ipynb"]:::notebook
    end

    %% Connections
    External --> DataCyl
    DataCyl --> TrainSplit
    TrainSplit --> TrainTxt
    TrainSplit --> ValTxt
    TrainTxt --> Dataset
    ValTxt --> Dataset
    Dataset --> Transforms
    Transforms --> TrainScript
    TrainScript --> UNet
    TrainScript --> Metrics
    TrainScript --> CheckpointsCyl
    CheckpointsCyl --> EDA
    CheckpointsCyl --> ValNb
    CheckpointsCyl --> TestNb
    CheckpointsCyl --> SubPy
    CheckpointsCyl --> SubV2
    CheckpointsCyl --> SubNB
    ValNb -->|"feedback"| TrainScript

    %% Click Events
    click DataCyl "https://github.com/georgebatch/kvasir-seg/tree/main/data/"
    click TrainSplit "https://github.com/georgebatch/kvasir-seg/tree/main/train-val-split/"
    click TrainTxt "https://github.com/georgebatch/kvasir-seg/blob/main/train-val-split/train.txt"
    click ValTxt "https://github.com/georgebatch/kvasir-seg/blob/main/train-val-split/val.txt"
    click Dataset "https://github.com/georgebatch/kvasir-seg/blob/main/utils/dataset.py"
    click Transforms "https://github.com/georgebatch/kvasir-seg/blob/main/utils/transforms.py"
    click UNet "https://github.com/georgebatch/kvasir-seg/blob/main/models/unet.py"
    click TrainScript "https://github.com/georgebatch/kvasir-seg/blob/main/train_models.py"
    click Metrics "https://github.com/georgebatch/kvasir-seg/blob/main/utils/metrics.py"
    click CheckpointsCyl "https://github.com/georgebatch/kvasir-seg/tree/main/checkpoints/"
    click EDA "https://github.com/georgebatch/kvasir-seg/blob/main/notebooks/eda.ipynb"
    click ValNb "https://github.com/georgebatch/kvasir-seg/blob/main/notebooks/validation_results.ipynb"
    click TestNb "https://github.com/georgebatch/kvasir-seg/blob/main/notebooks/test_predictions.ipynb"
    click SubPy "https://github.com/georgebatch/kvasir-seg/blob/main/submission/submission.py"
    click SubV2 "https://github.com/georgebatch/kvasir-seg/blob/main/submission/submission-v2.py"
    click SubNB "https://github.com/georgebatch/kvasir-seg/blob/main/submission/submission.ipynb"

    %% Styles
    classDef data fill:#bbdefb,stroke:#1e88e5,stroke-width:2px;
    classDef code fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef notebook fill:#ffe0b2,stroke:#fb8c00,stroke-width:2px;
    classDef external fill:#e0e0e0,stroke:#616161,stroke-width:2px;
```
