An end-to-end Deep Learning pipeline for brain tumor classification and segmentation on MRI scans, built using the BRISC 2025 dataset.
The system first classifies an MRI scan into one of four categories:
gliomameningiomapituitaryno_tumor
When a tumor is detected, the pipeline performs tumor segmentation to identify the affected region, followed by visual localization using bounding boxes, convex hulls, centroids, and an overlay visualization.
The project includes a Streamlit web application, FastAPI REST API, and Docker support, making it suitable for local demonstrations and portfolio deployment.
⚠️ Disclaimer: This project is a research and portfolio demonstration. It is not a certified medical device and must not be used for real clinical diagnosis or treatment decisions. Any clinical use would require appropriate validation and review by qualified medical professionals.
The system follows a two-stage workflow:
MRI Image
│
▼
┌─────────────────────┐
│ Tumor Classification│
└──────────┬──────────┘
│
Tumor detected?
│ │
No Yes
│ │
▼ ▼
No Tumor Segmentation
│
▼
Tumor Localization
│
▼
Visual Analysis
Segmentation is executed only when the classification model predicts a tumor.
- ResNet34 backbone
- Adapted for single-channel grayscale MRI images
- Four-class classification:
- Glioma
- Meningioma
- Pituitary
- No Tumor
- ResNet34 ImageNet-pretrained encoder
- UNet3+-style decoder
- Full-scale feature fusion between encoder and decoder stages
- Binary tumor segmentation
- Single-channel output
- Sigmoid activation for tumor probability
- Binary mask generation using a probability threshold
The segmentation result is further processed to generate:
- Tumor mask
- Tumor probability map
- Tumor coverage percentage
- Tumor confidence
- Bounding boxes
- Convex hull
- Region centroids
- Tumor overlay
- Combined visual report
- Downloadable PNG report
The project provides a presentation-ready Streamlit interface with:
- MRI image upload
- Classification results
- Confidence scores
- Per-class probabilities
- Segmentation results
- Tumor coverage
- Bounding boxes
- Visual overlays
- Model/device status
- Downloadable analysis report
REST API endpoints are provided for integrating the models with other applications:
/health/predict/classification/predict/segmentation/predict/full-analysis
Interactive API documentation is available through Swagger UI at /docs.
The project includes Docker configuration for running:
- Streamlit frontend
- FastAPI backend
Both services can share the same Docker image while using the trained model weights through a read-only volume.
This project requires an NVIDIA GPU with CUDA support for model inference.
The application does not fall back to CPU. If CUDA is unavailable while the application requests GPU execution, a RuntimeError is raised indicating that an NVIDIA GPU with CUDA support is required.
The device selection logic is:
NVIDIA GPU + CUDA available
│
▼
CUDA
│
│
CUDA unavailable
│
▼
RuntimeError
GPU required
For example:
RuntimeError:
CUDA is not available.
This model is intended to run on an NVIDIA GPU.
Please run the code on a machine with CUDA support.
Therefore, make sure that:
- An NVIDIA GPU is available.
- NVIDIA drivers are correctly installed.
- A CUDA-compatible PyTorch installation is used.
torch.cuda.is_available()returnsTrue.
You can verify CUDA availability with:
python -c "import torch; print(torch.cuda.is_available())"Expected output:
True
Note: CPU-only execution is intentionally not supported because the trained models and intended deployment environment are designed for NVIDIA GPU inference.
This project uses the BRISC 2025 dataset for brain MRI classification and segmentation.
The dataset contains brain MRI images associated with different tumor categories and segmentation annotations.
Dataset:
BRISC 2025 — Brain Tumor MRI Dataset
The models in this project were trained using preprocessing pipelines designed specifically for grayscale MRI images.
brain-tumor-classification-segmentation/
│
├── app/
│ ├── api/
│ │ ├── main.py
│ │ └── schemas.py
│ │
│ └── streamlit_app/
│ └── app.py
│
├── src/
│ ├── model.py
│ ├── transforms.py
│ ├── utils.py
│ └── visualization.py
│
├── docker/
│ ├── Dockerfile
│ └── docker-compose.yml
│
├── models/
│ ├── best_model_classif.pth
│ ├── best_model_seg.pth
│ └── README.md
│
├── requirements.txt
├── .dockerignore
├── .gitignore
└── README.md
| File / Directory | Description |
|---|---|
app/streamlit_app/app.py |
Streamlit web application |
app/api/main.py |
FastAPI REST API |
app/api/schemas.py |
Pydantic request/response schemas |
src/model.py |
Classification and segmentation architectures |
src/transforms.py |
Shared preprocessing and augmentation |
src/utils.py |
Model loading and inference utilities |
src/visualization.py |
Mask, bounding box, overlay and report utilities |
models/ |
Trained model checkpoints |
docker/ |
Docker configuration |
git clone <your-repo-url>
cd brain-tumor-classification-segmentationpython -m venv .venv
.venv\Scripts\activatepython -m venv .venv
source .venv/bin/activatepython -m pip install --upgrade pip
pip install -r requirements.txtPlace the trained model checkpoints inside the models/ directory:
models/
├── best_model_classif.pth
└── best_model_seg.pth
See models/README.md for the expected model architecture and checkpoint format.
streamlit run app/streamlit_app/app.pyOpen:
http://localhost:8501
Upload an MRI image and run the analysis.
The classification model uses ResNet34 as the backbone.
Because brain MRI images are grayscale, the first convolutional layer is adapted from three input channels to one input channel.
MRI Image
│
▼
Grayscale Input
│
▼
ResNet34
│
▼
Feature Extraction
│
▼
Fully Connected Layer
│
▼
4 Classes
Output classes:
0 → glioma
1 → meningioma
2 → no_tumor
3 → pituitary
The exact class-index mapping should match the training configuration used by the classification model.
The segmentation model combines:
- ResNet34 encoder
- UNet3+-style decoder
- Full-scale feature fusion
- Single-channel binary segmentation output
Architecture overview:
ResNet34 Encoder
│
┌────────────────┼────────────────┐
│ │ │
▼ ▼ ▼
Stage 1 Stage 2 Stage 3
│ │ │
└────────┬───────┴────────┬───────┘
│ │
▼ ▼
UNet3+ Decoder
│
▼
1-Channel Output
│
▼
Sigmoid
│
▼
Tumor Probability Map
│
▼
Binary Tumor Mask
The segmentation model produces a single-channel logit map:
(B, 1, H, W)
The output is converted to tumor probabilities using:
torch.sigmoid(output)A probability threshold is then used to generate the binary segmentation mask:
0 → background
1 → tumor
The project uses shared preprocessing utilities to keep training and inference consistent.
MRI Image
↓
Grayscale
↓
Resize
↓
Tensor Conversion
↓
Normalization
↓
Classification Model
MRI Image
↓
Grayscale
↓
Resize to 512 × 512
↓
Tensor Conversion
↓
Normalization
↓
Segmentation Model
Using the same preprocessing pipeline during training and inference helps prevent inconsistencies between model development and deployment.
streamlit run app/streamlit_app/app.pyThe application runs at:
http://localhost:8501
- Upload an MRI scan.
- Run the analysis.
- The classification model predicts the tumor class.
- If
no_tumoris predicted, segmentation is skipped. - If a tumor is detected, the segmentation model generates a tumor mask.
- The application calculates tumor coverage and confidence.
- Tumor regions are localized using bounding boxes and additional geometric analysis.
- A visual report is generated.
Start the API with:
uvicorn app.api.main:app --reload --port 8000API:
http://localhost:8000
Swagger documentation:
http://localhost:8000/docs
| Method | Endpoint | Description |
|---|---|---|
GET |
/health |
Service and model status |
POST |
/predict/classification |
Classify an MRI image |
POST |
/predict/segmentation |
Generate a tumor segmentation |
POST |
/predict/full-analysis |
Run classification followed by conditional segmentation |
curl -X POST http://localhost:8000/predict/full-analysis \
-F "file=@sample_scan.png"If a required model is unavailable, the API returns an appropriate error response instead of failing with an unhandled exception.
The project supports running both services with Docker Compose.
From the project root:
docker compose -f docker/docker-compose.yml up --buildServices:
Streamlit → http://localhost:8501
FastAPI → http://localhost:8000
Swagger → http://localhost:8000/docs
docker build -f docker/Dockerfile -t brain-mri-app .Then:
docker run \
-p 8501:8501 \
-v "$(pwd)/models:/workspace/models:ro" \
brain-mri-appOn Windows PowerShell, the volume syntax may need to be adjusted according to the local Docker setup.
The complete inference pipeline is:
┌──────────────┐
│ MRI Image │
└──────┬───────┘
│
▼
┌──────────────────┐
│ Classification │
│ ResNet34 │
└────────┬─────────┘
│
┌─────────┴─────────┐
│ │
No Tumor Tumor
│ │
▼ ▼
Final Result ┌──────────────┐
│ Segmentation │
│ ResNet34 + │
│ UNet3+ │
└──────┬───────┘
│
▼
Tumor Mask
│
┌──────────┼──────────┐
│ │ │
▼ ▼ ▼
BBox Overlay Geometry
│ │ │
└──────────┼──────────┘
│
▼
Final Report
For a tumor-positive MRI, the system can provide:
Predicted Class: Glioma
Confidence: 94.2%
Tumor Coverage: 8.37%
Segmentation Confidence: 91.6%
Original MRI
+
Tumor Mask
+
Bounding Box
+
Tumor Overlay
+
Geometric Localization
The final visualization can be exported as a PNG report.
The applications are designed to remain usable even when model weights are unavailable.
If a checkpoint is missing:
Model not loaded
is displayed instead of causing the entire application to crash.
This makes it possible to review the UI and application structure independently from the trained checkpoints.
The application automatically detects CUDA:
torch.cuda.is_available()If CUDA is available:
Device → CUDA
Otherwise:
Device → CPU
This allows the project to run across different environments without requiring manual device configuration.
- Python
- PyTorch
- Torchvision
- ResNet34
- UNet3+-style architecture
- OpenCV
- NumPy
- Pillow
- FastAPI
- Pydantic
- Uvicorn
- Streamlit
- Docker
- Docker Compose
- BRISC 2025
Hossein Heydari
Computer Engineering (Software) · AI Builders Iran
GitHub: @HosseinHeydari2004
Seyede Reyhane Khorashadizade
GitHub: @Seyede-Reyhane-Khorashadizade
This project is intended exclusively for research, education, and portfolio demonstration.
The predictions, segmentation masks, confidence values, and visualizations generated by this system should not be considered medical advice or a clinical diagnosis.
The system has not been certified as a medical device and should not be used to make decisions regarding patient diagnosis, treatment, or medical care.
