# drstringg/befunet architecture

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

- Interactive diagram: https://gitdiagram.com/drstringg/befunet
- Repository: https://github.com/drstringg/befunet

## Overview

##### Project type and purpose
- This is a research‐oriented deep learning project for medical image segmentation using a hybrid CNN-Transformer architecture (BEFUnet).
- The primary use case is training and testing on the Synapse dataset to produce high-quality organ/tissue segmentation masks.

##### File structure
- Top-level scripts:
- Colab_BEFUnet.ipynb – end-to-end notebook for data prep, training, and evaluation.
- train.py / test.py – CLI entry points for training and evaluation.
- trainer.py – orchestrates the training loop, logging, checkpointing, metrics.
- utils.py – dataset utilities, metrics calculation, visualization helpers.
- configs/ – Python config file(s) holding hyperparameters and paths.
- datasets/ – PyTorch Dataset class for loading Synapse data.
- lists/ – text files enumerating train/test volume lists.
- models/ – network definition
- BEFUnet.py – high-level model class combining encoder & decoder
- Encoder.py – CNN + transformer blocks (borrowed/modified from Swin Transformer)
- Decoder.py – up-sampling and fusion modules
- pidinet.py, convert_pidinet.py – PiDiNet edge detection integration
- ops.py – custom operations (e.g., attention, convolution wrappers)
- config.py – model-specific hyperparameters or layer configurations
- requirements.txt – core dependencies (PyTorch, torchvision, numpy, etc.)

##### Key insights from README
- Highlights a modular architecture: hybrid CNN + transformer encoder feeding into a decoder.
- Acknowledges reliance on two external codebases: Swin Transformer (for transformer blocks) and PiDiNet (for edge prior).
- Primary workflow: data prep → train → test/evaluate.

a. Main components
1. Data Layer
– Synapse dataset source (NPZ/H5 volumes)
– Data loader + pre-processing (Dataset class)
2. Configuration Layer
– Global configs (configs/BEFUnet_configs.py)
– Model hyperparameters (models/config.py)
3. Model Layer
– Encoder (CNN + Transformer blocks)
– Edge Prior Network (PiDiNet integration)
– Decoder (upsampling, skip-connections, fusion)
4. Training Orchestration
– Trainer (trainer.py)
– Loss functions, optimizer, scheduler
– Checkpointing, logging, metrics
5. Inference/Evaluation
– test.py
– Metrics computation (Dice, IoU) & NIfTI export
6. External Services / Libraries
– PyTorch & CUDA
– Swin Transformer components
– PiDiNet code

b. Relationships & interactions
- Data Layer → Configuration Layer (paths & hyperparameters)
- Data Layer → Model Layer (inputs into encoder)
- Model Layer ↔ Trainer (forward/backward passes)
- Trainer → Configuration Layer (reads hyperparameters)
- Trainer → Filesystem (checkpoints, logs)
- test.py → Model Layer (loads weights) → Data Layer → Outputs (metrics, NIfTI)

c. Architectural patterns & design principles
- Modular separation: data, config, model, training, evaluation all live in dedicated modules.
- Clear pipeline: sequential flow from data ingestion to model computation to output generation.
- Reusable components: encoder and decoder can be swapped or extended.
- Config‐driven design: parameters and paths externalized to config files.

d. Key technologies/frameworks
- PyTorch (core DL framework)
- NumPy, h5py (data handling)
- Swin Transformer blocks (external)
- PiDiNet edge prior (external)
- Hydra or custom Python configs (for hyperparameter management)

##### Final recommendations
- Maintain clarity: avoid clutter by grouping related submodules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data & Config Layer
    subgraph "Data Layer" 
        direction TB
        DataLoader["Data Loader"]:::data
        ListsAll["all.lst"]:::data
        ListsTrain["train.txt"]:::data
        ListsTest["test_vol.txt"]:::data
    end

    subgraph "Configuration Layer"
        direction TB
        GlobalConfig["BEFUnet_configs.py"]:::config
        ModelConfig["models/config.py"]:::config
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        BEFUnet["BEFUnet"]:::model
        Encoder["Encoder"]:::model
        Decoder["Decoder"]:::model
        EdgePrior["PiDiNet Integration"]:::model
        Ops["Custom Ops"]:::model
    end

    %% Training Orchestration
    subgraph "Training Orchestration"
        direction TB
        TrainScript["train.py"]:::orchestration
        Trainer["trainer.py"]:::orchestration
        Utils["utils.py"]:::orchestration
    end

    %% Inference / Evaluation
    subgraph "Inference/Evaluation"
        direction TB
        TestScript["test.py"]:::orchestration
        Notebook["Colab_BEFUnet.ipynb"]:::orchestration
    end

    %% External Libraries
    subgraph "External Services"
        direction TB
        PyTorch["PyTorch & CUDA"]:::external
        Swin["Swin Transformer"]:::external
        PiDiNetExt["PiDiNet Code"]:::external
    end

    %% Connections
    ListsAll -->|volume lists| DataLoader
    ListsTrain -->|volume lists| DataLoader
    ListsTest -->|volume lists| DataLoader

    DataLoader -->|batches| Encoder
    GlobalConfig -->|paths & hyperparams| Encoder
    ModelConfig -->|model params| Encoder

    Encoder -->|features| BEFUnet
    EdgePrior -->|edge priors| BEFUnet
    Ops -->|ops support| BEFUnet
    BEFUnet -->|latent maps| Decoder

    Encoder -->|transformer blocks| Swin
    EdgePrior -->|edge extraction| PiDiNetExt

    BEFUnet -->|model| Trainer
    Decoder -->|segmentation| Trainer
    GlobalConfig -->|training params| Trainer
    Utils -->|preproc & metrics| Trainer
    PyTorch -->|compute| Trainer

    Trainer -->|checkpoints & logs| TestScript
    Trainer -->|checkpoints & logs| Notebook

    TestScript -->|load model| BEFUnet
    TestScript -->|eval batches| DataLoader
    TestScript -->|metrics & masks| Utils

    Notebook -->|demo workflow| DataLoader
    Notebook -->|demo workflow| Trainer
    Notebook -->|demo workflow| TestScript

    %% Click events
    click DataLoader "https://github.com/drstringg/befunet/blob/main/datasets/dataset_synapse.py"
    click ListsAll "https://github.com/drstringg/befunet/blob/main/lists/lists_Synapse/all.lst"
    click ListsTrain "https://github.com/drstringg/befunet/blob/main/lists/lists_Synapse/train.txt"
    click ListsTest "https://github.com/drstringg/befunet/blob/main/lists/lists_Synapse/test_vol.txt"
    click GlobalConfig "https://github.com/drstringg/befunet/blob/main/configs/BEFUnet_configs.py"
    click ModelConfig "https://github.com/drstringg/befunet/blob/main/models/config.py"
    click Encoder "https://github.com/drstringg/befunet/blob/main/models/Encoder.py"
    click Decoder "https://github.com/drstringg/befunet/blob/main/models/Decoder.py"
    click BEFUnet "https://github.com/drstringg/befunet/blob/main/models/BEFUnet.py"
    click EdgePrior "https://github.com/drstringg/befunet/blob/main/models/pidinet.py"
    click EdgePrior "https://github.com/drstringg/befunet/blob/main/models/convert_pidinet.py"
    click Ops "https://github.com/drstringg/befunet/blob/main/models/ops.py"
    click Trainer "https://github.com/drstringg/befunet/blob/main/trainer.py"
    click TrainScript "https://github.com/drstringg/befunet/blob/main/train.py"
    click Utils "https://github.com/drstringg/befunet/blob/main/utils.py"
    click TestScript "https://github.com/drstringg/befunet/blob/main/test.py"
    click Notebook "https://github.com/drstringg/befunet/blob/main/Colab_BEFUnet.ipynb"

    %% Styles
    classDef data fill:#cfe2f3,stroke:#6fa8dc
    classDef config fill:#d9ead3,stroke:#6aa84f
    classDef model fill:#d0e0e3,stroke:#76a5af
    classDef orchestration fill:#f9cb9c,stroke:#e69138
    classDef external fill:#e0d9f0,stroke:#8e7cc3
```
