Created by Eng. Salman Dawod • YouTube: bioeng.y
A desktop application for brain-tumour MRI research: manage patients and scans (PNG, JPG, DICOM, NIfTI), segment tumours with a MATLAB or built-in Python image-processing pipeline, classify slices with a small deep-learning model and see where it looked with Grad-CAM, compare scans over time, run batch analyses and export PDF reports and Excel workbooks. Interface in English and Arabic, light and dark themes.
⚠️ Research and education only — not a medical device. Segmentations, measurements, AI classifications and heatmaps are decision-support estimates and must be reviewed by a qualified radiologist.
| Page | What it does |
|---|---|
| Dashboard | Patient / study / analysis counts, AI findings per class, recent analyses, quick actions |
| Patients | Add, search, edit and delete patients (deleting also removes their images and results) |
| MRI Studies | Upload PNG / JPG / DICOM / NIfTI; pick the slice of a 3-D volume; pixel spacing is read so areas are in mm² |
| Image Processing | Grayscale → skull stripping → 9 filters → 8 segmentation methods → largest-region statistics → 7 edge detectors. Runs on MATLAB or the built-in Python engine. Mask overlay with opacity slider, 4-way method comparison |
| AI Analysis | MobileViT classifier: glioma, meningioma, pituitary, no tumour, per-class probabilities and a Grad-CAM heatmap |
| Batch Analysis | AI and/or processing for one patient, all patients or a whole folder; results table; export Excel / CSV; export the full database |
| Comparison | Two studies side by side (original, mask overlay, heatmap, mask, preprocessed) with change in region size |
| Reports | Patient report preview and PDF export with heatmaps and overlays (in the interface language) |
| Settings | Language (English / العربية), theme (light / dark), password, processing engine, MATLAB path + test, AI model |
 |
 |
 |
 |
Download BrainTumorAI-1.1.0-win64.zip from the Releases page, unzip it anywhere you can write
(e.g. Documents), and double-click BrainTumorAI.exe. The AI model is included, so it works offline.
Keep the whole folder together — your database, uploads and reports are stored inside it.
To build the exe yourself: py -3 -m pip install pyinstaller then py -3 packaging/build_exe.py.
Requires Python 3.10+ (Windows, macOS or Linux). MATLAB is optional.
git clone https://github.com/salmand-dev/BrainTumorSystem.git
cd BrainTumorSystem
python -m pip install -r requirements.txt
python main.pyOn Windows, if python opens the Microsoft Store, use py -3 instead.
First sign-in: admin / admin123 — you will be asked to choose a new password immediately. Researchers can also create their own account from the sign-in screen.
samples/ contains synthetic brain phantoms (no real patient data):
| File | What it shows |
|---|---|
phantom_tumor.dcm |
DICOM with 0.5 mm pixel spacing → areas in mm² |
phantom_volume.nii.gz |
16-slice NIfTI volume → slice picker |
phantom_tumor.png, phantom_no_tumor.png |
plain images; also a quick folder for Batch Analysis |
Add a patient → MRI Studies → Upload a sample → Image Processing (Region Growing works well) and AI Analysis.
The AI model was trained on real MRI, so its prediction on synthetic phantoms is meaningless — use real,
de-identified scans to evaluate it. Regenerate the samples with python tools/make_samples.py.
| Engine | When it is used | Notes |
|---|---|---|
| MATLAB | MATLAB R2019a+ with Image Processing Toolbox found (Settings → Test MATLAB) | matlab_scripts/pipeline/run_pipeline.m, called through JSON job files |
| Python | MATLAB not installed, or chosen explicitly | app/services/python_pipeline.py — scikit-image / SciPy port of the same methods |
| Auto (default) | MATLAB if available, otherwise Python |
Both engines implement the same steps and produce the same outputs; on the test tumour image Region Growing gives 3 841 px (MATLAB) vs 3 862 px (Python) with an identical bounding box.
Jesteban247/mobilevit_small-brain_tumor — Apple
MobileViT-small fine-tuned on the BRISC2025 brain-MRI dataset (Apache-2.0, ~20 MB, downloaded once and cached).
Author-reported test results: accuracy 0.98, macro F1 0.957 (not independently verified).
Works best on original, unprocessed axial slices; the app always classifies the original image.
The heatmap is Grad-CAM (Selvaraju et al., 2017) computed on the fusion convolution of the second-to-last MobileViT block (16×16 map), which concentrated ~8× more heat inside a known tumour than outside it — the final 8×8 layer was too coarse. It shows where the model looked, not the tumour border. Any Hugging Face image-classification model can be configured in Settings → AI model.
python -m pip install -r requirements-dev.txt
pytest # 54 tests; AI tests run only when the model is cached
python tools/extract_strings.py # check that every UI string has an Arabic translationGitHub Actions runs the test suite on every push (.github/workflows/tests.yml).
See CONTRIBUTING.md and CHANGELOG.md.
main.py entry point (theme, language, login → main window)
config/config.yaml settings (database, MATLAB, engine, AI model, language, theme)
app/core/ validated config, logger, password hashing, i18n + Arabic table, credits
app/database/ SQLAlchemy models + automatic column migration
app/services/ patients, MRI import (DICOM/NIfTI), MATLAB bridge, Python pipeline,
AI + Grad-CAM, analysis history, batch & Excel export, PDF reports
app/ui/ pages and widgets (viewer with overlays, charts, study picker, workers)
matlab_scripts/ MATLAB pipeline and algorithm functions
samples/ synthetic phantoms (PNG, DICOM, NIfTI)
tests/ pytest suite
tools/ sample generator, translation checker
docs/ screenshots, Arabic description of the MATLAB scripts
data/ database/ reports/ logs/ runtime output (git-ignored: may contain patient data)
MatlabService writes <job>_in.json (image path, methods, output paths) and runs
matlab -batch "cd(...); run_pipeline('<job>_in.json')". The pipeline writes the processed images and
<job>_out.json (status, image paths, region area / centroid / bounding box). On failure it writes
{"status":"error","message":...} so the real reason is shown in the app.
MIT © 2026 Eng. Salman Dawod. The AI model is Apache-2.0 (downloaded from Hugging Face at run time). Not for clinical use — see the medical disclaimer in LICENSE.