How pbaniket/braintumor-segmentation works
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: classifier.py Trainer · __init__.py BTS package · api.py API · dataset.py Dataset
Components 17
Entry points
User-facing inference and exploratory training entry points.
- API · Loads a trained checkpoint and predicts masks for a single image or a folder.
api.py - Notebook · Interactive training and experimentation environment.
Tumor Segmentation.ipynb - Dependencies · Pinned runtime dependencies for PyTorch, Torchvision, TensorBoard, Matplotlib, and Jupyter.
requirements.txt - README · Describes the dataset, model, training flow, and usage.
README.md
Core pipeline
Modeling, data loading, training, loss, and plotting components.
- U-Net · Encoder-decoder segmentation network with skip connections.
bts/model.py - Trainer · Coordinates model execution, optimization, and metric reporting.
bts/classifier.py - Dataset · Loads paired brain MRI images and masks, including augmentation.
bts/dataset.py - Loss · Defines the optimization objective used during training.
bts/loss.py - Plots · Creates training and result plots for offline analysis.
bts/plot.py - BTS 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 · Trained U-Net weights loaded for inference.
saved_models/UNet-[16, 32, 64, 128, 256].pt - Logs · TensorBoard events and textual training output.
logs/05-47-51_PM_on_May_20,_2019 - API images · Example originals, masks, and predictions generated by the API flow.
images/API - README images · Figures used to document model behavior and results.
images/README
Dataset prep
Scripts that fetch and convert the external dataset into local files.
- Download · Downloads the external brain tumor dataset archive.
setup_scripts/download_dataset.py - Unzip · Extracts the downloaded dataset archive locally.
setup_scripts/unzip_dataset.py - Extract images · Converts archive contents into image files consumable by the loader.
setup_scripts/extract_images.py
Connections 26
- 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.