# pbaniket/braintumor-segmentation architecture

> Architecture diagram of the GitHub repository pbaniket/braintumor-segmentation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pbaniket/braintumor-segmentation
- Repository: https://github.com/pbaniket/braintumor-segmentation

## Overview

1. **What this repo is**
   - A small research/project codebase for **brain tumor image segmentation** using a **U-Net** model in PyTorch.
   - It is not a multi-service application; the architecture is mostly **offline training + local inference CLI** around a saved segmentation model.

2. **Primary execution paths**
   - There are two main flows:
     - **Training/experimentation**: notebook + `bts/` package + dataset setup scripts.
     - **Inference/API-style usage**: `api.py` loads a trained checkpoint and generates masks for one image or a folder of images.

3. **Inference boundary**
   - `api.py` is the top-level entry point for end users.
   - It accepts either a **single file** or a **folder**, then writes predicted mask images to an optional output path.
   - The presence of `saved_models/UNet-[16, 32, 64, 128, 256].pt` indicates inference depends on a **pretrained checkpoint on disk**, not on a remote model service.

4. **Model subsystem**
   - `bts/model.py` contains the **U-Net architecture** itself.
   - This is the core segmentation engine: it takes a 512×512 grayscale medical image and outputs a pixel-wise tumor mask.
   - The README’s architecture image and the checkpoint naming strongly suggest a standard encoder-decoder with skip connections.

5. **Training support code**
   - `bts/loss.py` defines the segmentation loss used during optimization.
   - `bts/classifier.py` likely acts as the training/evaluation wrapper around the model, loss, and metric computation.
   - The repo’s outputs show a focus on **Dice score**, so evaluation is centered on overlap quality between predicted and ground-truth masks.

6. **Dataset and augmentation layer**
   - `bts/dataset.py` is the data-loading boundary between raw files and the model.
   - It handles the **brain MRI images and masks**, likely returning paired image/mask tensors.
   - Augmentation is part of this layer: **horizontal flip, vertical flip, and random rotation** via `torchvision`, with randomized order/probability.

7. **Data acquisition and preparation pipeline**
   - `setup_scripts/download_dataset.py`, `unzip_dataset.py`, and `extract_images.py` form a small preprocessing pipeline.
   - The raw source is the external **Jun Cheng / Figshare brain tumor dataset**.
   - The scripts convert the downloaded archive into local image files that the dataset loader can consume.

8. **Artifacts and persistence**
   - `saved_models/` stores trained weights for reuse.
   - `logs/` stores training-time observability:
     - TensorBoard event files
     - textual training output
   - `images/API/` and `images/README/` are documentation/output artifacts showing original images, masks, and predictions.

9. **Experimentation environment**
   - `Tumor Segmentation.ipynb` is the exploratory/training notebook.
   - This suggests the project was developed interactively, with the notebook likely used for training runs, visual inspection, and plotting results.

10. **Monitoring and visualization**
   - TensorBoard is used to track training progress, especially **learning rate and loss over epochs**.
   - `bts/plot.py` and the saved images indicate a second visualization path via **Matplotlib** for offline graphs and result comparison.

11. **End-to-end data flow**
   - External dataset → setup scripts → local image/mask files → `bts.dataset` augmentation/loading → `bts.model` U-Net → loss/metrics during training → checkpoint saved to `saved_models/` → `api.py` loads checkpoint → predicted masks written to disk.

12. **Important architectural boundary**
   - The repo is fundamentally **file-system driven**: dataset files, checkpoints, logs, and outputs all live locally.
   - Runtime dependencies that materially shape the design are **PyTorch**, **Torchvision**, **TensorBoard**, **Matplotlib**, and **Jupyter**.

Main entry points: [`bts/classifier.py`](https://github.com/pbaniket/braintumor-segmentation/blob/main/bts/classifier.py) (Trainer), [`bts/__init__.py`](https://github.com/pbaniket/braintumor-segmentation/blob/main/bts/__init__.py) (BTS package), [`api.py`](https://github.com/pbaniket/braintumor-segmentation/blob/main/api.py) (API), [`bts/dataset.py`](https://github.com/pbaniket/braintumor-segmentation/blob/main/bts/dataset.py) (Dataset)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_api["API<br/>inference CLI<br/>[api.py]"]
  node_notebook["Notebook<br/>exploration"]
  node_requirements["Dependencies<br/>python deps<br/>[requirements.txt]"]
  node_readme["README<br/>project guide<br/>[README.md]"]
end

subgraph group_core["Core pipeline"]
  node_model["U-Net<br/>segmentation model<br/>[model.py]"]
  node_classifier["Trainer<br/>train/eval wrapper<br/>[classifier.py]"]
  node_dataset[("Dataset<br/>data loader<br/>[dataset.py]")]
  node_loss["Loss<br/>[loss.py]"]
  node_plot["Plots<br/>visualization<br/>[plot.py]"]
  node_pkg["BTS package<br/>python package<br/>[__init__.py]"]
end

subgraph group_assets["Local assets"]
  node_weights[("Checkpoint<br/>saved model")]
  node_logs["Logs"]
  node_apiout["API images<br/>example outputs"]
  node_readmeimg["README images<br/>documentation assets"]
end

subgraph group_prep["Dataset prep"]
  node_download["Download<br/>dataset fetch"]
  node_unzip["Unzip<br/>archive extract<br/>[unzip_dataset.py]"]
  node_extract["Extract images<br/>dataset convert<br/>[extract_images.py]"]
end

node_readme -->|"describes usage"| node_api
node_readme -->|"describes training"| node_notebook
node_readme -->|"documents data flow"| node_dataset
node_readme -->|"documents architecture"| node_model
node_api -->|"loads"| node_weights
node_api -->|"runs inference with"| node_model
node_api -->|"writes outputs"| node_apiout
node_notebook -->|"trains via"| node_classifier
node_classifier -->|"optimizes"| node_model
node_classifier -->|"uses"| node_loss
node_classifier -->|"consumes"| node_dataset
node_dataset -->|"depends on"| node_extract
node_download -->|"feeds"| node_unzip
node_unzip -->|"feeds"| node_extract
node_extract -->|"prepares inputs for"| node_dataset
node_classifier -->|"emits"| node_logs
node_classifier -->|"visualizes with"| node_plot
node_classifier -->|"saves"| node_weights
node_plot -->|"renders into"| node_readmeimg
node_pkg -.->|"contains"| node_model
node_pkg -.->|"contains"| node_dataset
node_pkg -.->|"contains"| node_classifier
node_pkg -.->|"contains"| node_loss
node_pkg -.->|"contains"| node_plot
node_requirements -.->|"supports"| node_api
node_requirements -.->|"supports"| node_notebook

click node_api "https://github.com/pbaniket/braintumor-segmentation/blob/main/api.py"
click node_notebook "https://github.com/pbaniket/braintumor-segmentation/blob/main/Tumor Segmentation.ipynb"
click node_model "https://github.com/pbaniket/braintumor-segmentation/blob/main/bts/model.py"
click node_classifier "https://github.com/pbaniket/braintumor-segmentation/blob/main/bts/classifier.py"
click node_dataset "https://github.com/pbaniket/braintumor-segmentation/blob/main/bts/dataset.py"
click node_loss "https://github.com/pbaniket/braintumor-segmentation/blob/main/bts/loss.py"
click node_plot "https://github.com/pbaniket/braintumor-segmentation/blob/main/bts/plot.py"
click node_pkg "https://github.com/pbaniket/braintumor-segmentation/blob/main/bts/__init__.py"
click node_download "https://github.com/pbaniket/braintumor-segmentation/blob/main/setup_scripts/download_dataset.py"
click node_unzip "https://github.com/pbaniket/braintumor-segmentation/blob/main/setup_scripts/unzip_dataset.py"
click node_extract "https://github.com/pbaniket/braintumor-segmentation/blob/main/setup_scripts/extract_images.py"
click node_weights "https://github.com/pbaniket/braintumor-segmentation/blob/main/saved_models/UNet-[16, 32, 64, 128, 256].pt"
click node_logs "https://github.com/pbaniket/braintumor-segmentation/tree/main/logs/05-47-51_PM_on_May_20,_2019"
click node_apiout "https://github.com/pbaniket/braintumor-segmentation/tree/main/images/API"
click node_readmeimg "https://github.com/pbaniket/braintumor-segmentation/tree/main/images/README"
click node_requirements "https://github.com/pbaniket/braintumor-segmentation/blob/main/requirements.txt"
click node_readme "https://github.com/pbaniket/braintumor-segmentation/blob/main/README.md"

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_api,node_notebook,node_requirements,node_readme toneBlue
class node_model,node_classifier,node_dataset,node_loss,node_plot,node_pkg toneAmber
class node_weights,node_logs,node_apiout,node_readmeimg toneMint
class node_download,node_unzip,node_extract toneRose
```

## Components

### Entry points

User-facing inference and exploratory training entry points.

- [API](https://github.com/pbaniket/braintumor-segmentation/blob/main/api.py): inference CLI · Loads a trained checkpoint and predicts masks for a single image or a folder. · `api.py`
- [Notebook](https://github.com/pbaniket/braintumor-segmentation/blob/HEAD/Tumor%20Segmentation.ipynb): exploration · Interactive training and experimentation environment. · `Tumor Segmentation.ipynb`
- [Dependencies](https://github.com/pbaniket/braintumor-segmentation/blob/main/requirements.txt): python deps · Pinned runtime dependencies for PyTorch, Torchvision, TensorBoard, Matplotlib, and Jupyter. · `requirements.txt`
- [README](https://github.com/pbaniket/braintumor-segmentation/blob/main/README.md): project guide · Describes the dataset, model, training flow, and usage. · `README.md`

### Core pipeline

Modeling, data loading, training, loss, and plotting components.

- [U-Net](https://github.com/pbaniket/braintumor-segmentation/blob/main/bts/model.py): segmentation model · Encoder-decoder segmentation network with skip connections. · `bts/model.py`
- [Trainer](https://github.com/pbaniket/braintumor-segmentation/blob/main/bts/classifier.py): train/eval wrapper · Coordinates model execution, optimization, and metric reporting. · `bts/classifier.py`
- [Dataset](https://github.com/pbaniket/braintumor-segmentation/blob/main/bts/dataset.py): data loader · Loads paired brain MRI images and masks, including augmentation. · `bts/dataset.py`
- [Loss](https://github.com/pbaniket/braintumor-segmentation/blob/main/bts/loss.py): segmentation loss · Defines the optimization objective used during training. · `bts/loss.py`
- [Plots](https://github.com/pbaniket/braintumor-segmentation/blob/main/bts/plot.py): visualization · Creates training and result plots for offline analysis. · `bts/plot.py`
- [BTS package](https://github.com/pbaniket/braintumor-segmentation/blob/main/bts/__init__.py): python package · Package boundary that groups the model, data, loss, and training code. · `bts/__init__.py`

### Local assets

On-disk datasets, checkpoints, logs, and example outputs.

- [Checkpoint](https://github.com/pbaniket/braintumor-segmentation/blob/HEAD/saved_models/UNet-%5B16%2C%2032%2C%2064%2C%20128%2C%20256%5D.pt): saved model · Trained U-Net weights loaded for inference. · `saved_models/UNet-[16, 32, 64, 128, 256].pt`
- [Logs](https://github.com/pbaniket/braintumor-segmentation/tree/main/logs/05-47-51_PM_on_May_20,_2019): training logs · TensorBoard events and textual training output. · `logs/05-47-51_PM_on_May_20,_2019`
- [API images](https://github.com/pbaniket/braintumor-segmentation/tree/main/images/API): example outputs · Example originals, masks, and predictions generated by the API flow. · `images/API`
- [README images](https://github.com/pbaniket/braintumor-segmentation/tree/main/images/README): documentation assets · Figures used to document model behavior and results. · `images/README`

### Dataset prep

Scripts that fetch and convert the external dataset into local files.

- [Download](https://github.com/pbaniket/braintumor-segmentation/blob/main/setup_scripts/download_dataset.py): dataset fetch · Downloads the external brain tumor dataset archive. · `setup_scripts/download_dataset.py`
- [Unzip](https://github.com/pbaniket/braintumor-segmentation/blob/main/setup_scripts/unzip_dataset.py): archive extract · Extracts the downloaded dataset archive locally. · `setup_scripts/unzip_dataset.py`
- [Extract images](https://github.com/pbaniket/braintumor-segmentation/blob/main/setup_scripts/extract_images.py): dataset convert · Converts archive contents into image files consumable by the loader. · `setup_scripts/extract_images.py`

## Connections

- README → API: describes usage · Documents inference entry-point behavior.
- README → Notebook: describes training · Covers exploratory notebook-based experimentation.
- README → Dataset: documents data flow · Explains paired image/mask loading.
- README → U-Net: documents architecture · Introduces the U-Net segmentation model.
- API → Checkpoint: loads · Inference depends on a local checkpoint file.
- API → U-Net: runs inference with · Uses the U-Net to generate predicted masks.
- API → API images: writes outputs · Saves original, ground-truth, and predicted masks to disk.
- Notebook → Trainer: trains via · Notebook likely orchestrates experiments through the training wrapper.
- Trainer → U-Net: optimizes · Wraps the segmentation network during training.
- Trainer → Loss: uses · Computes the training objective.
- Trainer → Dataset: consumes · Reads batched image and mask tensors.
- Dataset → Extract images: depends on · Consumes locally prepared image files.
- Download → Unzip: feeds · Downloaded archive is extracted next.
- Unzip → Extract images: feeds · Extracted dataset contents are converted into images.
- Extract images → Dataset: prepares inputs for · Produces files that the dataset loader can read.
- Trainer → Logs: emits · Writes TensorBoard events and textual training output.
- Trainer → Plots: visualizes with · Generates training and result plots.
- Trainer → Checkpoint: saves · Persists trained checkpoints for reuse.
- Plots → README images: renders into · Produces figures used in documentation and results review.
- BTS package → U-Net: contains · Package boundary includes the model module.
- BTS package → Dataset: contains · Package boundary includes the dataset module.
- BTS package → Trainer: contains · Package boundary includes the training wrapper.
- BTS package → Loss: contains · Package boundary includes the loss module.
- BTS package → Plots: contains · Package boundary includes plotting helpers.
- Dependencies → API: supports · Declares runtime dependencies needed by the CLI.
- Dependencies → Notebook: supports · Declares notebook and training dependencies.
