SDLC-Corp/Medical-Imaging-Brain-tumor-analysis

<div align="center">

🧠 Brain Tumor Detection — SDLC Corp

    

An SDLC Corp deep-learning web app that classifies brain MRI scans into four categories (glioma · meningioma · no-tumor · pituitary). Two models run entirely in the browser via ONNX Runtime Web — a ViT for the prediction (~97% on a held-out test set) and a ResNet50 for grad-free explainability — deployable as a free Hugging Face Static Space.

</div>

⚠️ Medical Disclaimer

This tool is for educational and research purposes only. It is not a substitute for professional medical diagnosis. Always consult a qualified radiologist or medical professional for clinical decisions.

📌 Table of Contents

• —About the Project
• —How It Works
• —Advanced ML features
• —Classes & data
• —Model Architecture
• —Model Performance
• —Project Structure
• —Getting Started
• —Tech Stack
• —Credits & Licenses

🔬 About the Project

Brain tumors are among the most critical conditions in medicine — accurate classification helps guide treatment decisions. This SDLC Corp project packages a fine-tuned ResNet50 MRI classifier into a modern, privacy-preserving web app that runs the model entirely in the user's browser (no server, no upload) and layers on real explainability and reliability tooling.

What this project covers:

• —Exporting a PyTorch ResNet50 to ONNX (fp16) for in-browser inference via ONNX Runtime Web
• —Class Activation Mapping — instant, grad-free, per-class explainability heatmaps
• —Test-time augmentation, predictive-entropy uncertainty, and embedding-based out-of-distribution detection
• —Content-based retrieval of the most similar reference scans
• —One-command deployment to a free Hugging Face Static Space

⚙️ How It Works

User selects an MRI Scan (.jpg / .png)   ← stays in the browser
              │
              ├─────────────────────────────┬───────────────────────────────┐
              ▼                             ▼                                │
   ViT preprocessing                ResNet preprocessing                     │
   (resize 224, norm [-1,1])        (resize 256 → crop 224 → ImageNet)       │
              ▼                             ▼                                │
   ViT-base/16 (ONNX fp16)          ResNet50 (ONNX fp16, 2 outputs)          │
   → logits → softmax               → logits + last-conv feature maps        │
              │                             │                                │
              ▼                             ▼                                ▼
   Prediction + confidence     Grad-free Class Activation Map     GAP embedding →
   bars + uncertainty          (per-class, instant)               OOD + retrieval
              │
              ▼
  ┌──────────┬────────────┬──────────┬────────────┐
  │  Glioma  │ Meningioma │ No-tumor │ Pituitary  │
  └──────────┴────────────┴──────────┴────────────┘

🧪 Advanced ML features (all in-browser)

Beyond a single forward pass, the app runs a small suite of real inference-time ML techniques — entirely client-side, with negligible extra download:

Why OOD matters here: softmax is overconfident on garbage — feed the app pure noise and it will predict a tumor class at ~100% "confidence". The embedding-based OOD check catches exactly this case and warns the user, which softmax confidence alone never would.

These assets are produced by compute_stats.py (run after export_onnx.py).

📊 Classes & data

The classifier predicts four categories of T1-weighted brain MRI:

The underlying model weights were fine-tuned on a public Brain Tumor MRI image-classification dataset (the four-class glioma / meningioma / no-tumor / pituitary set). See Credits & Licenses for provenance.

⚠️ SDLC Corp has not independently re-benchmarked these third-party weights; accuracy on new data is not claimed here (see Model Performance).

🏗️ Model Architecture

The app runs two complementary models in the browser, each doing what it's best at:

                         ┌─────────────────────────────────────────┐
  MRI ─┬─ resize 224 ────►  ViT-base/16   (higher accuracy)         │
       │  norm [-1,1]     │  → prediction · confidence · uncertainty│  ← displayed
       │                  └─────────────────────────────────────────┘
       │                  ┌─────────────────────────────────────────┐
       └─ resize 256 ─────►  ResNet50  (GAP → Linear head)           │
          crop 224        │  → CAM heatmap (grad-free)               │  ← explain
          ImageNet norm   │  → 2048-d embedding → OOD + retrieval    │
                          └─────────────────────────────────────────┘

The ResNet is kept specifically because its global-average-pool → Linear head makes grad-free CAM possible (a ViT has no such head). Both are exported to ONNX float16 (export_onnx.py): ResNet 47 MB, ViT 172 MB — parity with their PyTorch sources ~1e-4 / 1e-6 (verify_pipeline.py). Each falls back to fp32 if a browser can't run fp16 in WASM.

📈 Model Performance

Measured with benchmark.py / benchmark_ensemble.py on a held-out test set of 1,311 labelled MRIs (the Kaggle "Brain Tumor MRI" Testing split; label order matches the models).

The app therefore uses the ViT for prediction and the ResNet50 for the CAM heatmap + feature embeddings (OOD / retrieval).

ViT per-class F1 (deployed model): glioma 0.967, meningioma 0.948, notumor 0.985, pituitary 0.980 — and glioma recall 0.963 (vs the ResNet's 0.713). Run python benchmark_ensemble.py for the full breakdown.

Read this honestly:

• —Averaging the two models is slightly worse than the ViT alone — the ResNet (86%) is too weak to help, so a naive ensemble drags the ViT down. The real win was switching the predictor to the ViT (+11 points; glioma recall 0.71 → 0.96).
• —This is in-distribution generalization; it assumes the checkpoints trained on the Training split and did not see this Testing split. If they overlapped, 97% is optimistic, and real-world accuracy on other scanners/institutions is lower.
• —The deployed fp16 ONNX models match their PyTorch sources (parity ~1e-4 / 1e-6).
• —Still not a medical device — even at 97% test accuracy, ~1 in 30 is wrong.

📁 Project Structure

BRAIN TUMOR DETECTION [END 2 END]/
│
│  ── Static Space (deployed, in-browser) ──────────────────────────
├── index.html                              # Space entry point (sdk: static)
├── style.css                               # UI styles
├── app.js                                  # onnxruntime-web inference + CAM + TTA + uncertainty + OOD + retrieval
├── cam_weights.json                        # classifier weights for in-browser CAM (generated)
├── reference.json                          # gallery feature embeddings for kNN retrieval (generated)
├── advanced.json                           # OOD threshold + uncertainty config (generated)
├── labels.json                             # labels + preprocessing config (generated)
├── 📂 model/
│   ├── vit.fp16.onnx                       # prediction model, ~172 MB  (git-lfs)
│   ├── vit.onnx                            # fp32 fallback, ~343 MB     (git-lfs)
│   ├── bt_resnet50.fp16.onnx               # CAM/embedding model, ~47 MB (git-lfs)
│   └── bt_resnet50.onnx                    # fp32 fallback, ~94 MB      (git-lfs)
├── 📂 examples/                            # example MRIs shown in the UI
│
│  ── Tooling & PyTorch reference ──────────────────────────────────
├── export_onnx.py                          # PyTorch → ONNX (fp32 + fp16) + labels.json + cam_weights.json
├── compute_stats.py                        # gallery embeddings + OOD threshold (reference.json, advanced.json)
├── benchmark.py                            # accuracy/F1/confusion matrix on a labelled held-out test set
├── benchmark_ensemble.py                   # compares ResNet vs ViT vs ensemble on the test set
├── verify_pipeline.py                      # checks browser preprocessing == PyTorch
├── app_gradio.py                           # full Gradio app w/ real Grad-CAM (local)
├── 📂 src/                                  # config · model · inference · gradcam
├── 📂 Brain-Tumor-Test-Images/             # source images copied into examples/
│
├── requirements.txt                        # deps for the Gradio reference app
├── requirements-export.txt                 # deps for export_onnx.py (one-time)
├── .gitattributes                          # git-lfs rules for *.onnx
├── .gitignore
└── README.md                               # you are here

🚀 Getting Started

1. Get the repository

git clone <your-sdlc-corp-repo-url>
cd brain-tumor-detection

2. Set up environment

python -m venv venv
source venv/bin/activate        # Linux / macOS
venv\Scripts\activate           # Windows

pip install -r requirements.txt

This project ships two front-ends that share the same model:

Option A — Run the static web app locally

First export the model to ONNX (one-time; needs the export deps):

pip install -r requirements-export.txt
python export_onnx.py          # downloads weights, writes model/*.onnx + labels.json + cam_weights.json
python compute_stats.py        # writes reference.json + advanced.json (embeddings + OOD threshold)

Then serve the folder as static files (any static server works):

python -m http.server 8000
# open http://localhost:8000

Upload an MRI scan → you get a prediction, per-class confidence bars, and an instant Class Activation Map (click any class to see where the model looks for it) — all computed in the browser in ~1 second.

Option B — Run the full Gradio app (real Grad-CAM)

pip install -r requirements.txt
python app_gradio.py           # opens http://127.0.0.1:7860

Weights (bt_resnet50_model.pt) auto-download from Google Drive on first run. Override with the BT_MODEL_URL / BT_GDRIVE_ID environment variables.

☁️ Deploy to Hugging Face Spaces (free Static Space)

On the free plan, HF Spaces only offers Static Spaces (Gradio/Docker require PRO). This repo targets exactly that: the YAML block at the top of this README sets sdk: static, and the models run in the browser — no server needed.

This repo is already built and committed (git + LFS initialised, fp16 models tracked, main branch). To deploy, just create a Static Space and push:

# 1. Create a new Space → SDK: Static → https://huggingface.co/new-space
# 2. Add it as a remote and push (LFS uploads the fp16 .onnx models):
git remote add space https://huggingface.co/spaces/<your-username>/<space-name>
git push space main

HF then serves index.html at the Space URL; the browser fetches the two fp16 ONNX models and runs inference locally. Because everything is static, the Space is free and always-on (no cold starts).

Sizes: the fp16 models (~172 MB ViT + ~47 MB ResNet ≈ 220 MB) download to each visitor once, then are cached. The fp32 fallbacks are .gitignored to keep the repo lean; add them back (edit .gitignore) for older browsers that can't run fp16 in WASM.

Rebuilding the assets from scratch (optional)

The .onnx models and JSON assets are already committed. To regenerate them (e.g. after changing models):

pip install -r requirements-export.txt
python export_onnx.py       # ViT + ResNet → ONNX (fp16 + fp32) + labels.json + cam_weights.json
python compute_stats.py     # reference.json + advanced.json (embeddings + OOD threshold)
python benchmark.py         # (optional) accuracy on a held-out test set

🖥️ App Preview

┌───────────────────────────────┬──────────────────────────────────┐
│  1 · Choose an MRI scan       │  2 · Result                       │
│                               │                                   │
│   [ Click to upload / drag ]  │   🟡  Meningioma                  │
│                               │   Confidence: 35.7%               │
│   Or try an example:          │                                   │
│   [▪][▪][▪][▪][▪]             │   Meningioma  ▓▓▓▓░░░░░░  35.7%    │
│                               │   Glioma      ▓▓▓░░░░░░░  25.7%    │
│   ┌─────────┬─────────┐       │   No tumor    ▓▓░░░░░░░░  22.1%    │
│   │  Input  │   CAM   │       │   Pituitary   ▓▓░░░░░░░░  16.5%    │
│   │  (MRI)  │(heatmap)│       │   ↑ click a class to switch CAM    │
│   └─────────┴─────────┘       │   [ Analyze ]   opacity ▓▓▓░░      │
│                               │   ⚠️ Educational use only.        │
└───────────────────────────────┴──────────────────────────────────┘
       Everything runs in the browser — the image never leaves the device.

🛠️ Tech Stack

📜 Credits & Licenses

This application — the in-browser inference pipeline, Class Activation Mapping, test-time augmentation, uncertainty/OOD tooling, retrieval, UI, and export/verification scripts — is © 2026 SDLC Corp, released under the Apache License 2.0.

It builds on the following third-party components, used under their licenses (this section serves as the attribution NOTICE required by Apache-2.0 §4):

The model weights are third-party pretrained artifacts used under the Apache-2.0 license; SDLC Corp does not claim to have trained them and has not independently validated them for clinical use.

Further reading:

• —Deep Residual Learning for Image Recognition — He et al. (2015)
• —Grad-CAM / CAM — Zhou et al. (2016)
• —Energy-based / feature-space OOD detection — Lee et al. (2018)

<div align="center">

© 2026 SDLC Corp · For research &amp; educational use only — not a medical device.

</div>