# eeeric-code/i3net architecture

> Architecture diagram of the GitHub repository eeeric-code/i3net, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eeeric-code/i3net
- Repository: https://github.com/eeeric-code/i3net

## Overview

##### Project type and purpose
- Type: Deep-learning research repository implementing the I³Net model for medical slice interpolation (CT & MR).
- Purpose: Train and evaluate an inter-intra-slice interpolation network that synthesizes missing 2D slices in 3D medical volumes.

##### High-level components
A. Data Acquisition & Preparation
B. Data Loading & Configuration
C. Model Definition (Generator & Discriminator)
D. Training & Optimization
E. Evaluation & Experiments Storage

##### Detailed breakdown & relationships
A. Data Acquisition & Preparation (green)
- Raw datasets: Medical Decathlon (Liver, Colon, Hepatic Vessel), IXI MR
- data_prepare/step1_split.py → splits volumes into train/test using test_set.pt
- data_prepare/step2_save_slice.py → writes individual slices to disk
→ Output: folder of 2D slice images (.pt or numpy)

B. Data Loading & Configuration (light blue)
- config.py: global hyperparameters (batch size, learning rate, paths)
- opt/i3net.json: model-specific options (number of slices to interpolate, DCT settings)
- data.py & util.py: PyTorch Dataset & DataLoader modules that read saved slices
- select_model.py: chooses I3Net implementation from model_zoo
- select_loss.py: picks loss functions from losses/

C. Model Definition (blue)
- model_zoo/i3net/basic_model.py: main Inter-Intra-slice U-Net architecture
- model_zoo/i3net/dct_util.py + utils_win.py: DCT transforms & sliding windows for intra-slice features
- losses/ (yellow): adversarial.py, contrastive_loss.py, edge_loss.py, focal_frequency_loss.py, vgg.py, discriminator.py
→ Generator network outputs synthesized slices
→ Discriminator network for adversarial training

D. Training & Optimization (orange)
- main.py: orchestrates training loop
- Loads config & opt JSON
- Instantiates DataLoader, model, losses, optimizer
- For each batch: forward pass → compute each loss → backward → optimizer.step()
- Writes checkpoints via train.sh wrapper and optim.py
- optim.py: builds Adam optimizers for generator & discriminator
- train.sh/test.sh: bash scripts that launch main.py/test.py with appropriate flags

- test.py: loads a checkpoint, runs inference on testset, computes PSNR/SSIM via util_evaluation.py
- experiments/i3net/...: folder hierarchy storing .pth checkpoints for different ×2/×4/×6 upsampling settings
- plots or metrics written to disk

##### Architectural patterns & design principles
- Modular separation: data_prepare, data­loading, model_zoo, losses
- Configurable via JSON + Python config
- Training loop decoupled from model/loss definitions
- Plugin-style selection: select_model.py & select_loss.py

[ Raw Data ] → [ Data Preparation ] → [ DataLoader / Config ] → [ Model + Loss Modules ] → [ Training Loop / Optimizer ] → [ Checkpoints & Evaluation ]
e.g., raw volumes → split → slices → DataLoader → model → loss → optimizer → checkpoint
- Data: green
- Config/Loading: cyan
- Model/Loss: blue/yellow
- Training: orange
- Storage: gray

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Acquisition & Preparation
    subgraph "Data Acquisition & Preparation"
        raw["Raw Datasets\nMedical Decathlon, IXI MR"]:::data
        step1["step1_split.py"]:::data
        testpt["test_set.pt"]:::data
        step2["step2_save_slice.py"]:::data
        sliceOut["2D Slice Outputs"]:::data
    end

    %% Data Loading & Configuration
    subgraph "Data Loading & Configuration"
        config["config.py"]:::config
        opt["i3net.json"]:::config
        dataMod["data.py"]:::config
        utilMod["util.py"]:::config
        selectModel["select_model.py"]:::config
        selectLoss["select_loss.py"]:::config
    end

    %% Model Definition
    subgraph "Model Definition (Generator & Discriminator)"
        basic["basic_model.py"]:::model
        dct["dct_util.py"]:::model
        win["utils_win.py"]:::model
        adv["adversarial.py"]:::loss
        contrast["contrastive_loss.py"]:::loss
        discr["discriminator.py"]:::loss
        edge["edge_loss.py"]:::loss
        ffl["focal_frequency_loss.py"]:::loss
        vgg["vgg.py"]:::loss
    end

    %% Training & Optimization
    subgraph "Training & Optimization"
        main["main.py"]:::train
        optim["optim.py"]:::train
        trainsh["train.sh"]:::train
    end

    %% Evaluation & Experiments Storage
    subgraph "Evaluation & Experiments Storage"
        test["test.py"]:::eval
        utilEval["util_evaluation.py"]:::eval
        exp2["Colon_x2 (.pth)"]:::exp
        exp4["Colon_x4 (.pth)"]:::exp
        exp6["Colon_x6 (.pth)"]:::exp
    end

    %% Data Flow
    raw --> step1 --> testpt
    step1 --> step2 --> sliceOut
    sliceOut --> dataMod
    config --> main
    opt --> main
    dataMod --> main
    utilMod --> main
    selectModel --> main
    selectLoss --> main
    main --> basic
    main --> adv
    main --> contrast
    main --> discr
    main --> edge
    main --> ffl
    main --> vgg
    basic --> main
    dct --> basic
    win --> basic
    optim --> main
    trainsh --> main
    main --> exp2
    main --> exp4
    main --> exp6
    exp2 --> test
    exp4 --> test
    exp6 --> test
    test --> utilEval

    %% Click Events
    click step1 "https://github.com/eeeric-code/i3net/blob/master/data_prepare/step1_split.py"
    click step2 "https://github.com/eeeric-code/i3net/blob/master/data_prepare/step2_save_slice.py"
    click testpt "https://github.com/eeeric-code/i3net/blob/master/data_prepare/test_set.pt"
    click config "https://github.com/eeeric-code/i3net/blob/master/config.py"
    click opt "https://github.com/eeeric-code/i3net/blob/master/opt/i3net.json"
    click dataMod "https://github.com/eeeric-code/i3net/blob/master/data.py"
    click utilMod "https://github.com/eeeric-code/i3net/blob/master/util.py"
    click selectModel "https://github.com/eeeric-code/i3net/blob/master/select_model.py"
    click selectLoss "https://github.com/eeeric-code/i3net/blob/master/select_loss.py"
    click basic "https://github.com/eeeric-code/i3net/blob/master/model_zoo/i3net/basic_model.py"
    click dct "https://github.com/eeeric-code/i3net/blob/master/model_zoo/i3net/dct_util.py"
    click win "https://github.com/eeeric-code/i3net/blob/master/model_zoo/i3net/utils_win.py"
    click adv "https://github.com/eeeric-code/i3net/blob/master/losses/adversarial.py"
    click contrast "https://github.com/eeeric-code/i3net/blob/master/losses/contrastive_loss.py"
    click discr "https://github.com/eeeric-code/i3net/blob/master/losses/discriminator.py"
    click edge "https://github.com/eeeric-code/i3net/blob/master/losses/edge_loss.py"
    click ffl "https://github.com/eeeric-code/i3net/blob/master/losses/focal_frequency_loss.py"
    click vgg "https://github.com/eeeric-code/i3net/blob/master/losses/vgg.py"
    click main "https://github.com/eeeric-code/i3net/blob/master/main.py"
    click optim "https://github.com/eeeric-code/i3net/blob/master/optim.py"
    click trainsh "https://github.com/eeeric-code/i3net/blob/master/train.sh"
    click test "https://github.com/eeeric-code/i3net/blob/master/test.py"
    click utilEval "https://github.com/eeeric-code/i3net/blob/master/util_evaluation.py"
    click exp2 "https://github.com/eeeric-code/i3net/tree/master/experiments/i3net/Colon_x2/pth"
    click exp4 "https://github.com/eeeric-code/i3net/tree/master/experiments/i3net/Colon_x4/pth"
    click exp6 "https://github.com/eeeric-code/i3net/tree/master/experiments/i3net/Colon_x6/pth"

    %% Styles
    classDef data fill:#ccffcc,stroke:#2d572c,color:#2d572c;
    classDef config fill:#ccffff,stroke:#2d7f7f,color:#2d7f7f;
    classDef model fill:#cce5ff,stroke:#265a88,color:#265a88;
    classDef loss fill:#fff5cc,stroke:#886f26,color:#886f26;
    classDef train fill:#ffd9b3,stroke:#b26b00,color:#b26b00;
    classDef eval fill:#e0e0e0,stroke:#7f7f7f,color:#7f7f7f;
    classDef exp fill:#d9d9d9,stroke:#595959,color:#595959;
```
