{"id":48852144,"url":"https://github.com/kiselyovd/brain-mri-segmentation","last_synced_at":"2026-04-15T10:03:15.842Z","repository":{"id":350532089,"uuid":"665462836","full_name":"kiselyovd/brain-mri-segmentation","owner":"kiselyovd","description":"Binary brain-tumor MRI segmentation (LGG) — SegFormer-B2 + U-Net baseline, FastAPI serving, HF Hub model","archived":false,"fork":false,"pushed_at":"2026-04-14T18:02:44.000Z","size":1958,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-14T20:07:45.367Z","etag":null,"topics":["brain-mri","deep-learning","fastapi","medical-imaging","pytorch","pytorch-lightning","segformer","segmentation","semantic-segmentation","unet"],"latest_commit_sha":null,"homepage":"https://kiselyovd.github.io/brain-mri-segmentation/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kiselyovd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-07-12T09:00:32.000Z","updated_at":"2026-04-14T18:02:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kiselyovd/brain-mri-segmentation","commit_stats":null,"previous_names":["kiselyovd/cerebro-net","kiselyovd/brain-mri-segmentation"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/kiselyovd/brain-mri-segmentation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiselyovd%2Fbrain-mri-segmentation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiselyovd%2Fbrain-mri-segmentation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiselyovd%2Fbrain-mri-segmentation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiselyovd%2Fbrain-mri-segmentation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kiselyovd","download_url":"https://codeload.github.com/kiselyovd/brain-mri-segmentation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiselyovd%2Fbrain-mri-segmentation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31835821,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T07:17:56.427Z","status":"ssl_error","status_checked_at":"2026-04-15T07:17:30.007Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["brain-mri","deep-learning","fastapi","medical-imaging","pytorch","pytorch-lightning","segformer","segmentation","semantic-segmentation","unet"],"created_at":"2026-04-15T10:03:11.230Z","updated_at":"2026-04-15T10:03:15.805Z","avatar_url":"https://github.com/kiselyovd.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# brain-mri-segmentation\n\n[![CI](https://github.com/kiselyovd/brain-mri-segmentation/actions/workflows/ci.yml/badge.svg)](https://github.com/kiselyovd/brain-mri-segmentation/actions/workflows/ci.yml)\n[![Docs](https://github.com/kiselyovd/brain-mri-segmentation/actions/workflows/docs.yml/badge.svg)](https://kiselyovd.github.io/brain-mri-segmentation/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/)\n[![HF Model](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Model-yellow)](https://huggingface.co/kiselyovd/brain-mri-segmentation)\n\nBinary brain-tumor segmentation on MRI slices — fine-tuned **SegFormer-B2** as the main model and a hand-rolled **U-Net** as a reproducible baseline, both trained on the Mateusz Buda LGG (TCGA) dataset with a strict patient-level split to prevent data leakage.\n\n**Russian:** [README.ru.md](README.ru.md) · **Docs:** [kiselyovd.github.io/brain-mri-segmentation](https://kiselyovd.github.io/brain-mri-segmentation/) · **Model:** [kiselyovd/brain-mri-segmentation](https://huggingface.co/kiselyovd/brain-mri-segmentation)\n\n## Dataset\n\nMateusz Buda's [LGG MRI Segmentation](https://www.kaggle.com/datasets/mateuszbuda/lgg-mri-segmentation) on Kaggle — 110 patients, 3,929 paired FLAIR slices with binary tumor masks from The Cancer Genome Atlas (TCGA). `src/brain_mri_segmentation/data/prepare.py` performs a **patient-level 80/10/10 split** (88/11/11 patients), so no patient appears in more than one partition.\n\nResulting slice counts: **3,133 train / 409 val / 387 test**.\n\n## Results\n\nTest-set metrics after full training (fill in with real numbers from `reports/metrics.json`):\n\n| Model | Dice | IoU | Pixel Accuracy |\n|---|---|---|---|\n| **SegFormer-B2** (main) | **65.5%** | **66.2%** | **99.73%** |\n| U-Net 4-level baseline | 51.9% | 57.7% | 99.66% |\n\nFull per-slice report lives in `reports/metrics.json` after running evaluation.\n\n## Quick Start\n\n```bash\n# 1. Install\nuv sync --all-groups\n\n# 2. Sync Kaggle dataset into data/raw/ (once)\nbash scripts/sync_data.sh /path/to/lgg-mri-segmentation\n\n# 3. Build processed splits\nuv run python -m brain_mri_segmentation.data.prepare --raw data/raw --out data/processed\n\n# 4. Train (main model on GPU)\nmake train\n\n# 5. Evaluate on test split\nmake evaluate\n\n# 6. Serve the model locally\nmake serve\n# or\ndocker compose up api\n```\n\n## Full Training Commands\n\n**Main — SegFormer-B2:**\n\n```bash\nuv run python -m brain_mri_segmentation.training.train experiment=sota\n```\n\n**Baseline — U-Net (4 levels, 32→256 ch):**\n\n```bash\nuv run python -m brain_mri_segmentation.training.train \\\n  model=baseline \\\n  trainer.max_epochs=30 \\\n  trainer.output_dir=artifacts/baseline\n```\n\nEvery run is tracked with MLflow under `./mlruns/`; launch `mlflow ui --backend-store-uri ./mlruns` to inspect.\n\n## Inference\n\n```python\nfrom huggingface_hub import snapshot_download\n\nfrom brain_mri_segmentation.inference.predict import load_model, predict\n\nweights_dir = snapshot_download(\"kiselyovd/brain-mri-segmentation\")\nmodel = load_model(f\"{weights_dir}/best.ckpt\")\nresult = predict(model, \"slice.tif\")\nprint(f\"Mask: {len(result['mask'])}×{len(result['mask'][0])}\")\n```\n\n`result[\"mask\"]` is a 2-D binary array (H × W) aligned to the input slice.\n\n## Serving\n\n```bash\ndocker compose up api\ncurl -X POST -F \"file=@slice.tif\" http://localhost:8000/segment\n```\n\nEndpoints:\n\n| Method | Path | Purpose |\n|---|---|---|\n| `GET` | `/health` | Liveness probe |\n| `POST` | `/segment` | Multipart TIFF/PNG → JSON mask |\n| `GET` | `/metrics` | Prometheus metrics |\n\nEvery response carries an `X-Request-ID` header for log correlation.\n\n## Project Structure\n\n```\nsrc/brain_mri_segmentation/\n├── data/           # MRIDataModule, MRIDataset, prepare.py (patient-level split)\n├── models/         # factory.py, lightning_module.py, unet.py\n├── training/       # Hydra entrypoint\n├── evaluation/     # Dice / IoU / pixel-accuracy report\n├── inference/      # load_model + predict\n├── serving/        # FastAPI app\n└── utils/          # logging, seeding, HF Hub helpers\nconfigs/            # Hydra configs (data / model / trainer / experiment)\ndata/\n├── raw/            # original Kaggle download (images + masks per patient)\n└── processed/      # train / val / test splits\ndocs/               # MkDocs site sources\ntests/              # pytest suite\n```\n\n## Intended Use\n\nResearch and educational only. **Not a medical device.** Predictions must not be used for clinical decisions.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiselyovd%2Fbrain-mri-segmentation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkiselyovd%2Fbrain-mri-segmentation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiselyovd%2Fbrain-mri-segmentation/lists"}