Spaces:
Running on Zero
A newer version of the Gradio SDK is available:
6.8.0
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.
🌐 Live Demo
Try it now on HuggingFace Spaces:
🚀 Launch Dashboard
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 in your browser. No installation needed!
Option 2: Run Locally
If you want to run the dashboard on your own hardware:
# 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
.niior.nii.gzfile 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):
- Loading NIfTI file
- Normalizing volume
- Preparing prompt
- BrainGemma3D inference
- Formatting report
- LIME interpretability analysis
- 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
- Example:
BraTS20_Training_001_flair.nii.gz
MPI-Leipzig Mind-Brain-Body (Healthy Controls):
- Download from: MPI-Leipzig Mind-Brain-Body
- 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 for detailed evaluation.
🤝 Contributing
Found a bug or have a feature request? Contributions are welcome!
- Report Issues: GitHub Issues
- Submit PRs: GitHub Repository
🙏 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 — Medical domain language model
- Google MedSigLIP — Medical vision encoder
- Hugging Face Transformers — Model framework
🔗 Related Links
Documentation & Resources
- 🤗 Model Card: praiselab-picuslab/BrainGemma3D
- 🚀 Dashboard (This Space): BrainGemma3D-Dashboard
- 💻 GitHub Repository: PRAISELab-PicusLab/BrainGemma3D
- 📄 Paper: ArXiv (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
- MedGemma Model Family: https://huggingface.co/google/medgemma
Datasets
- BraTS 2020: 369 brain tumor MRI cases with clinical annotations from TextBraTS 2021
- Healthy Controls: 99 preprocessed healthy brain scans (skull-stripped, normalized) from MPI-Leipzig Mind-Brain-Body
Built with ❤️ for the MedGemma Impact Challenge 🏆
Advancing Medical AI with Google's Health AI Developer Foundations