---
title: BrainGemma3D
emoji: 🚀
colorFrom: gray
colorTo: blue
sdk: gradio
sdk_version: 6.6.0
app_file: app.py
pinned: false
license: cc-by-4.0
short_description: 🧠Brain Report Automation via Inflated ViT in 3D
---

# 🧠 BrainGemma3D Dashboard

Interactive web dashboard for generating medical reports from 3D brain MRI volumes (NIfTI format) using the **BrainGemma3D** model with LIME interpretability analysis.

<div align="center">
    <a href="https://huggingface.co/praiselab-picuslab/BrainGemma3D" target="_blank"><img alt="BrainGemma3D"
        src="https://img.shields.io/badge/HuggingFace-BrainGemma3D%20Model-grey?style=for-the-badge&logo=huggingface&logoSize=auto&color=gold"/></a>
    <a href="https://www.kaggle.com/code/antonioromano45/braingemma3d" target="_blank"><img alt="Kaggle Notebook"
        src="https://img.shields.io/badge/Kaggle-Notebook-20BEFF?style=for-the-badge&logo=kaggle&logoSize=auto"/></a>
    <br>
    <a href="https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview" target="_blank"><img alt="MedGemma Challenge"
        src="https://img.shields.io/badge/Kaggle-MedGemma_Impact_Challenge-blue?style=for-the-badge&logo=kaggle&logoSize=auto&color=20BEFF"/></a>
</div>

---

## 🌐 Live Demo

**Try it now on HuggingFace Spaces:**  
🚀 **[Launch Dashboard](https://huggingface.co/spaces/giuseppericcio/BrainGemma3D)**

No installation required! Simply upload your NIfTI file and get instant AI-powered radiology reports with interpretability visualizations.

---

## 📋 Features

- ✅ **Upload NIfTI files** (.nii / .nii.gz) for 3D brain MRI volumes
- ✅ **Multi-planar visualization** (Axial, Coronal, Sagittal views)
- ✅ **Automatic medical report generation** powered by BrainGemma3D
- ✅ **LIME Interpretability** - Visualize which brain regions support the diagnosis
- ✅ **PDF Export** - Professional radiology report with multi-planar reconstructions
- ✅ **Configurable parameters** (temperature, max tokens, custom instructions)
- ✅ **Real-time progress tracking** during inference
- ✅ **Responsive UI** optimized for medical imaging workflows

---

## 🚀 Quick Start

### Option 1: Use HuggingFace Spaces (Recommended)

Simply visit the [BrainGemma3D Dashboard Space](https://huggingface.co/spaces/giuseppericcio/BrainGemma3D) in your browser. No installation needed!

### Option 2: Run Locally

If you want to run the dashboard on your own hardware:

```bash
# Clone the repository
git clone https://huggingface.co/spaces/giuseppericcio/BrainGemma3D
cd BrainGemma3D

# Install dependencies
pip install -r requirements.txt

# Run the app
python app.py
```

The model will be automatically downloaded from HuggingFace on first run (~3.5 GB).

---

## 📖 How to Use

### 1. Upload NIfTI File

- Click **"Upload NIfTI File"**
- Select a `.nii` or `.nii.gz` file from your filesystem
- The file must be a 3D brain MRI volume (e.g., FLAIR, T1, T2, etc.)
- Automatic multi-planar preview will be displayed

### 2. Enter Patient Information (Optional)

For complete PDF reports, you can provide:
- Patient name
- Patient ID / MRN
- Exam date
- Referring physician
- Institution

### 3. Configure Generation Parameters (Optional)

Expand **"⚙️ Generation Parameters"** to adjust:

- **Additional Instructions**: Extra instructions or questions about the image
- **Max Tokens**: Maximum report length (50-512)
- **Temperature**: Creativity level (0.0 = deterministic, 2.0 = very creative)
- **Top-p**: Nucleus sampling (0.9 recommended)
- **Repetition Penalty**: Penalty for repetitions (1.2 recommended)

### 4. Generate Report

- Click **"🚀 Generate"**
- Wait for the progress bar (7 steps):
  1. Loading NIfTI file
  2. Normalizing volume
  3. Preparing prompt
  4. BrainGemma3D inference
  5. Formatting report
  6. **LIME interpretability analysis**
  7. Completion

### 5. View Results

#### 📋 Diagnostic Report
Medical report generated in Markdown format with generation metadata

#### 🔬 LIME Interpretability

2×3 grid visualization showing:
- **Top row**: 3 original representative slices from the volume
- **Bottom row**: Same slices with LIME overlay

**Color legend:**
- 🔴 **Red** = Regions strongly supporting the diagnosis
- 🔵 **Blue** = Regions contradicting or weakening the diagnosis
- ⚪ **White/Gray** = Neutral or minimal impact

This helps understand **which brain areas influenced** the model's diagnosis.

#### 🔍 3D Volume Viewer

Explore the MRI volume interactively:
- **Axial**: Horizontal slices (top-down)
- **Coronal**: Frontal slices
- **Sagittal**: Lateral slices

Use the sliders to navigate through the slices.

### 6. Export PDF

Click **"📄 Download PDF Report"** to generate a professional radiology report with:
- Institutional header
- Patient information
- Multi-planar reconstructions
- Complete report text
- Physician signature section
- AI disclaimer

---

## 📂 Example Files

You can test the dashboard with publicly available brain MRI datasets:

### BraTS (Brain Tumors):
- Download from: [BraTS 2020](https://www.kaggle.com/datasets/awsaf49/brats20-dataset-training-validation)
- Example: `BraTS20_Training_001_flair.nii.gz`

### MPI-Leipzig Mind-Brain-Body (Healthy Controls):
- Download from: [MPI-Leipzig Mind-Brain-Body](https://openneuro.org/datasets/ds000221/versions/00002)
- Requires registration (free for researchers)

---

## 🛠️ Technical Details

### Hardware Requirements (Local Installation)

| Component | Minimum | Recommended |
|-----------|---------|-------------|
| **GPU** | 8GB VRAM (e.g., RTX 2080) | 16GB+ VRAM (e.g., A100, RTX 3090) |
| **RAM** | 16GB | 32GB+ |
| **Storage** | 10GB free | 20GB+ free |

**Note:** HuggingFace Spaces runs on shared infrastructure with resource limits. For heavy usage or faster inference, consider running locally.

### Generation Times (HF Spaces)

| Component | Typical Time | Notes |
|-----------|-------------|-------|
| **Report Generation** | 10-15s | BrainGemma3D inference |
| **LIME Analysis** | 2-3 min | 50 samples (configurable) |
| **PDF Export** | <1s | Report rendering |
| **TOTAL** | ~2.5-3.5 min | Complete workflow |

*Times may vary based on Space availability and queue status.*

### LIME Samples vs Quality

| `lime_samples` | Time | Explanation Quality |
|----------------|------|---------------------|
| 10 | ~30s | Low (quick testing) |
| 25 | ~1 min | Medium (acceptable) |
| **50** | **~2 min** | **Good (dashboard default)** |
| 100 | ~4 min | High (research grade) |

*Dashboard uses 50 samples to balance speed and quality. Research papers typically use 100.*

---

## ⚠️ Limitations & Best Practices

### File Size Limits
- HuggingFace Spaces has upload limits (typically ~100-200 MB per file)
- Most NIfTI files are 5-50 MB, so this should not be an issue
- For very large files, consider running locally

### Supported MRI Sequences
- ✅ **FLAIR** (Recommended)
- ✅ T1-weighted
- ✅ T2-weighted  
- ✅ T1-contrast enhanced
- ⚠️ Other sequences may work but are not validated

### Privacy & Security
- **Do NOT upload** files containing identifiable patient information (PHI)
- Files uploaded to HuggingFace Spaces are processed in memory and not permanently stored
- For clinical data, always run locally or use de-identified data
- Comply with HIPAA, GDPR, and local data protection regulations

---

## 🔒 Medical Disclaimer

⚠️ **IMPORTANT**: This dashboard is for **research and educational purposes only**.

- ❌ **NOT for clinical diagnosis** or patient care decisions
- ❌ **NOT a substitute** for professional medical judgment
- ❌ **NOT validated** for clinical use or regulatory approval
- ⚠️ **LIME interpretability** is explanatory, not diagnostic

AI-generated reports may contain errors, hallucinations, or incomplete information. LIME visualizations show which regions influenced the model but do not guarantee clinical relevance.

**Always consult qualified healthcare professionals for medical diagnosis and treatment.**

---

## 📊 Performance Benchmarks

### Accuracy Metrics (BraTS 2020 dataset)

| Metric | BrainGemma3D | Baseline |
|--------|--------------|----------|
| **BLEU-4** | 0.287 | 0.234 |
| **METEOR** | 0.412 | 0.368 |
| **CIDEr** | 1.456 | 1.102 |
| **Clinical Accuracy** | 89.3% | 76.8% |

*See [Model Card](https://huggingface.co/praiselab-picuslab/BrainGemma3D) for detailed evaluation.*

---

## 🤝 Contributing

Found a bug or have a feature request? Contributions are welcome!

- **Report Issues**: [GitHub Issues](https://github.com/PRAISELab-PicusLab/BrainGemma3D/issues)
- **Submit PRs**: [GitHub Repository](https://github.com/PRAISELab-PicusLab/BrainGemma3D)

---

## 🙏 Acknowledgements

This project was developed by:

**Mariano Barone** · **Francesco Di Serio** · **Giuseppe Riccio** · **Antonio Romano** · **Vincenzo Moscato**

*Department of Electrical Engineering and Information Technology*  
*University of Naples Federico II, Italy*

### Built With
- [Google MedGemma](https://huggingface.co/google/medgemma-1.5-4b-it) — Medical domain language model
- [Google MedSigLIP](https://huggingface.co/google/medsiglip-base-patch16-448) — Medical vision encoder
- [Hugging Face Transformers](https://huggingface.co/docs/transformers) — Model framework

---

## 🔗 Related Links

### Documentation & Resources
- **🤗 Model Card**: [praiselab-picuslab/BrainGemma3D](https://huggingface.co/praiselab-picuslab/BrainGemma3D)
- **🚀 Dashboard (This Space)**: [BrainGemma3D-Dashboard](https://huggingface.co/spaces/praiselab-picuslab/BrainGemma3D-Dashboard)
- **💻 GitHub Repository**: [PRAISELab-PicusLab/BrainGemma3D](https://github.com/PRAISELab-PicusLab/BrainGemma3D)
- **📄 Paper**: [ArXiv](https://arxiv.org/abs/XXXX.XXXXX) *(Coming soon)*

### Technical References
- **Gradio Documentation**: https://gradio.app/docs
- **NiBabel (NIfTI Processing)**: https://nipy.org/nibabel
- **LIME Paper**: ["Why Should I Trust You?" - Ribeiro et al., 2016](https://arxiv.org/abs/1602.04938)
- **MedGemma Model Family**: https://huggingface.co/google/medgemma

### Datasets
- **[BraTS 2020](https://www.kaggle.com/datasets/awsaf49/brats20-dataset-training-validation)**: 369 brain tumor MRI cases with clinical annotations from [TextBraTS 2021](https://github.com/Jupitern52/TextBraTS)
- **Healthy Controls**: 99 preprocessed healthy brain scans (skull-stripped, normalized) from [MPI-Leipzig Mind-Brain-Body](https://openneuro.org/datasets/ds000221/versions/00002)

---

<div align="center">
    <p><i>Built with ❤️ for the <a href="https://www.kaggle.com/competitions/med-gemma-impact-challenge/overview">MedGemma Impact Challenge</a> 🏆</i></p>
    <p><i>Advancing Medical AI with Google's Health AI Developer Foundations</i></p>
</div>