Metadata-Version: 2.4
Name: yolo-mslesseg
Version: 0.1.3
Summary: Automatic multiple sclerosis lesion segmentation in MRI using YOLO11-seg
Author: Sebastián Rozenblum
License-Expression: MIT
Project-URL: Repository, https://github.com/srozenblum/YOLO-MSLesSeg
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.1
Requires-Dist: opencv-python>=4.11
Requires-Dist: nibabel>=5.3
Requires-Dist: matplotlib>=3.10
Requires-Dist: ultralytics>=8.3
Requires-Dist: requests>=2.32
Requires-Dist: tqdm>=4.67
Requires-Dist: pyyaml>=6.0
Requires-Dist: scipy>=1.16
Requires-Dist: scikit-learn>=1.5
Requires-Dist: pandas>=2.2
Requires-Dist: polars>=1.35
Requires-Dist: psutil>=7.1
Dynamic: license-file

![Python](https://img.shields.io/badge/Python-3.10%2B-blue?logo=python&logoColor=white)
![License](https://img.shields.io/badge/License-MIT-green)

# 🧠💻 YOLO-MSLesSeg: Automatic Multiple Sclerosis Lesion Segmentation with YOLO11-seg

**yolo_mslesseg** is a Python package that provides a complete pipeline for the automatic segmentation and evaluation of
multiple sclerosis
lesions in MRI images, using
[**YOLO11-seg**](https://docs.ultralytics.com/models/yolo11/) models.
The system is based on the
[**MSLesSeg Competition**](https://www.nature.com/articles/s41597-025-05250-y) (ICPR 2024) dataset, an international
benchmark for the validation of automatic methods for multiple sclerosis lesion segmentation.

The package introduces an approach that combines **deep learning models** with different **image enhancement
techniques** as a preprocessing stage, with the goal of quantifying lesions consistently and reducing
the variability associated with manual segmentation.

## Table of Contents

- [Visual examples](#visual-examples)
- [Pipeline overview](#pipeline-overview)
- [Installation](#installation)
- [Repository structure](#repository-structure)
- [Running the pipeline](#running-the-pipeline)
- [References](#references)
- [License](#license)
- [Citation](#citation)

---

<a id="visual-examples"></a>

## Visual Examples

Below are representative examples of the outputs generated by the pipeline. These visualisations allow a direct
appreciation of the type of segmentations produced by the model and their anatomical consistency across the
different viewing planes. A GIF is also included that traverses all slices of a patient,
showing the consistency of predictions across the entire volume.

### Segmentation across the three anatomical planes

The following example corresponds to a reference patient (P1) and shows the overlay of the automatic segmentation
on the FLAIR image in the axial, coronal, and sagittal planes.

<p align="center">
  <img src="https://raw.githubusercontent.com/srozenblum/YOLO-MSLesSeg/main/docs/images/P1_FLAIR_103.png" height="270">
  <img src="https://raw.githubusercontent.com/srozenblum/YOLO-MSLesSeg/main/docs/images/P1_FLAIR_73.png" height="270">
  <img src="https://raw.githubusercontent.com/srozenblum/YOLO-MSLesSeg/main/docs/images/P1_FLAIR_119.png" height="270">
</p>

### Complete patient sequence

The following animation shows the segmentation generated for another reference patient (P42) across all slices
of the volume in the axial plane.

<p align="center">
  <img src="https://raw.githubusercontent.com/srozenblum/YOLO-MSLesSeg/main/docs/images/P42_FLAIR.gif" width="350">
</p>


---

<a id="pipeline-overview"></a>

## Pipeline Overview

The complete process consists of eight sequential stages,
automated via the `run_pipeline.py` script:

0. Download and preparation of the official MSLesSeg dataset.
1. Preprocessing and slice extraction in a format compatible with the YOLO model.
2. Training of the YOLO11-seg model (_optional_).
3. Generation of two-dimensional predictions.
4. Reconstruction of three-dimensional volumes from predicted slices.
5. Combination of volumes predicted across different planes (consensus).
6. Quantitative evaluation using performance metrics.
7. Computation of global experiment results.

Each module can be executed independently or through the global pipeline,
ensuring flexibility for debugging or experimentation.

---

<a id="installation"></a>

## Installation

### Dependencies

- Python 3.10+
- numpy, opencv-python, nibabel, matplotlib, ultralytics, requests, tqdm, pyyaml, scipy, scikit-learn, pandas, polars, psutil

> **Note:** PyTorch is required but must be installed separately to allow GPU/CPU variant selection.
> Follow the [official instructions](https://pytorch.org/get-started/locally/).

### User installation

```bash
pip install yolo-mslesseg
```

---

<a id="repository-structure"></a>

## Repository Structure

The repository is organised as follows:

```
📦 yolo_mslesseg/
│
├── run_pipeline.py          # Entry point for the full pipeline
├── 📁 configs/              # Per-stage configuration classes
├── 📁 scripts/              # Pipeline stage scripts
├── 📁 utils/                # Utilities and enhancement algorithms
└── 📁 extras/               # Additional utility scripts
```

---

<a id="running-the-pipeline"></a>

## Running the Pipeline

Once installed, run the full pipeline with:

```bash
yolo-mslesseg --plane axial --modality FLAIR --num_slices P50 --enhancement CLAHE --k_folds 5 --epochs 50 --full
```

> **Note:** `yolo-mslesseg` is a CLI-first package. The recommended way to run experiments is through the command line as shown above. Programmatic use via `import` is supported for advanced users building custom workflows.

For the full list of arguments and stage-by-stage execution, see the [GitHub repository](https://github.com/srozenblum/YOLO-MSLesSeg).

---

## References

- Ultralytics (2025). YOLO11 documentation.
- Guarnera, F., Rondinella, A., Crispino, E., et al. (2025).
  MSLesSeg: Baseline and benchmarking of a new Multiple Sclerosis lesion segmentation dataset.
  *Scientific Data*, 12, 920. https://doi.org/10.1038/s41597-025-05250-y.

---

## License

This project is licensed under the [MIT License](LICENSE).

---

## Citation

If you use this work, please cite it once a reference is available. A citable reference will be added upon
publication.

```bibtex
@article{rozenblum2026yolomslesseg,
    author = {Jiménez-Partinen, Ariadna and Rozenblum, Sebastián and
 Pascual-González, Mario and Ordóñez-Walkowiak, María Paulina and
 Guirado-Osorio, Víctor and Molina-Cabello, Miguel A.},
    title = {YOLO-MSLesSeg: Automated Multiple Sclerosis Lesion Segmentation
 in MRI with Image Enhancement Techniques},
    journal = {},
    year = {2026},
    doi = {}
}
```
