PRISM-DR

KO | EN

gitlite — search

#hacktoberfest #react #ai #typescript #llm #golang #rust #deep-learning #linux #macos #nodejs #java #cli #openai

(★ 6)

PRISM-DR: per-lesion YOLO system for detecting diabetic retinopathy lesions (MA, HE, EX, SE) in color fundus images. M.Sc. thesis code (Baskent University, 2026).

PRISM-DR Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# PRISM-DR

**P**er-lesion **R**etinal **I**nference with **S**pecialist **M**odels for **D**iabetic **R**etinopathy

*M.Sc. thesis: "Detection of Diabetic Retinopathy Lesions in Color Fundus Images Using Object Detection"*

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://raw.githubusercontent.com/zubeyrozeren/PRISM-DR/main/LICENSE)
[![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)

**PRISM-DR** is an end-to-end deep-learning system that detects the four primary diabetic retinopathy (DR) lesions — **microaneurysms (MA)**, **hemorrhages (HE)**, **hard exudates (EX)**, and **soft exudates (SE)** — in color fundus images. Instead of forcing one detector to learn all four lesions, the system trains an **independent, lesion-specific YOLO pipeline** for each lesion type and fuses the outputs with a clinically informed post-processing stage.

This repository accompanies the paper **PRISM-DR: Per-lesion Retinal Inference with Specialist Models for Diabetic Retinopathy** (Zübeyr Özeren, Tansel Uyar) and the underlying M.Sc. thesis (Başkent University, Department of Biomedical Engineering, 2026). It contains the full training, inference, evaluation, and figure-generation code.

> **Paper:** [arXiv:2607.19864](https://arxiv.org/abs/2607.19864) · [doi:10.48550/arXiv.2607.19864](https://doi.org/10.48550/arXiv.2607.19864)
> **Trained weights:** released as a [GitHub Release](../../releases) (see [Model weights](#model-weights)).

---

## Highlights

- **Lesion-specific design.** Each lesion gets its own architecture, tiling strategy, augmentation policy, ensemble method, and confidence threshold — chosen to match that lesion's size, morphology, and sample count.
- **Per-lesion architecture search.** Five YOLO generations (YOLOv5, YOLOv8, YOLO11, YOLO12, YOLO26) are compared under identical conditions; the best generation is selected per lesion.
- **Per-lesion augmentation tuning.** Data-augmentation parameters are optimized separately for each lesion with [Optuna](https://optuna.org/) Bayesian optimization.
- **Fast tiled inference.** A custom batched tiling-inference routine runs roughly **4.8× faster** than standard slice-aided inference.
- **Clinically informed fusion.** An inter-lesion suppression (ILS) step (size-based for the MA–HE red-lesion pair, SE-priority for the EX–SE bright-lesion pair) resolves overlapping detections from different models.
- **Cross-dataset generalization.** Evaluated on e-ophtha, DDR, and TJDR with **no fine-tuning**.

## Results

Final system on the **IDRiD test set** (27 held-out images), reported per lesion after the full pipeline (lesion-specific model → cross-fold ensemble → inter-lesion suppression):

| Lesion | Architecture | Inference | Ensemble | AP@50 | F1 |
|--------|--------------|-----------|----------|:-----:|:---:|
| MA — Microaneurysms | YOLOv5nu (P2 head) | Tiled 1280² | Majority vote (3/5) | 0.554 | 0.536 |
| HE — Hemorrhages    | YOLO12n            | Tiled 1280² | Majority vote (3/5) | 0.485 | 0.480 |
| EX — Hard exudates  | YOLOv5nu           | Tiled 1280² | Majority vote (3/5) | 0.561 | 0.595 |
| SE — Soft exudates  | YOLO26n            | Full image  | Weighted box fusion | 0.510 | 0.505 |
| **Overall**         |                    |             |                     | **mAP@50 0.527** | **0.529** |

**External validation (zero fine-tuning):** AP@50 of **0.628** for MA on e-ophtha; mAP@50 of 0.154 on DDR and 0.295 on TJDR (best resolution mode).

End-to-end inference takes ≈83 s for the 27-image IDRiD test set (≈3 s/image) on an RTX 4070 + Ryzen 5 7600X.

See [`docs/results.md`](docs/results.md) for the full per-stage tables, ablations, and external-validation breakdown.

## Method overview

```mermaid
flowchart TD
 A[Raw color fundus image] --> B[ROI crop YOLOv8n detector]
 B --> C[Preprocessing green channel + median filter + CLAHE + resize]
 C --> D{Four parallel lesion pipelines}
 D --> MA[MA &middot; YOLOv5nu P2 tiled 1280&sup2;]
 D --> HE[HE &middot; YOLO12n tiled 1280&sup2;]
 D --> EX[EX &middot; YOLOv5nu tiled 1280&sup2;]
 D --> SE[SE &middot; YOLO26n full image]
 MA --> E1[5-fold ensemble majority vote]
 HE --> E2[5-fold ensemble majority vote]
 EX --> E3[5-fold ensemble majority vote]
 SE --> E4[5-fold ensemble weighted box fusion]
 E1 --> F[Inter-lesion suppression MA&ndash;HE size rule, EX&ndash;SE priority rule]
 E2 --> F
 E3 --> F
 E4 --> F
 F --> G[Final per-lesion detections]
```

A detailed description of every stage and how it maps to the paper is in [`docs/method.md`](docs/method.md).

## Repository structure

```
.
├── evaluation/                 # Inference & evaluation framework (CLI + importable package)
│   ├── main.py                 #   entry point: 5-fold CV / test / ensemble / image-level
│   ├── confusion_analysis.py   #   inter-lesion confusion analysis
│   ├── configs/inference.yaml  #   per-lesion inference configuration
│   └── src/                    #   inference engines, metrics, ensembles, suppression, viz
├── pipeline/
│   ├── data_preparation/       # ROI crop, mask→bbox, stratified 5-fold split, dataset build
│   ├── training/               # per-lesion training + Optuna augmentation search (notebook)
│   ├── inference/              # tiled / SAHI inference runners
│   ├── ablation/               # tiling, augmentation, head, and YOLO-vs-SAHI comparisons
│   ├── analysis/               # lesion-size / box / tile-overlap statistics
│   └── figures/                # publication figure generators
├── docs/                       # method, datasets, and results documentation
├── scripts/download_weights.py # fetch trained weights from the GitHub Release
├── requirements.txt
├── CITATION.cff
├── THIRD_PARTY_NOTICES.md
└── LICENSE
```

## Installation

```bash
git clone https://github.com/zubeyrozeren/PRISM-DR.git
cd PRISM-DR

python -m venv .venv
# Windows: .venv\Scripts\activate   |   Linux/macOS: source .venv/bin/activate

pip install -r requirements.txt
```

Requires Python 3.8+ and PyTorch 2.0+. A CUDA-capable GPU is recommended for training and tiled inference. `ultralytics` is pinned to `8.4.8`, the version used in the thesis (and the one that supports the YOLO26 architecture used for SE).

**Minimum hardware**
- **GPU:** an NVIDIA CUDA GPU with **≥ 4 GB VRAM** — or **CPU-only**, which is fully supported but substantially slower.
- **CPU:** any modern quad-core.
- **Disk:** **~10 GB** (≈ 5.5 GB Python environment + ~0.1 GB weights + your chosen dataset).

## Data

The four public datasets used in this work are **not redistributed here** — download them from their original sources and accept their licenses. Expected folder layout and per-dataset notes are in [`docs/datasets.md`](docs/datasets.md).

| Dataset | Role | Lesions | Link |
|---------|------|---------|------|
| IDRiD (Segmentation) | Train + test | MA, HE, EX, SE | <https://idrid.grand-challenge.org/> |
| e-ophtha | External validation | MA, EX | <https://www.adcis.net/en/third-party/e-ophtha/> |
| DDR | External validation | MA, HE, EX, SE | <https://github.com/nkicsl/DDR-dataset> |
| TJDR | External validation | MA, HE, EX, SE | <https://github.com/NekoPii/TJDR> |

## Model weights

Trained per-lesion weights (5 folds × 4 lesions) and the ROI-cropper model are published on the [Releases page](../../releases). Download and place them with:

```bash
python scripts/download_weights.py --dest .
```

This recreates the `Final Models/` and `ROI_Cropper_Results/` layout that the configs expect.

## Usage

All commands assume your working directory contains the datasets and weights in the documented layout (set `base_dir` in `evaluation/configs/inference.yaml`, or run from that directory).

**Reproduce evaluation on the IDRiD test set:**
```bash
cd evaluation
python main.py --lesion all --image-level --ensemble --test --inter-class-nms --device cuda
```

**Evaluate a single lesion with cross-fold ensembling:**
```bash
python main.py --lesion MA --ensemble --device cuda
```

**Inter-lesion confusion analysis (e.g. how many HE the MA model fires on):**
```bash
python confusion_analysis.py --pred-lesion MA --gt-lesion HE --bidirectional
```

See [`evaluation/README.md`](evaluation/README.md) for the full CLI reference, and [`docs/method.md`](docs/method.md) for the training-pipeline order (`pipeline/data_preparation` → `pipeline/training` → `evaluation`).

## Citation

If you use this code, please cite the paper. See [`CITATION.cff`](CITATION.cff).

```bibtex
@article{ozeren2026prismdr,
  title   = {PRISM-DR: Per-lesion Retinal Inference with Specialist Models for Diabetic Retinopathy},
  author  = {{\"O}zeren, Z{\"u}beyr and Uyar, Tansel},
  journal = {arXiv preprint arXiv:2607.19864},
  year    = {2026},
  doi     = {10.48550/arXiv.2607.19864},
  url     = {https://arxiv.org/abs/2607.19864}
}
```

## License and attributions

Code in this repository is released under the [MIT License](LICENSE).

This work builds on third-party software with their own licenses — most importantly **Ultralytics YOLO (AGPL-3.0)** and **SAHI (MIT)** — and on public datasets with their own usage terms. Review [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) before redistributing or using this work commercially.

## Acknowledgements

Thesis advisor: Asst. Prof. Tansel Uyar (Başkent University). Built with [Ultralytics](https://github.com/ultralytics/ultralytics), [SAHI](https://github.com/obss/sahi), [Optuna](https://github.com/optuna/optuna), and [ensemble-boxes](https://github.com/ZFTurbo/Weighted-Boxes-Fusion).

PRISM-DR

PRISM-DR Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

PRISM-DR

PRISM-DR Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README